Usar segredos em ações do GitHub

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 da organização, você deve ter acesso 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.

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Criar segredos para um ambiente

Para criar segredos ou variáveis para um ambiente em um repositório de conta pessoal, você deve ser o proprietário do repositório. Para criar segredos ou variáveis para um ambiente em um repositório da organização, é necessário ter acesso de admin. Para saber mais sobre os ambientes, confira Gerenciar ambientes para implantação.

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Criando segredos para uma organização

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 e os usuários com as permissões "Gerenciar variáveis de ações da organização" ou "Gerenciar segredos de ações da organização" podem criar segredos ou variáveis no nível da organização.

Para saber mais, confira Sobre as funções da organização personalizadas.

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

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

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

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. Em GitHub, acesse a página principal da organização.

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

   

3. Na seção "Security" da barra lateral, selecione Secrets and variables e clique em Actions.

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

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 saber mais, confira Referência de 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 Referência de 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%"

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.

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 my_secret.json.gpg criptografado que termina com a extensão de arquivo .gpg e não o arquivo my_secret.json não criptografado.

   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@v5
         - 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.

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@v5
         - 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
   

Próximas etapas

Para obter informações de referência, confira Referência de segredos.