Conectar GitHub à AWS sem chaves de acesso (OIDC)

Duas direções de confiança#

Conectar um provedor Git à nuvem envolve duas relações de confiança diferentes. Numa, um sistema externo (seu CI, uma plataforma de deploy) precisa ler seus repositórios. Na outra, esse sistema precisa agir na sua conta AWS: subir imagens, atualizar serviços ou sincronizar um bucket.

Durante anos, a receita comum foi uma chave SSH pessoal para o Git e um par de access keys de um usuário IAM colado na plataforma ou nos secrets do CI. Funciona, mas deixa credenciais de longa duração espalhadas por vários sistemas.

Este guia mostra a alternativa moderna para cada direção: OpenID Connect (OIDC) para que o GitHub Actions obtenha credenciais temporárias da AWS sem guardar nenhuma chave, e chaves somente leitura ou GitHub Apps para dar acesso mínimo aos repositórios.

Por que evitar access keys#

Access keys são credenciais de longa duração associadas a um usuário IAM: um Access key ID e um Secret access key que não expiram sozinhos. A AWS recomenda, como boa prática, usar credenciais temporárias, como roles IAM, em vez de criar access keys, e avaliar as alternativas antes de gerá-las.

• Se vazarem (num log, num fork ou num print), continuam funcionando até alguém desativá-las.
• É preciso fazer a rotação manualmente, e a AWS só mostra o secret uma vez, na criação.
• Cada sistema que as armazena é mais um lugar a proteger.

Com OIDC, cada execução do workflow recebe um token assinado pelo GitHub, troca esse token por credenciais da AWS válidas por tempo limitado e não sobra nada para rotacionar.

Para se aprofundar: Acesso à sua AWS para plataforma externa com privilégio mínimo

Documentação: AWS IAM · Access keys ↗ · AWS IAM · Gerenciar access keys ↗ · AWS IAM · Boas práticas ↗

Como funciona o OIDC entre GitHub e AWS#

• O job do GitHub Actions pede ao GitHub um token JWT; para isso precisa da permissão id-token: write.
• O token traz claims sobre quem o solicita, como o repositório, a branch ou o environment, no claim sub, e a audiência no aud.
• A action configure-aws-credentials apresenta o token ao AWS STS para assumir uma role (AssumeRoleWithWebIdentity).
• O IAM compara os claims com as condições da trust policy da role. Se baterem, o STS devolve credenciais temporárias; se não, o job falha.

A segurança depende inteiramente dessas condições. O GitHub exige definir pelo menos uma para que repositórios não confiáveis não consigam obter tokens para a sua nuvem, e o IAM recomenda avaliar sempre o claim sub.

Documentação: GitHub · Sobre OIDC ↗ · GitHub · OIDC com AWS ↗

Configurar a AWS: provedor e role#

Primeiro, adicione o GitHub como provedor de identidade OIDC no IAM, com a URL https://token.actions.githubusercontent.com e a audiência sts.amazonaws.com (a usada pela action oficial). Isso é feito uma vez por conta.

Depois, crie uma role com uma trust policy que fixe organização, repositório e, melhor ainda, o environment do GitHub:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:minha-org/meu-repo:environment:prod"
        }
      }
    }
  ]
}

Evite curingas amplos como repo:minha-org/*, a menos que você realmente queira que qualquer repositório da organização assuma a role. Anexe à role só as permissões do deploy e use uma role diferente por ambiente.

Atenção a uma mudança recente: em repositórios criados depois de 15 de julho de 2026, ou que tenham optado por isso, o sub inclui identificadores imutáveis de owner e repositório (por exemplo repo:minha-org@123456/meu-repo@456789:...). Verifique qual formato o seu repositório usa antes de escrever a condição.

Documentação: AWS IAM · Criar um provedor OIDC ↗ · AWS IAM · Role para OIDC e GitHub ↗ · GitHub · Claims imutáveis no OIDC ↗

O workflow do GitHub Actions#

# .github/workflows/deploy.yml
name: deploy
on:
  push:
    branches: [main]

permissions:
  id-token: write   # permite pedir o token OIDC (não dá permissão de escrita)
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: prod   # precisa bater com o sub da trust policy
    steps:
      - uses: actions/checkout@v7
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::111122223333:role/github-deploy-prod
          aws-region: us-east-1
      - run: aws sts get-caller-identity   # confere a role assumida

Se você configurar o environment prod no GitHub com regras de proteção, como revisores obrigatórios ou branches permitidas, essa aprovação passa a ser também um requisito para obter credenciais de produção, porque a role só aceita tokens desse environment.

Para se aprofundar: Deploy de frontend a partir do Git na AWS

Documentação: configure-aws-credentials ↗ · GitHub · Environments ↗ · AWS CLI · sts get-caller-identity ↗

Erros comuns#

• Not authorized to perform sts:AssumeRoleWithWebIdentity: quase sempre o sub não bate. Um job com environment emite environment:NOME, não ref:refs/heads/BRANCH.
• O job não consegue pedir o token: falta permissions id-token: write no workflow ou no job.
• Trust policy só com aud: qualquer repositório do GitHub poderia tentar assumir a role. Adicione sempre o sub.
• Workflows com pull_request_target ou runners não efêmeros: o README da action pede cuidado redobrado, porque eles podem executar código não confiável com acesso a credenciais.

Documentação: GitHub · OIDC com AWS ↗ · configure-aws-credentials ↗

A outra direção: acesso de leitura aos seus repositórios#

Se uma plataforma externa precisa clonar seus repositórios, dê a ela o acesso mínimo. As principais opções, da mais ampla à mais restrita:

Ao cadastrar uma chave pública fornecida por uma plataforma, confirme que é a correta comparando a impressão digital dela com a exibida pelo seu provedor: salve-a num arquivo e rode ssh-keygen -lf arquivo.pub.

Documentação: GitHub · Deploy keys e machine users ↗ · GitHub · Quando usar uma GitHub App ↗ · GitHub · Tokens de instalação ↗ · Bitbucket · Access keys ↗ · GitLab · Deploy keys ↗ · OpenSSH · ssh-keygen ↗ · GitHub · Revisar chaves SSH ↗

Checklist#

• Provedor OIDC do GitHub criado em cada conta AWS que recebe deploys.
• Uma role por ambiente, com aud e sub fixados a repositório e environment.
• Permissões da role limitadas ao que o deploy faz.
• Nenhuma access key da AWS nos secrets do repositório.
• Acesso de leitura aos repositórios com deploy keys, access keys ou uma GitHub App, não com chaves pessoais.