Skip to main content

Enabling GitHub Actions with Amazon S3 storage

You can enable GitHub Actions on GitHub Enterprise Server and use Amazon S3 storage to store data generated by workflow runs.

Quem pode usar esse recurso?

Site administrators can enable GitHub Actions and configure enterprise settings.

Sobre o armazenamento externo para GitHub Actions

GitHub Actions usa o armazenamento de blobs externo para armazenar dados gerados por execuções de fluxo de trabalho. Os dados armazenados incluem logs de fluxo de trabalho, caches e artefatos de build carregados pelo usuário. Para saber mais, confira "Getting started with GitHub Actions for GitHub Enterprise Server".

Há duas opções para configurar o GitHub Enterprise Server para se conectar ao provedor de armazenamento externo:

  • OIDC (OpenID Connect)
  • Autenticação tradicional baseada em credenciais usando segredos

É recomendável usar o OIDC sempre que possível, pois você não precisará criar ou gerenciar segredos de credenciais confidenciais e de longa duração para seu provedor de armazenamento e arriscar que eles sejam expostos. Depois de definir uma relação de confiança com o OIDC, seu provedor de armazenamento em nuvem emite automaticamente tokens de acesso de curta duração para sua instância do GitHub Enterprise Server, que expiram automaticamente.

Prerequisites

Note: The only GitHub-supported S3 storage providers are Amazon S3 and MinIO Gateway for NAS.

Há outros produtos de armazenamento compatíveis com a API do S3 que os parceiros GitHub validaram automaticamente como trabalhando com GitHub Actions em GitHub Enterprise Server. Para obter mais informações, confira o repositório Parceiros de Armazenamento GHES.

Para produtos de armazenamento validados por meio do programa de Parceria de Tecnologia do GitHub, o provedor de armazenamento é responsável pelo suporte e documentação pelo uso do produto de armazenamento com GitHub Actions.

Before enabling GitHub Actions, make sure you have completed the following steps:

  • Create your Amazon S3 bucket for storing data generated by workflow runs.

  • Revisar os requisitos de hardware para GitHub Actions. Para obter mais informações, confira "Getting started with GitHub Actions for GitHub Enterprise Server".

  • O TLS deve ser configurado para o domínio do sua instância do GitHub Enterprise Server. Para obter mais informações, confira "Configuring TLS".

    Observação: É altamente recomendável que você configure a TLS em GitHub Enterprise Server com um certificado assinado por uma autoridade confiável. Embora um certificado autoassinado possa funcionar, é necessária uma configuração extra para os seus executores auto-hospedados, e não é recomendado para ambientes de produção.

  • Se você tiver um Servidor Proxy HTTP configurado em sua instância do GitHub Enterprise Server:

  • Você deve adicionar .localhost, 127.0.0.1 e ::1 à lista de Exclusão de Proxy HTTP (nessa ordem).

  • Se o local de armazenamento externo não for encaminhável, você também precisará adicionar a URL de armazenamento externo à lista de exclusões.

Para obter mais informações sobre como alterar as configurações de proxy, confira "Configuring an outbound web proxy server".

  • Se você estiver usando o OIDC para a conexão com seu provedor de armazenamento, precisará expor as seguintes URLs de serviço de token OIDC em sua instância do GitHub Enterprise Server à Internet pública:

    https://HOSTNAME/_services/token/.well-known/openid-configuration
    https://HOSTNAME/_services/token/.well-known/jwks
    

    Isso garante que o provedor de armazenamento possa entrar em contato com sua instância do GitHub Enterprise Server para autenticação.

To configure GitHub Enterprise Server to use OIDC with an Amazon S3 bucket, you must first create an Amazon OIDC provider, then create an Identity and Access Management (IAM) role, and finally configure GitHub Enterprise Server to use the provider and role to access your S3 bucket.

1. Create an Amazon OIDC provider

  1. Get the thumbprint for sua instância do GitHub Enterprise Server.

    1. Use the following OpenSSL command to get the SHA1 thumbprint for sua instância do GitHub Enterprise Server, replacing HOSTNAME with the public hostname for sua instância do GitHub Enterprise Server

      Shell
      openssl s_client -connect HOSTNAME:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin
      

      For example:

      openssl s_client -connect my-ghes-host.example.com:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin
      

      The command returns a thumbprint in the following format:

      SHA1 Fingerprint=AB:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56
      
    2. Remove the colons (:) from the thumbprint value, and save the value to use later.

      For example, the thumbprint for the value returned in the previous step is:

      AB1234567890ABCDEF1234567890ABCDEF123456
      
  2. Using the AWS CLI, use the following command to create an OIDC provider for sua instância do GitHub Enterprise Server. Replace HOSTNAME with the public hostname for sua instância do GitHub Enterprise Server, and THUMBPRINT with the thumbprint value from the previous step.

    Shell
    aws iam create-open-id-connect-provider \
      --url https://HOSTNAME/_services/token \
      --client-id-list "sts.amazonaws.com" \
      --thumbprint-list "THUMBPRINT"
    

    For example:

    Shell
    aws iam create-open-id-connect-provider \
      --url https://my-ghes-host.example.com/_services/token \
      --client-id-list "sts.amazonaws.com" \
      --thumbprint-list "AB1234567890ABCDEF1234567890ABCDEF123456"
    

    For more information on installing the AWS CLI, see the Amazon documentation.

    Warning: If the certificate for sua instância do GitHub Enterprise Server changes in the future, you must update the thumbprint value in the Amazon OIDC provider for the OIDC trust to continue to work.

2. Create an IAM role

  1. Open the AWS Console, and navigate to the Identity and Access Management (IAM) service.

  2. In the left menu, under "Access management", click Roles, then click Create Role.

  3. On the "Select trusted entity" page, enter the following options:

    • For "Trusted entity type", click Web identity.
    • For "Identity provider", use the Choose provider drop-down menu and select the OIDC provider you created in the previous steps. It should be named HOSTNAME/_services/token, where HOSTNAME is the public hostname for sua instância do GitHub Enterprise Server.
    • For "Audience", select sts.amazonaws.com.
  4. Click Next.

  5. On the "Add permissions" page, use the filter to find and select the AmazonS3FullAccess policy.

  6. Click Next.

  7. On the "Name, review, and create" page, enter a name for the role, and click Create role.

  8. On the IAM "Roles" page, select the role you just created.

  9. Under "Summary", note the ARN value for the role, as this is needed later.

  10. Click the Trust relationships tab, then click Edit trust policy.

  11. Edit the trust policy to add a new sub claim. The value for Condition must match the following example, replacing HOSTNAME with the public hostname for sua instância do GitHub Enterprise Server:

    ...
    "Condition": {
      "StringEquals": {
        "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
        "HOSTNAME/_services/token:sub": "HOSTNAME"
      }
    }
    ...
    

    For example:

    ...
    "Condition": {
      "StringEquals": {
        "my-ghes-host.example.com/_services/token:aud": "sts.amazonaws.com",
        "my-ghes-host.example.com/_services/token:sub": "my-ghes-host.example.com"
      }
    }
    ...
    
  12. Click Update policy.

3. Configure GitHub Enterprise Server to connect to Amazon S3 using OIDC

  1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

  2. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

  3. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .

  4. Na barra lateral "Configurações", clique em Ações.

  5. Em "GitHub Actions", selecione Habilitar GitHub Actions.

  6. Em "Armazenamento de Logs e Artefatos", ao lado de "Amazon S3", clique em Configurar.

  7. Under "Authentication", select OpenID Connect (OIDC), and enter the values for your storage:

    • AWS S3 Bucket: The name of your S3 bucket.
    • AWS Role: The ARN for the role you created in the previous procedures. For example, arn:aws:iam::123456789:role/my-role-name.
    • AWS Region: The AWS region for your bucket. For example, us-east-1.
  8. Clique no botão Testar configurações de armazenamento para validar as configurações de armazenamento.

    Se houver erros ao validar as configurações de armazenamento, verifique as configurações no provedor de armazenamento e tente novamente.

  9. Na barra lateral "Configurações", clique em Salvar configurações.

    Observação: se você salvar as configurações no Console de Gerenciamento, isso reiniciará os serviços do sistema, o que poderá resultar em tempo de inatividade visível pelo usuário.

  10. Aguarde a conclusão da execução de suas configurações.

Enabling GitHub Actions with Amazon S3 storage using access keys

  1. Using the AWS Console or CLI, create an access key for your storage bucket. GitHub Actions exige as seguintes permissões para a chave de acesso que terá acesso ao bucket:

    • s3:PutObject
    • s3:GetObject
    • s3:ListBucketMultipartUploads
    • s3:ListMultipartUploadParts
    • s3:AbortMultipartUpload
    • s3:DeleteObject
    • s3:ListBucket
    • kms:GenerateDataKey (se a criptografia KMS, Serviço de Gerenciamento de Chaves, tiver sido habilitada)

    For more information on managing AWS access keys, see the "AWS Identity and Access Management Documentation."

  2. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

  3. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

  4. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .

  5. Na barra lateral "Configurações", clique em Ações.

  6. Em "GitHub Actions", selecione Habilitar GitHub Actions.

  7. Em "Armazenamento de Logs e Artefatos", ao lado de "Amazon S3", clique em Configurar.

  8. Under "Authentication", select Credentials-based, and enter your storage bucket's details:

    • URL de Serviço da AWS: a URL de serviço do bucket. Por exemplo, se o bucket S3 foi criado na região us-west-2, esse valor deve ser https://s3.us-west-2.amazonaws.com.

      Para obter mais informações, confira "Pontos de extremidade de serviço da AWS" na documentação da AWS.

    • Bucket da AWS S3: o nome do bucket S3.

    • Chave de Acesso da AWS S3 e Chave Secreta da AWS S3: a ID da chave de acesso da AWS e a chave secreta do bucket.

  9. Clique no botão Testar configurações de armazenamento para validar as configurações de armazenamento.

    Se houver erros ao validar as configurações de armazenamento, verifique as configurações no provedor de armazenamento e tente novamente.

  10. Na barra lateral "Configurações", clique em Salvar configurações.

    Observação: se você salvar as configurações no Console de Gerenciamento, isso reiniciará os serviços do sistema, o que poderá resultar em tempo de inatividade visível pelo usuário.

  11. Aguarde a conclusão da execução de suas configurações.

Próximas etapas

Depois que a execução da configuração tiver sido concluída com sucesso, GitHub Actions será habilitado em sua instância do GitHub Enterprise Server. Para suas próximas etapas, como gerenciar as permissões de acesso do GitHub Actions e adicionar executores auto-hospedados, retorne para "Getting started with GitHub Actions for GitHub Enterprise Server".