Modern CI/CD süreçlerinde uzun ömürlü AWS erişim anahtarlarını projelerde saklamak hem riskli hem de yönetimi zahmetli. OpenID Connect (OIDC) sayesinde GitHub Actions, AWS’e şifresiz ve kısa ömürlü kimlik doğrulama ile bağlanabiliyor. Bu yazıda, GitHub Actions’ı kullanarak AWS’e OIDC tabanlı, güvenli ve pratik bir dağıtım hattını nasıl kuracağınızı adım adım anlatıyorum.
Özet: AWS tarafında GitHub’ı güvenilen kimlik sağlayıcısı olarak tanımlayacağız, belirli bir depo/branch için kısıtlı yetkili bir IAM rolü oluşturacağız ve GitHub Actions üzerinde bu rolü geçici olarak üstlenerek dağıtım yapacağız. Anahtar saklamaya gerek yok.
OIDC ile neden şifresiz dağıtım?
Klasik yaklaşımda, GitHub Secrets içine AWS_ACCESS_KEY_ID ve AWS_SECRET_ACCESS_KEY koyarız. Bu yöntem, anahtar sızıntısı, rotasyon zorluğu ve fazladan yetkiler gibi sorunlar yaratır. OIDC ile GitHub, çalıştırdığı iş akışı (workflow) için imzalı bir kimlik belirteci üretir; AWS bu belirteci doğrular ve yalnızca o an, o koşullarda geçerli kısa ömürlü kimlik bilgileri verir. Sonuç: Daha az gizli bilgi, daha sıkı yetkilendirme ve otomatik süre sonu.
Önkoşullar
- Bir AWS hesabı ve IAM üzerinde rol oluşturma yetkisi
- GitHub’da bir depo (public ya da private)
- Dağıtım hedefi: Örneğin S3 statik site, ECR + ECS/Fargate, ya da CloudFormation/SAM ile altyapı
AWS tarafı: IAM rolü ve güven ilişkisi (trust policy)
1) AWS IAM’de Identity providers bölümünden OpenID Connect sağlayıcısı olarak token.actions.githubusercontent.com ekleyin. Audience olarak sts.amazonaws.com kullanın.
2) Yeni bir IAM rolü oluşturun ve “Web identity” seçeneğiyle az önceki sağlayıcıyı seçin.
3) Aşağıdaki gibi bir trust policy tanımlayın. Bu örnek sadece belirli bir repo ve branch için yetki veriyor:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Federated": "arn:aws:iam::HESAP_IDNIZ:oidc-provider/token.actions.githubusercontent.com" },
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:ORGANIZASYON/DEPO_ADI:ref:refs/heads/main"
}
}
}
]
}
4) Role bağlayacağınız izinleri minimum ilke (least privilege) ile ayarlayın. Örneğin S3’e sadece belirli bir bucket’a yazma yetkisi veya ECR push izinleri. Örnek bir S3 dağıtım politikası (özet):
{
"Version": "2012-10-17",
"Statement": [
{ "Effect": "Allow", "Action": ["s3:PutObject","s3:DeleteObject"], "Resource": ["arn:aws:s3:::hedef-bucket/*"] },
{ "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::hedef-bucket"] }
]
}
GitHub tarafı: Workflow ile rolü üstlenmek
GitHub Actions, OIDC token’ı otomatik üretir. AWS ile konuşmak için aws-actions/configure-aws-credentials eylemini (action) kullanacağız ve IAM rolümüzü geçici olarak üstleneceğiz. Basit bir S3 dağıtımı örneği:
name: Deploy to S3 (OIDC)
on:
push:
branches: [ "main" ]
permissions:
id-token: write # OIDC token üretimi için şart
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Kodu çek
uses: actions/checkout@v4
- name: AWS kimlik bilgilerini yapılandır
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::HESAP_IDNIZ:role/GITHUB_OIDC_DEPLOY_ROLE
aws-region: eu-central-1
- name: Statik dosyaları derle
run: |
npm ci
npm run build
- name: S3'e senkronize et
run: |
aws s3 sync ./build s3://hedef-bucket --delete
Dikkat edilmesi gereken en kritik kısım permissions altında id-token: write yetkisinin verilmesi. Bu izin olmadan GitHub, OIDC belirteci oluşturmaz ve AWS rolünü üstlenemezsiniz.
Güvenlik ve en iyi uygulamalar
- Least privilege: Role bağlanan politikalar sadece gereken servis ve kaynaklara izin versin. “*” yerine spesifik ARN kullanın.
- Branch kısıtları: Trust policy içinde sub koşulunu belirli branch’lerle sınırlandırın (ör. refs/heads/main ve refs/tags/v*).
- Ortam ayrımı: Prod/staging için farklı rol ve politikalar tanımlayın; workflow’larda çevresel değişkenlerle hedefleri ayırın.
- Geçici kimlik: Varsayılan token süreleri kısadır. Bu, çalınsa bile etkisini sınırlar. Gereksiz session duration artırımı yapmayın.
Sık karşılaşılan hatalar ve çözümü
- AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity: Trust policy’de OIDC provider ARN’i, audience ve subject desenini kontrol edin.
- Invalid identity token: GitHub OIDC domain’i ve thumbprint otomasyonlarını doğru oluşturduğunuzdan emin olun; provider’ı tekrar eklemek çoğu kez sorunu çözer.
- Missing id-token permission: Workflow permissions kısmında id-token: write yoksa ekleyin.
- Bucket veya ECR erişim hataları: IAM rolüne eklediğiniz izin politikasının kaynak ARN’lerini ve region bilgisini doğrulayın.
Gelişmiş kullanım: ECR + ECS/Fargate dağıtımı
S3 yerine konteyner dağıtıyorsanız, aynı rol ile ecr:BatchCheckLayerAvailability, ecr:PutImage, ecr:GetAuthorizationToken gibi izinleri verip Docker imajını ECR’a push edebilir, ardından aws ecs update-service ile hizmeti yeni imaja yönlendirebilirsiniz. Tüm akış yine şifresiz ve OIDC tabanlı kalır.
Sonuç olarak, GitHub Actions + OIDC yaklaşımı, güvenliği artırırken bakım yükünü azaltır. API anahtarlarıyla uğraşmadan, denetlenebilir ve politikalarla sıkı şekilde sınırlandırılmış bir dağıtım boru hattı elde edersiniz. Yeni projelerde varsayılan tercih olarak OIDC’yi değerlendirmenizi öneririm.
