Gerenciamento de segredos do GitHub Actions: protegendo chaves de API e senhas em workflows

By Mirko Peters · 2026-10-26

Aprenda a proteger seus pipelines de CI/CD usando corretamente os segredos do GitHub Actions. Conheça as melhores práticas para gerenciar chaves de API e tokens de acesso com segurança.

Automatically translated with AI from the original post. Read the English original

Quando sua automação roda totalmente sem supervisão na nuvem, manter suas credenciais seguras se torna essencial. Gerenciar bem os segredos do GitHub Actions garante que suas chaves de API, senhas de implantação e tokens de acesso permaneçam fora do código-fonte, mas continuem facilmente acessíveis aos workflows que precisam deles para compilar e entregar seus projetos.

Principais conclusões

• Nunca escreva senhas sensíveis, chaves de API ou tokens de acesso diretamente nos arquivos YAML dos seus workflows.
• O GitHub oferece três níveis de segredos: segredos de repositório, segredos de organização e segredos de ambiente.
• Os segredos são criptografados antes mesmo de chegar ao GitHub e são mascarados automaticamente nos logs de execução.
• Segredos de ambiente podem exigir aprovação humana antes que as credenciais de implantação fiquem acessíveis a um job.
• Siga sempre o princípio do menor privilégio, concedendo a cada segredo o menor conjunto de permissões necessário.

Por que credenciais em texto simples falham em CI/CD

É tentador, para desenvolvedores com pressa de configurar um novo pipeline, colar uma chave de API diretamente no arquivo de configuração do workflow. Afinal, se o workflow é privado, quem vai vê-lo? Essa mentalidade introduz sérias vulnerabilidades de segurança. Os arquivos de workflow são versionados, o que significa que cada revisão histórica, commit e branch mantém um registro permanente de tudo o que foi escrito dentro desses documentos YAML.

Além disso, repositórios frequentemente mudam suas permissões, passam de privados para públicos ou são copiados em forks por colaboradores. Se suas credenciais estiverem como strings de texto simples nos arquivos de configuração, uma única configuração incorreta de permissão pode expor todo o seu ambiente de produção. Tratar os arquivos de configuração apenas como instruções, enquanto os dados sensíveis ficam armazenados em um cofre criptografado e desacoplado, é a regra fundamental da segurança moderna em nuvem.

Os três níveis de segredos do GitHub

O GitHub reconhece que diferentes credenciais têm escopos diferentes. Para ajudar os desenvolvedores a gerenciar o controle de acesso com eficiência, a plataforma permite configurar segredos em três níveis organizacionais distintos.

Segredos em nível de repositório

Os segredos de repositório pertencem exclusivamente a um único projeto. Se você está desenvolvendo uma aplicação independente ou mantendo um único plugin, um segredo de repositório mantém suas strings de conexão e tokens de implantação restritos àquele espaço de trabalho específico. Eles não podem ser acessados por outros projetos da sua organização.

Segredos em nível de organização

Quando vários repositórios de uma empresa precisam acessar os mesmos recursos compartilhados, como um registro central de contêineres ou um certificado corporativo de assinatura de código, os segredos de organização evitam que você duplique entradas. Administradores podem definir políticas e direcionar repositórios ou equipes específicos que têm permissão para herdar essas credenciais de toda a organização.

Segredos em nível de ambiente

Os segredos de ambiente vinculam credenciais a destinos de implantação específicos, como os ambientes de staging ou produção. É aqui que você armazena as chaves necessárias para acessar sistemas em produção. De forma crucial, os segredos de ambiente permitem configurar revisores obrigatórios, garantindo que uma pessoa precise aprovar manualmente uma execução de implantação antes que as credenciais de produção sejam liberadas e entregues ao runner.

Como o GitHub protege seus dados em trânsito

A segurança vai além de onde os segredos são armazenados; ela envolve também como eles trafegam durante a execução. Os segredos são criptografados na sua máquina local antes de serem transmitidos ao GitHub, garantindo que nunca sejam enviados em texto simples pela rede. Depois de armazenados, permanecem completamente ocultos na interface de configurações do repositório.

Quando um workflow é executado, você precisa passar explicitamente um segredo para uma etapa ou ação, pelo nome, usando a sintaxe de expressão como ${{ secrets.DATABASE_URL } }. Isso significa que uma ação de terceiros mal-intencionada ou descuidada no marketplace não consegue se servir automaticamente de todas as credenciais do seu repositório: ela recebe apenas o que você entrega explicitamente.

Além disso, o GitHub verifica automaticamente os logs de saída dos jobs para mascarar strings sensíveis. Se seu script exibir acidentalmente o valor de um segredo no console, o GitHub tenta substituir os caracteres por asteriscos. No entanto, como scripts podem manipular ou codificar strings antes de imprimi-las, depender apenas do mascaramento de logs não substitui escrever código seguro.

Melhores práticas para automação segura

Gerenciar segredos no GitHub Actions de forma robusta exige adotar hábitos específicos no dia a dia. Primeiro, sempre diferencie uma configuração de um segredo. Se um valor for apenas um endereço de site público, o nome de um ambiente ou uma flag de funcionalidade não sensível, mantenha-o em texto simples dentro do seu arquivo YAML, para que sua equipe consiga entender facilmente como o pipeline funciona. Reserve o recurso de segredos exclusivamente para dados que precisam permanecer confidenciais.

Segundo, adote o princípio do menor privilégio. Gere tokens de acesso granulares com as datas de expiração mais curtas possíveis e o escopo de permissões mais restrito. Se um token de deploy só precisa gravar em um bucket específico do S3, não lhe dê direitos administrativos sobre toda a sua infraestrutura de nuvem.

Conclusão

Dominar o gerenciamento de segredos do GitHub Actions transforma seus pipelines de CI/CD de potenciais riscos de segurança em motores de automação robustos e de nível empresarial. Ao separar suas credenciais do código e aproveitar controles de acesso em múltiplas camadas, você consegue entregar software rapidamente sem abrir mão da segurança.

Para explorar os fundamentos da criação de workflows automatizados, confira o Listen to the full episode. Acompanhe a discussão completa para saber mais sobre como configurar gatilhos, jobs e runners para o seu ambiente de nuvem moderno!

Perguntas frequentes

Posso ler um segredo do GitHub Actions em um pull request vindo de um fork?

Por padrão, o GitHub impede que pull requests de colaboradores externos (forks) acessem os segredos do seu repositório, para evitar que código malicioso seja executado e roube suas credenciais.

Como passo um segredo de um workflow para uma etapa específica?

Você passa os segredos para o seu workflow usando o contexto 'env' dentro de uma etapa ou job, mapeando o segredo do GitHub para uma variável de ambiente, como env: API_KEY: ${{ secrets.MY_API_KEY } }.

Os segredos do GitHub Actions são garantidamente ocultos nos logs?

O GitHub mascara automaticamente valores de segredos conhecidos nos logs de execução, mas isso não é uma garantia absoluta. Se um valor de segredo for manipulado, codificado ou transformado antes de ser impresso, partes dele podem ficar expostas.

Qual é a diferença entre segredos de repositório e segredos de ambiente?

Segredos de repositório estão disponíveis para qualquer workflow de um determinado repositório, enquanto segredos de ambiente são vinculados a ambientes de implantação específicos (como staging ou produção) e podem exigir aprovações de revisão manual.