Segredos criptografados

Sobre os segredos encriptados

Segredos são variáveis de ambiente encriptadas que você cria em um repositório ou organização. Os segredos que você cria estão disponíveis para utilização nos fluxos de trabalho em GitHub Actions. O GitHub usa uma caixa selada de libsodium para ajudar a garantir que os segredos sejam criptografados antes de chegar ao GitHub e permanecer criptografados até que você os use 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.

Nomear os seus segredos

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

• Os nomes dos segredos podem conter apenas caracteres alfanuméricos ([a-z], [A-Z], [0-9]) or sublinhado (_). Não são permitidos espaços.
• Os nomes dos segredos não devem começar com o prefixo GITHUB_.
• Os nomes dos segredos não devem começar com um número.
• Os nomes dos segredos devem ser únicos no nível em que são criados. Por exemplo, um segredo criado no nível da organização deve ter um nome único nesse nível, e um segredo criado no nível do repositório deve ter um nome único nesse repositório. Se o segredo do nível de uma organização tiver o mesmo nome do segredo do nível do repositório, o segredo do nível do repositório prevalecerá.

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 Git blobs.

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 LEIAME da ação para saber quais entradas e variáveis de ambientes a ação exige. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

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

Você também pode gerenciar segredos usando o API REST. Para obter mais informações, consulte "Segredos".

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 token de acesso pessoal (PAT), selecione o menor escopo necessário.

Criar segredos encriptados para um repositório

Para criar segredos para um repositório de conta de usuário, você deve ser o proprietário do repositório. Para criar segredos para o repositório de uma organização, você deve ter acesso admin.

1. No GitHub, navegue até a página principal do repositório.
2. No nome do seu repositório, clique em Configurações.
   
3. Na barra lateral esquerda, clique em Secrets (Segredos).
4. Clique em Adicionar novo segredo.
5. Digite um nome para o seu segredo na caixa de entrada Nome.
6. Insira o valor para o seu segredo.
7. Clique em Add secret (Adicionar segredo).

Se o seu repositório puder acessar segredos a partir da organização-mãe, esses segredos também serão listados nesta página.

Criar segredos encriptados para uma organização

Ao criar um segredo em uma organização, você pode usar uma política para limitar quais repositórios podem acessar esse segredo. 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.

Para criar segredos no nível da organização, você deve ter acesso admin.

1. No GitHub, navegue para a página principal da organização.
2. No nome da sua organização, clique em Settings.
   
3. Na barra lateral esquerda, clique em Secrets (Segredos).
4. Clique em Novo segredo.
5. Digite um nome para o seu segredo na caixa de entrada Nome.
6. Insira o Valor para o seu segredo.
7. Na lista suspensa Acesso do repositório, escolha uma política de acesso.
8. Clique em Add secret (Adicionar segredo).

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, navegue para a página principal da organização.
2. No nome da sua organização, clique em Settings.
   
3. Na barra lateral esquerda, clique em Secrets (Segredos).
4. A lista de segredos inclui quaisquer permissões e políticas configuradas. Por exemplo:
   
5. Para obter mais detalhes sobre as permissões configuradas para cada segredo, clique em Atualizar.

Usando segredos encriptados em um fluxo de trabalho

Com exceção do GITHUB_TOKEN, os segredos não são disponibilizados para o executor quando um fluxo de trabalho é acionado a partir de um repositório bifurcado.

Para fornecer uma ação com um segredo como uma entrada ou variável de ambiente, você pode usar o contexto de segredos para acessar os segredos que você criou no seu repositório. Para obter mais informações, consulte "Contexto e sintaxe de expressão para GitHub Actions" e "Sintaxe do fluxo de trabalho para GitHub Actions."

steps:
  - name: Hello world action
    with: # Configura o segredo como uma entrada
      super_secret: ${{ secrets.SuperSecret }}
    env: # Ou como uma variável de ambiente
      super_secret: ${{ secrets.SuperSecret }}

Evite a transmissão de segredos entre processos da linha de comando sempre que possível. Os processos da linha de comando podem ser visíveis para outros usuários (usando o comando ps) ou capturado 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

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

Exemplo de uso do PowerShell

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

Exemplo de uso do Cmd.exe

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

Limites para segredos

O seu fluxo de trabalho pode ter até 100 segredos. Os nomes das variáveis do ambiente de segredo devem ser únicas em um repositório.

Os segredos são limitados a 64 kB. Para usar segredos maiores que 64 kB, você pode armazenar segredos criptografados no seu repositório e salvar a frase secreta de descodificação como um segredo no GitHub. Por exemplo, você pode usar gpg para criptografar suas credenciais localmente antes de colocar o arquivo no repositório do GitHub. Para obter mais informações, consulte a "página do manual gpg".

1. Execute o seguinte comando no seu terminal para criptografar o arquivo my_secret.json usando gpg e o algoritmo de cifragem AES256.

   $ 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 novo segredo com o nome LARGE_SECRET_PASSPHRASE e defina o valor do segredo para a frase secreta que você escolheu na etapa anterior.

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

5. Crie um script shell para decifrar a senha. Salve o arquivo como decrypt_secret.sh.

   #!/bin/sh
   
   # Decrypt the file
   mkdir $HOME/secrets
   # --lote para evitar o comando interativo
   # --sim para supor "sim" para as perguntas
   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. A partir de seu fluxo de trabalho, use step para chamar o shell script e decifrar o segredo. Para ter uma cópia do seu repositório no ambiente em que o seu fluxo de trabalho é executado, você deverá executar a ação actions/checkout. Faça referência ao shell script usando o comando run relativo à raiz do repositório.

   nome: Fluxos de trabalho com grandes segredos
   
   : empurrar
   
   empregos:
     meu trabalho:
       nome: My Job
       runs-on: ubuntu-latest
       steps:
         - usa: actions/checkout@v2
         - nome: Descriptografar grandes segredos
           executar: ./.github/scripts/decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # Este comando é apenas um exemplo para mostrar seu segredo sendo impresso
         # Certifique-se de remover quaisquer declarações impressas de seus segredos. O GitHub
         # não oculta segredos que usam essa alternativa.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json