Como se autenticar na API do GitHub

Saiba como se autenticar na API GitHub para usar o Actions Runner Controller with GitHub.

Neste artigo

Aviso legal

Visão geral

Você pode autenticar o ARC (Actions Runner Controller) na API do GitHub usando um GitHub App ou um personal access token (classic).

Observação

Não é possível se autenticar usando um GitHub App para executores na empresa. Para saber mais, confira Gerenciar o acesso a executores auto-hospedados usando grupos.

Como autenticar o ARC com um GitHub App

  1. Crie um GitHub App que pertence a uma organização. Para saber mais, confira Registrar um Aplicativo GitHub. Configure o GitHub App da seguinte maneira.

    1. Em "URL da Home Page", insira http://github.com/actions/actions-runner-controller.

    2. Em "Permissões", clique em Permissões do repositório. Em seguida, use os menus suspensos para selecionar as permissões de acesso a seguir.

      • Administração: leitura e gravação

        Observação

        Administration: Read and write só é necessário ao configurar o Actions Runner Controller para registro no escopo do repositório. Não é necessário se registrar no escopo da organização.

      • Metadados: somente leitura

    3. Em "Permissões", clique em Permissões da organização. Em seguida, use os menus suspensos para selecionar as permissões de acesso a seguir.

      • Executores auto-hospedados: leitura e gravação

  2. Depois de criar os dados do GitHub App, na página do GitHub App, observe o valor de "ID do aplicativo". Você usará esse valor mais tarde.

  3. Em "Chaves privadas", clique em Gerar uma chave privada e salve o arquivo .pem. Você usará esta chave mais tarde.

  4. No menu no canto superior esquerdo da página, clique em Instalar aplicativo e, ao lado da sua organização, clique em Instalar para instalar o aplicativo na sua organização.

  5. Depois de confirmar as permissões de instalação na sua organização, anote a ID de instalação do aplicativo. Você o usará mais tarde. Encontre a ID de instalação do aplicativo na página de instalação do aplicativo, que tem o seguinte formato de URL:

    http://HOSTNAME/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

  6. Registre a ID do aplicativo, a ID de instalação e o arquivo de chave privada .pem baixado das etapas anteriores para o Kubernetes como um segredo.

    Para criar um segredo do Kubernetes com os valores de seus dados do GitHub App, execute o comando a seguir.

    Observação

    Crie o segredo no mesmo namespace onde o gráfico gha-runner-scale-set está instalado. Neste exemplo, o namespace é arc-runners para corresponder à documentação de início rápido. Para saber mais, confira Guia de início rápido do Actions Runner Controller.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_app_id=123456 \
   --from-literal=github_app_installation_id=654321 \
   --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

    Usando a propriedade githubConfigSecret em sua cópia do arquivo values.yaml, passe o nome do segredo como uma referência.

    githubConfigSecret: pre-defined-secret

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como autenticar o ARC com um personal access token (classic)

O ARC pode usar o personal access tokens (classic) para registrar executores auto-hospedados.

Observação

A autenticação do ARC com um personal access token (classic) é o único método de autenticação com suporte para registrar executores na empresa.

  1. Crie um personal access token (classic) com os escopos necessários. Os escopos necessários são diferentes, dependendo se você está registrando executores no nível do repositório, da organização ou da empresa. Para saber mais sobre como criar um personal access token (classic), confira Gerenciar seus tokens de acesso pessoal.

    Veja a seguir a lista de escopos necessários do personal access token para executores do ARC.

    • Executores do repositório: repo
    • Executores da organização: admin:org
    • Executores da empresa: manage_runners:enterprise

  2. Para criar um segredo do Kubernetes com o valor do personal access token (classic), execute o comando a seguir.

    Observação

    Crie o segredo no mesmo namespace onde o gráfico gha-runner-scale-set está instalado. Neste exemplo, o namespace é arc-runners para corresponder à documentação de início rápido. Para saber mais, confira Guia de início rápido do Actions Runner Controller.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. Na sua cópia do arquivo values.yaml, transmita o nome do segredo como uma referência.

    githubConfigSecret: pre-defined-secret

    Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como autenticar o ARC com um fine-grained personal access token

O ARC pode usar o fine-grained personal access tokens para registrar executores auto-hospedados.

Observação

A autenticação do ARC com um personal access token (classic) é o único método de autenticação com suporte para registrar executores na empresa.

  1. Crie um fine-grained personal access token com os escopos necessários. Os escopos necessários são diferentes dependendo de você estar registrando executores no nível do repositório ou da organização. Para saber mais sobre como criar um fine-grained personal access token, confira Gerenciar seus tokens de acesso pessoal.

    Veja a seguir a lista de escopos necessários do personal access token para executores do ARC.

    • Executores do repositório:

      • Administração: leitura e gravação

    • Operadores da organização:

      • Administração: leitura
      • Executores auto-hospedados: leitura e gravação

  2. Para criar um segredo do Kubernetes com o valor do seu fine-grained personal access token, use o comando a seguir.

    Observação

    Crie o segredo no mesmo namespace onde o gráfico gha-runner-scale-set está instalado. Neste exemplo, o namespace é arc-runners para corresponder à documentação de início rápido. Para saber mais, confira Guia de início rápido do Actions Runner Controller.

    Bash
    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. Na sua cópia do arquivo values.yaml, transmita o nome do segredo como uma referência.

    githubConfigSecret: pre-defined-secret

    Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Autenticar ARC com segredos do cofre

Observação

A integração do cofre está atualmente disponível em visualização pública com suporte para o Azure Key Vault.

A partir do gha-runner-scale-set versão 0.12.0, o ARC dá suporte à recuperação de credenciais do GitHub de um cofre externo. A integração do cofre é configurada por conjunto de dimensionamento de executores. Isso significa que você pode executar alguns conjuntos de dimensionamento usando segredos do Kubernetes, enquanto outros usam segredos baseados em cofre, dependendo de seus requisitos operacionais e de segurança.

Habilitar a integração do cofre

Para habilitar a integração do cofre em um conjunto de dimensionamento de executores:

  1. Defina o campo githubConfigSecret no arquivo values.yaml como o nome da chave secreta armazenada em seu cofre. Esse valor precisa ser uma cadeia de caracteres.
  2. Remova marca de comentário e configure a seção keyVault no arquivo values.yaml com o provedor apropriado e os detalhes de acesso.
  3. **Forneça o certificado ** necessário (.pfx) ao controlador e ao ouvinte. Para fazer isso: *Recompile a imagem do controlador com o certificado incluído ou *Monte o certificado como um volume no controlador e no ouvinte usando os campos listenerTemplate e controllerManager.

Formato do segredo

O segredo armazenado no Azure Key Vault deve estar no formato JSON. A estrutura depende do tipo de autenticação que você está usando:

Exemplo: Token do GitHub

{
  "github_token": "TOKEN"
}

Exemplo: Aplicativo GitHub

{
  "github_app_id": "APP_ID_OR_CLIENT_ID",
  "github_app_installation_id": "INSTALLATION_ID",
  "github_app_private_key": "PRIVATE_KEY"
}

Configurar values.yaml para a integração do Cofre

O certificado é armazenado como um arquivo .pfx e montado no contêiner em /akv/cert.pfx. Veja abaixo um exemplo de como configurar a seção keyVault para usar este certificado para autenticação:

keyVault:
  type: "azure_key_vault"
  proxy:
    http:
      url: "PROXY_URL"
      credentialSecretRef: "PROXY_CREDENTIALS_SECRET_NAME"
    http: {}
    noProxy: []
  azureKeyVault:
    clientId: <AZURE_CLIENT_ID>
    tenantId: <AZURE_TENANT_ID>
    url: <AZURE_VAULT_URL>
    certificatePath: "/akv/cert.pfx"

Fornecendo o certificado para o controlador e o ouvinte

O ARC requer um certificado .pfx para autenticar com o cofre. Esse certificado deve ser disponibilizado para os componentes do controlador e do ouvinte durante a instalação do controlador. Você pode fazer isso montando o certificado como um volume usando os campos controllerManager e listenerTemplate no arquivo values.yaml:

volumes:
  - name: cert-volume
    secret:
      secretName: my-cert-secret
volumeMounts:
  - mountPath: /akv
    name: cert-volume
    readOnly: true

listenerTemplate:
  volumeMounts:
    - name: cert-volume
      mountPath: /akv/certs
      readOnly: true
  volumes:
    - name: cert-volume
      secret:
        secretName: my-cert-secret

O código abaixo é um exemplo de um arquivo de conjunto de dimensionamento values.yml.

listenerTemplate:
  spec:
    containers:
      - name: listener
        volumeMounts:
          - name: cert-volume
            mountPath: /akv
            readOnly: true
    volumes:
      - name: cert-volume
        secret:
          secretName: my-cert-secret

Partes foram adaptadas do http://github.com/actions/actions-runner-controller/ de acordo com a licença Apache-2.0:

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.