Skip to main content

Segredos criptografados

Segredos criptografados permitem que você armazene informações confidenciais na organização, repositório ou ambientes de repositórios.

Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.

Sobre os segredos encriptados

Os segredos são variáveis de ambiente criptografadas 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 usa uma caixa selada libsodium para ajudar a garantir que os segredos sejam criptografados antes de chegarem a GitHub e permaneçam 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.

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, consulteSobre segurança fortalecida com OpenID Connect"

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.

  • Nomes dos segredos não diferenciam maiúsculas de minúsculas.

  • Os nomes dos segredos 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.

    If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. 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, 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."

Aviso: GitHub elimina automaticamente os segredos impressos no registro, mas você deve evitar a impressão intencional de segredos no log.

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, 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.

Observação: Você pode usar a API REST para gerenciar segredos. Para obter mais informações, consulte "GitHub Actions secrets API."

Criar segredos encriptados para um repositório

Para criar segredos para um repositório de conta pessoal, 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 your GitHub Enterprise Server instance, navegue até a página principal do repositório.

  2. No nome do seu repositório, clique em Configurações. Botão de configurações do repositório

  3. Na barra lateral esquerda, clique em Segredos de .

  4. Clique em Novo segredo do repositório.

  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 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, consulte "Sobre GitHub CLI."

Para adicionar um segredo de repositório, use o subcomando gh secret set. Substitua nome secreto pelo nome do seu 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 para o repositório, use o subcomando da lista gh secret.

Criar segredos criptografados para um ambiente

Para criar segredos para um ambiente em um repositório de conta pessoal, você deve ser o proprietário do repositório. Para criar segredos para um ambiente em um repositório da organização, é necessário ter acesso de admin.

  1. No your GitHub Enterprise Server instance, navegue até a página principal do repositório.
  2. No nome do seu repositório, clique em Configurações. Botão de configurações do repositório
  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 seu segredo na caixa de entrada Nome.
  7. Insira o valor para o seu segredo.
  8. Clique em Add secret (Adicionar segredo).

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

gh secret set --env environment-name secret-name

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

gh secret list --env environment-name

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 your GitHub Enterprise Server instance, navegue para a página principal da organização.
  2. Abaixo do nome da sua organização, clique em Settings. Botão de configurações da organização
  1. Na barra lateral esquerda, clique em Segredos de .

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

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

  4. Insira o Valor para o seu segredo.

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

  6. Clique em Add secret (Adicionar segredo).

Observação: Por padrão, GitHub CLI efetua a autenticação com os escopos repo e read:org. Para gerenciar segredos da organização, você deve adicionalmente autorizar o escopo admin:org.

gh auth login --scopes "admin:org"

Para adicionar um segredo de 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 organization-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 da organização, use o sinalizador --visibility ou -v.

gh secret set --org organization-name secret-name --visibility all

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

gh secret set --org organization-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 organization-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 your GitHub Enterprise Server instance, navegue para a página principal da organização.
  2. Abaixo do nome da sua organização, clique em Settings. Botão de configurações da organização
  1. Na barra lateral esquerda, clique em Segredos de .

  2. A lista de segredos inclui quaisquer permissões e políticas configuradas. Por exemplo: Lista de segredos

  3. Para obter mais detalhes sobre as permissões configuradas para cada segredo, clique em Atualizar.

Usando segredos encriptados em um fluxo de trabalho

Observação: 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 "Contextos" e "Sintaxe de 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 }}

Não é possível fazer referência a segredos nas 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, consulte "Disponibilidade de contexto" e trabalhos.<job_id>.steps[*].if.

Se um segredo não tiver sido definido, o valor de retorno de uma expressão referente ao segredo (como ${{ secrets.SuperSecret }} no exemplo) será uma string vazia.

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

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 64 kB. Para armazenar segredos maiores, consulte a alternativa "Armazenando grandes segredos" abaixo.

Armazenando grandes segredos

Para usar segredos maiores que 64 kB, você pode usar uma alternativa para 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 um arquivo que contém seu segredo localmente antes de verificar o arquivo criptografado no seu repositório em GitHub. Para obter mais informações, consulte a "página do manual gpg".

Aviso: Tenha vuidado para seus segredos não serem impressos quando o fluxo de trabalho é executado. Quando usar essa alternativa, o GitHub não eliminará segredos que estão impressos nos logs.

  1. Execute o seguinte comando no seu terminal para criptografar o arquivo que contém seu segredo usando gpg e o algoritmo de cifra 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 novo segredo com o nome LARGE_SECRET_PASSPHRASE e defina o valor do segredo para a frase secreta que você usou na etapa anterior.

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

    Aviso: Certifique-se de copiar o arquivo criptografado my.json.gpg que termina com a extenção do arquivo .gpg e não o arquivo não criptografado my_secret.json.

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

    #!/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 seu fluxo de trabalho de GitHub Actions, use uma etapa para chamar o script do shell e descriptografar 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.

    name: Workflows with large secrets
    
    on: push
    
    jobs:
      my-job:
        name: My Job
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - 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 os limites de tamanho, consulte "Limites para segredos".

Observação: Observe que o Base64 só converte números binários em texto e não substitui a criptografia real.

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

    $ base64 -i cert.der -o 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 string de Base64 do seu executor, transforme segredo em base64 --decode. Por exemplo:

    name: Retrieve Base64 secret
    on:
      push:
        branches: [ octo-branch ]
    jobs:
      decode-secret:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - 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