Skip to main content

Usar segredos em ações do GitHub

Os segredos permitem que você armazene informações confidenciais na sua organização, repositório ou em ambientes do repositório.

Tool navigation

Sobre segredos

Segredos são variáveis que você cria em uma organização, repositório ou ambiente de repositório. Os segredos que você cria estão disponíveis para utilização nos fluxos de trabalho em GitHub Actions. GitHub Actions só poderá ler um segredo se você incluí-lo explicitamente em um fluxo de trabalho.

Para segredos armazenados no nível da organização, é possível usar políticas de acesso para controlar quais repositórios podem usar segredos da organização. Segredos no nível da organização permitem que você compartilhe segredos entre vários repositórios, o que reduz a necessidade de criar segredos duplicados. A atualização de um segredo de organização em um único local também garante que a alteração tenha efeito em todos os fluxos de trabalho do repositório que usam esse segredo.

Para segredos armazenados no nível do ambiente, você pode habilitar os revisores necessários para controlar o acesso aos segredos. Um trabalho de fluxo de trabalho não pode acessar segredos de ambiente até que a aprovação seja concedida por aprovadores necessários.

Observação: Se os seus fluxos de trabalho de GitHub Actions tiverem de acessar recursos de um provedor de nuvem compatível com o OpenID Connect (OIDC), você poderá configurar seus fluxos de trabalho para efetuar a autenticção diretamente no provedor de nuvem. Isso permitirá que você pare de armazenar essas credenciais como segredos de longa duração e proporcione outros benefícios de segurança. Para obter mais informações, confira "Sobre o enrijecimento de segurança com o OpenID Connect".

Nomear os seus segredos

As regras a seguir aplicam-se aos nomes dos segredos:

  • Os nomes só podem conter caracteres alfanuméricos ([a-z], [A-Z], [0-9]) ou sublinhados (_). Espaços não são permitidos.

  • Os nomes não devem começar com o prefixo GITHUB_.

  • Os nomes não devem começar com número.

  • Os nomes não diferenciam maiúsculas de minúsculas.

  • Os nomes devem ser únicos no nível em que são criados.

    Por exemplo, um segredo criado no nível de ambiente deve ter um nome exclusivo nesse ambiente, um segredo criado no nível do repositório deve ter um nome exclusivo nesse repositório, e um segredo criado no nível da organização deve ter um nome exclusivo nesse nível.

    Se houver um segredo com o mesmo nome em vários níveis, o segredo no nível mais baixo terá precedência. Por exemplo, se um segredo a nível de organização tiver o mesmo nome que um segredo a nível de repositório, o segredo a nível de repositório terá prioridade. Da mesma forma, se uma organização, repositório e ambiente tiverem um mesmo nome, o segredo do nível de ambiente terá prioridade.

Para ajudar a garantir que GitHub remova o seu segredo dos registros, evite usar dados estruturados como valores dos segredos. Por exemplo, evite criar segredos que contêm JSON ou blobs do Git.

Acessar os seus segredos

Para disponibilizar um segredo para uma ação, você deve configurá-lo como uma entrada ou variável de ambiente no arquivo do fluxo de trabalho. Revise o arquivo README da ação para saber quais entradas e variáveis de ambientes a ação exige. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Você pode usar e ler segredos em um arquivo de fluxo de trabalho se tiver permissão para editar o arquivo. Para obter mais informações, confira "Permissões de acesso no GitHub".

Aviso: Se um segredo foi usado no trabalho, o GitHub edita automaticamente os segredos impressos no log. Você deve evitar imprimir segredos no log intencionalmente.

Os segredos da organização e do repositório são lidos quando uma execução de fluxo de trabalho é enfileirada e os segredos de ambiente são lidos quando um trabalho que faz referência ao ambiente é iniciado.

Você também pode gerenciar segredos usando o API REST. Para obter mais informações, confira "Pontos de extremidade da API REST para segredos do GitHub Actions".

Permissões limitadas de credenciais

Ao gerar credenciais, recomendamos que você conceda as permissões mínimas possíveis. Por exemplo, em vez de usar credenciais pessoais, use chaves de implantação ou uma conta de serviço. Considere conceder permissões somente leitura se isso o necessário e limite o acesso tanto quanto possível.

Ao gerar um personal access token (classic), selecione o menor número de escopos necessários. Ao gerar um fine-grained personal access token, selecione o mínimo de permissões e de acesso ao repositório necessário.

Em vez de usar um personal access token, considere usar um GitHub App, que usa permissões refinadas e tokens de curta duração, como um fine-grained personal access token. Ao contrário de um personal access token, um GitHub App não está vinculado a um usuário, portanto, o fluxo de trabalho continuará funcionando mesmo que o usuário que instalou o aplicativo saia da organização. Para obter mais informações, confira "Fazer solicitações de API autenticadas com um Aplicativo do GitHub em um fluxo de trabalho do GitHub Actions".

Observação: usuários com acesso de colaborador a um repositório podem usar a API REST para gerenciar segredos desse repositório, e usuários com acesso de administrador a uma organização podem usar a API REST para gerenciar segredos dessa organização. Para obter mais informações, confira "Pontos de extremidade da API REST para segredos do GitHub Actions".

Como criar segredos para um repositório

Para criar segredos ou variáveis no GitHub para um repositório de conta pessoal, você deve ser o proprietário do repositório. Para criar segredos ou variáveis no GitHub para um repositório de organização, você deve ter acesso a admin. Por fim, para criar segredos ou variáveis para um repositório de conta pessoal ou um repositório de organização por meio da API REST, você deve ter acesso de colaborador.

  1. No GitHub.com, navegue até a página principal do repositório.

  2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  3. Na seção "Segurança" da barra lateral, selecione Segredos e variáveis, e clique em Ações.

  4. Clique na guia Segredos. Captura de tela da página "Segredos e variáveis de ações".

  5. Clique em Novo segredo de repositório.

  6. No campo Nome, digite um nome para o segredo.

  7. No campo Segredo, insira o valor do segredo.

  8. Clique em Adicionar segredo.

Se o seu repositório tiver segredos de ambiente ou puder acessar segredos da organização principal, esses segredos também serão listados nesta página.

Para saber mais sobre GitHub CLI, confira "Sobre o a CLI do GitHub".

Para adicionar um segredo do repositório, use o subcomando gh secret set. Substitua secret-name pelo nome do segredo.

gh secret set SECRET_NAME

A CLI solicitará que você digite o valor de um segredo. Como alternativa, você pode ler o valor do segredo a partir de um arquivo.

gh secret set SECRET_NAME < secret.txt

Para listar todos os segredos do repositório, use o subcomando gh secret list.

Criar segredos para um ambiente

Para criar segredos ou variáveis para um ambiente em um repositório de conta pessoal, você precisa ser o proprietário do repositório. Para criar segredos ou variáveis para um ambiente no repositório de uma organização, você precisa ter acesso de admin. Para saber mais sobre os ambientes, confira "Usando ambientes para implantação".

  1. No GitHub.com, navegue até a página principal do repositório.

  2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  3. Na barra lateral esquerda, clique em Ambientes.

  4. Clique no ambiente ao qual você deseja adicionar um segredo.

  5. Em Segredos do ambiente, clique em Adicionar segredo.

  6. Digite um nome para o segredo na caixa de entrada Nome.

  7. Insira o valor para o seu segredo.

  8. Clique em Adicionar segredo.

Para adicionar um segredo a um ambiente, use o subcomando gh secret set com o sinalizador --env ou -e seguido do nome do ambiente.

gh secret set --env ENV_NAME SECRET_NAME

Para listar todos os segredos de um ambiente, use o subcomando gh secret list com o sinalizador --env ou -e seguido do nome do ambiente.

gh secret list --env ENV_NAME

Criando segredos para uma organização

Nota: segredos e variáveis no nível da organização não são acessíveis por repositórios privados para GitHub Free. Para obter mais informações sobre como atualizar sua assinatura do GitHub, consulte "Atualizando o plano da sua conta".

Ao criar um segredo ou uma variável em uma organização, você poderá usar uma política para limitar o acesso por repositório. Por exemplo, você pode conceder acesso a todos os repositórios ou limitar o acesso a apenas repositórios privados ou a uma lista específica de repositórios.

Os proprietários da organização podem criar segredos ou variáveis no nível da organização.

  1. No GitHub.com, navegue até a página principal da organização.

  2. No nome da sua organização, clique Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela das guias no perfil de uma organização. A guia "Configurações" está contornada em laranja escuro.

  3. Na seção "Segurança" da barra lateral, selecione Segredos e variáveis, e clique em Ações.

  4. Clique na guia Segredos.

    Captura de tela da página "Segredos e variáveis de ações". Uma guia, rotulada como "Segredos", está contornada em laranja escuro.

  5. Clique em Novo segredo da organização.

  6. Digite um nome para o segredo na caixa de entrada Nome.

  7. Insira o Valor do segredo.

  8. Na lista suspensa Acesso do repositório, escolha uma política de acesso.

  9. Clique em Adicionar segredo.

Observação: por padrão, a GitHub CLI é autenticada com os escopos repo e read:org. Para gerenciar os segredos da organização, você também precisa autorizar o escopo admin:org.

gh auth login --scopes "admin:org"

Para adicionar um segredo a uma organização, use o subcomando gh secret set com o sinalizador --org ou -o seguido do nome da organização.

gh secret set --org ORG_NAME SECRET_NAME

Por padrão, o segredo só está disponível para repositórios privados. Para especificar que o segredo deve estar disponível para todos os repositórios na organização, use o sinalizador --visibility ou -v.

gh secret set --org ORG_NAME SECRET_NAME --visibility all

Para especificar que o segredo deve estar disponível para repositórios selecionados na organização, use o sinalizador --repos ou -r.

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2"

Para listar todos os segredos de uma organização, use o subcomando gh secret list com o sinalizador --org ou -o seguido do nome da organização.

gh secret list --org ORG_NAME

Rever o acesso para os segredos do nível da organização

Você pode verificar quais políticas de acesso são aplicadas a um segredo na sua organização.

  1. No GitHub.com, navegue até a página principal da organização.

  2. No nome da sua organização, clique Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela das guias no perfil de uma organização. A guia "Configurações" está contornada em laranja escuro.

  3. Na seção "Segurança" da barra lateral, selecione Segredos e variáveis, e clique em Ações.

  4. A lista de segredos inclui quaisquer permissões e políticas configuradas. Para obter mais detalhes sobre as permissões configuradas para cada segredo, clique em Atualizar.

Usar segredos em um fluxo de trabalho

Observações:

  • Com exceção do GITHUB_TOKEN, os segredos não são transmitidos para o executor quando um fluxo de trabalho é disparado de um repositório com fork.

  • Os segredos não são passados automaticamente para fluxos de trabalho reutilizáveis. Para obter mais informações, confira "Reutilizar fluxos de trabalho".

Para fornecer uma ação com um segredo como uma entrada ou uma variável de ambiente, use o contexto secrets para acessar os segredos criados no seu repositório. Para obter mais informações, confira "Contextos" e "Sintaxe de fluxo de trabalho para o GitHub Actions."

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

Não é possível referenciar segredos diretamente em condicionais if:. Em vez disso, considere definir segredos como variáveis de ambiente no nível de trabalho e, em seguida, fazer referência às variáveis de ambiente para executar etapas condicionalmente no trabalho. Para obter mais informações, confira "Contextos" e jobs.<job_id>.steps[*].if.

Se um segredo não for definido, o valor retornado de uma expressão que referencia o segredo (como ${{ secrets.SuperSecret }} no exemplo) será uma cadeia de caracteres vazia.

Evite a transmissão de segredos entre processos da linha de comando sempre que possível. Os processos de linha de comando podem estar visíveis para outros usuários (por meio do comando ps) ou ser capturados por eventos de auditoria de segurança. Para ajudar a proteger os segredos, considere o uso de variáveis de ambiente, STDIN ou outros mecanismos compatíveis com o processo de destino.

Se você passar segredos dentro de uma linha de comando, inclua-os dentro das regras de aspas corretas. Muitas vezes, os segredos contêm caracteres especiais que não intencionalmente podem afetar o seu shell. Para escapar desses caracteres especiais, use aspas com suas variáveis de ambiente. Por exemplo:

Exemplo de uso do Bash

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

Exemplo de uso do PowerShell

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Exemplo de uso do Cmd.exe

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

Limites para segredos

Você pode armazenar até 1.000 segredos da organização, 100 segredos de repositório e 100 segredos de ambiente.

Um fluxo de trabalho criado em um repositório pode acessar o seguinte número de segredos:

  • Todos os 100 segredos do repositório.
  • Se o repositório tiver acesso a mais de 100 segredos da organização, o fluxo de trabalho só poderá usar os primeiros 100 segredos da organização (ordem alfabética por nome de segredo).
  • Todos os 100 segredos de ambiente.

Os segredos são limitados a 48 KB. Para armazenar segredos maiores, confira a solução alternativa "Como armazenar segredos grandes" abaixo.

Como armazenar segredos grandes

Para usar segredos com mais de 48 KB, você pode usar uma solução alternativa para armazenar segredos no repositório e salvar a frase secreta de descriptografia como um segredo no GitHub. Por exemplo, você pode usar gpg para criptografar um arquivo contendo o segredo localmente antes de fazer check-in do arquivo criptografado no repositório do GitHub. Para obter mais informações, confira a "Página do manual do GPG".

Aviso: tenha cuidado para que os segredos não sejam impressos quando o fluxo de trabalho for executado. Quando usar essa alternativa, o GitHub não eliminará segredos que estão impressos nos logs.

  1. Execute o comando a seguir no terminal para criptografar o arquivo que contém o segredo usando gpg e o algoritmo de criptografia AES256. Neste exemplo, my_secret.json é o arquivo que contém o segredo.

    gpg --symmetric --cipher-algo AES256 my_secret.json
    
  2. Você receberá a solicitação para inserir a frase secreta. Guarde a frase secreta, pois você precisará criar um novo segredo no GitHub que usa a frase secreta como valor.

  3. Criar um novo segredo que contém a frase secreta. Por exemplo, crie um segredo com o nome LARGE_SECRET_PASSPHRASE e defina o valor do segredo como a frase secreta usada na etapa acima.

  4. Copie o arquivo criptografado para um caminho no repositório e faça commit. Neste exemplo, o arquivo criptografado é my_secret.json.gpg.

    Aviso: copie o arquivo criptografado my_secret.json.gpg que termina com a extensão de arquivo .gpg e não o arquivo não criptografado my_secret.json.

    git add my_secret.json.gpg
    git commit -m "Add new secret JSON file"
    
  5. Crie um script do shell no repositório para descriptografar o arquivo de segredo. Neste exemplo, o script se chama decrypt_secret.sh.

    Shell
    #!/bin/sh
    
    # Decrypt the file
    mkdir $HOME/secrets
    # --batch to prevent interactive command
    # --yes to assume "yes" for questions
    gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
    --output $HOME/secrets/my_secret.json my_secret.json.gpg
    
  6. Confirme que o shell script é executável antes de colocá-lo no repositório.

    chmod +x decrypt_secret.sh
    git add decrypt_secret.sh
    git commit -m "Add new decryption script"
    git push
    
  7. No fluxo de trabalho do GitHub Actions, use um step para chamar o script do shell e descriptografar o segredo. Para ter uma cópia do repositório no ambiente em que o fluxo de trabalho é executado, você precisará usar a ação actions/checkout. Referencie o script do shell usando o comando run relativo à raiz do repositório.

    name: Workflows with large secrets
    
    on: push
    
    jobs:
      my-job:
        name: My Job
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Decrypt large secret
            run: ./decrypt_secret.sh
            env:
              LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
          # This command is just an example to show your secret being printed
          # Ensure you remove any print statements of your secrets. GitHub does
          # not hide secrets that use this workaround.
          - name: Test printing your secret (Remove this step in production)
            run: cat $HOME/secrets/my_secret.json
    

Armazenar Blobs binários de Base64 como segredos

Você pode usar a codificação de Base64 para armazenar pequenos blobs binários como segredos. Em seguida, você pode fazer referência ao segredo no seu fluxo de trabalho e decodificá-lo para usar no executor. Para ver os limites de tamanho, confira "Usar segredos em ações do GitHub".

Observação: observe que o Base64 converte apenas binário em texto e não substitui a criptografia real.

  1. Use base64 para codificar seu arquivo em uma cadeia de caracteres Base64. Por exemplo:

    No macOS, você pode executar:

    base64 -i cert.der -o cert.base64
    

    No Linux, você pode executar:

    base64 -w 0 cert.der > cert.base64
    
  2. Crie um segredo que contenha a string de Base64. Por exemplo:

    $ gh secret set CERTIFICATE_BASE64 < cert.base64
    ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
    
  3. Para acessar a cadeia de caracteres Base64 por meio do executor, encaminhe o segredo para base64 --decode. Por exemplo:

    name: Retrieve Base64 secret
    on:
      push:
        branches: [ octo-branch ]
    jobs:
      decode-secret:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Retrieve the secret and decode it to a file
            env:
              CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
            run: |
              echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
          - name: Show certificate information
            run: |
              openssl x509 -in cert.der -inform DER -text -noout
    

Observação: o uso de outro shell pode exigir comandos diferentes para decodificar o segredo em um arquivo. Em executores do Windows, recomendamos usar um shell do bash com shell: bash para usar os comandos na etapa run acima.

Editar segredos de logs de execução de fluxo de trabalho

Embora o GitHub edite automaticamente os segredos impressos nos logs de fluxo de trabalho, os executores só podem excluir os segredos aos quais têm acesso. Isso significa que um segredo só será editado se tiver sido usado em um trabalho. Como medida de segurança, você pode excluir logs de execução do fluxo de trabalho para evitar que valores confidenciais sejam vazados. Para obter mais informações, confira "Usando logs de execução de fluxo de trabalho".