Automatizando instalações de aplicativo nas organizações da sua empresa

Introdução

Para automatizar um processo com segurança, você pode criar um GitHub App de propriedade de uma conta corporativa e, em seguida, instalar o aplicativo na empresa ou organização em que a automação ocorrerá.

Os GitHub Apps fornecem tokens que podem ser usados por você para autenticar chamadas de API ao GitHub em scripts e fluxos de trabalho. Esses tokens são adequados para empresas com requisitos específicos de segurança e auditoria, pois são:

• Temporário
• Escopo definido para contas específicas e permissões
• Associado à identidade do aplicativo em vez de uma conta de usuário

Uma necessidade comum para grandes empresas é manter uma automação consistente e atualizada em várias organizações. Você pode fazer isso instalando um aplicativo programaticamente. Por exemplo, se precisar configurar todas as organizações com determinadas políticas e configurações, você poderá instalar um GitHub App para essa tarefa em cada organização.

Este guia demonstrará as etapas necessárias para instalar automaticamente um GitHub App pertencente à empresa em uma organização. Depois que o aplicativo for instalado, você o usará para criar um novo repositório.

Visão geral do processo

Neste guia, você usará a GitHub CLI para fazer as chamadas à API necessárias para solicitar tokens de acesso e instalar um aplicativo em uma organização. Na realidade, esse processo faria parte de um script personalizado adaptado às necessidades da sua empresa.

Você vai:

1. Crie dois aplicativos pertencentes à sua conta corporativa.
   • Um deles terá permissão para instalar aplicativos em organizações.
   • O outro terá permissão para automatizar um processo em uma organização (nesse caso, criar um repositório).
2. Autentique o primeiro aplicativo para obter um token de acesso com escopo empresarial.
3. Use o token com escopo empresarial para chamar uma API que instala o aplicativo de automação em uma organização.
4. Autenticar o aplicativo instalado pela organização para obter um token de acesso no escopo da organização.
5. Usar o token com escopo da organização para chamar uma API que cria um repositório na organização.

Em cada estágio, você usará um token que só tem permissão para executar ações específicas em uma conta específica. Do ponto de vista de segurança e auditoria, essa abordagem é superior a confiar apenas em um único token com permissão para executar ações em toda a sua empresa e organizações.

Pré-requisitos

Para seguir este guia em seu próprio dispositivo, você deve:

• Seja um proprietário da empresa.
• Seja proprietário de uma organização de propriedade empresarial em que você executará a automação.
• Ter a GitHub CLI instalada para fazer chamadas à API. Consulte Instalação no repositório GitHub CLI .
• Instale openssl para gerar um JSON Web Token (JWT). Muitos dispositivos têm o OpenSSL instalado por padrão. Você pode verificar executando openssl -v, que retorna um número de versão se instalado.
• Use um shell do Unix, como Bash, ZSH ou Git Bash.

1. Preparar para gerar um JWT

Para solicitar um token de acesso de um aplicativo, você precisa de um JWT (token Web JSON) gerado a partir da ID do cliente do aplicativo e da chave privada. Muitas linguagens de programação têm métodos internos para gerar um JWT. Neste tutorial, você usará um script Bash para gerar um JWT da linha de comando usando openssl.

1. Copie o conteúdo do script Bash para gerar um JWT do Gerando um JWT (Token Web JSON) para um aplicativo GitHub.

2. Salve o conteúdo em um novo arquivo no diretório inicial, chamado gen-jwt.sh.

3. Torne o script executável.

   Shell

   chmod +x ~/gen-jwt.sh
   

2. Criar dois aplicativos empresariais

Os GitHub Apps só podem gerar tokens com as permissões específicas e os escopos de conta que você permite. Nesta etapa, você criará dois aplicativos de propriedade empresarial: um com permissão de nível empresarial para instalar aplicativos e outro com permissão de nível de organização para criar um repositório.

a. Criar o aplicativo instalador

O "aplicativo instalador" será instalado na conta corporativa e terá permissão para instalar o outro aplicativo em uma organização.

1. Crie um novo aplicativo em sua conta corporativa.

   1. Vá para as configurações da sua conta corporativa.
   2. Na barra lateral esquerda, clique em GitHub Apps .
   3. Clique em Novo GitHub App.

2. Você pode deixar a maioria dos valores como padrões, exceto:

   • Chame o aplicativo YOUR-HANDLE-installer-app, substituindo YOUR-HANDLE pelo nome de usuário GitHub .
   • Defina a "URL da Home page" como https://github.com.
   • Desmarque Expirar tokens de autorização do usuário e, em "Webhook", desmarque Ativo.
   • Em "Permissões empresariais", forneça ao aplicativo permissões de leitura e gravação para instalações da organização Enterprise.

3. Depois de criar o aplicativo, copie a ID do cliente e salve-a como uma variável chamada INSTALLER_APP_CLIENT_ID. Por exemplo, na linha de comando:

   Shell

   export INSTALLER_APP_CLIENT_ID='abcde12345'
   

4. Na página do aplicativo, role para baixo e clique em Gerar uma chave privada. O arquivo de chave privada será baixado.

5. Anote o caminho do arquivo, que será semelhante a .~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem

6. Na barra lateral esquerda da página do aplicativo, clique em Instalar aplicativo e, em seguida, instale o novo aplicativo na conta corporativa. A instalação de um aplicativo dá ao aplicativo permissão para executar ações na conta.

7. Examine a URL no navegador para localizar a ID de instalação do aplicativo. Essa é uma cadeia de caracteres de números no final da /enterprises/ENTERPRISE/settings/installations/ID URL. Salve-o como a INSTALLER_APP_INSTALL_ID variável.

   Shell

   export INSTALLER_APP_INSTALL_ID='12345678'
   

8. Salve o nome da empresa em que o aplicativo está instalado como uma variável.

   Shell

   export ENTERPRISE='octo-enterprise'
   

b. Criar o aplicativo de automação

O "aplicativo de automação" será instalado em uma organização e terá permissão para criar repositórios nessa organização. Na realidade, você daria a esse aplicativo todas as permissões necessárias para automatizar um processo em suas organizações.

1. Crie um novo aplicativo em sua conta corporativa.

   • Chame o aplicativo YOUR-HANDLE-automation-app, substituindo YOUR-HANDLE pelo nome de usuário GitHub .
   • Defina a "URL da Home page" como https://github.com.
   • Desmarque Expirar tokens de autorização do usuário e, em "Webhook", desmarque Ativo.
   • Em "Permissões de repositório", conceda ao aplicativo permissões de leitura e gravação para a seção Administração.

2. Depois de criar o aplicativo, copie a ID do cliente e salve-a como a AUTOMATION_APP_CLIENT_ID variável.

   Shell

   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   

3. Role para baixo e clique em Gerar uma chave privada. O arquivo de chave privada será baixado.

4. Anote o caminho do arquivo, que será semelhante a .~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem

5. Salve o nome da organização em que o aplicativo será instalado como uma variável.

   Shell

   export ORG='octo-org'
   

3. Autenticar o aplicativo instalador

A autenticação de um aplicativo permite que você obtenha um token com o escopo e as permissões que você definiu quando registrou o aplicativo. Nesse caso, você obterá um token para o aplicativo instalador, o que lhe dará permissão para instalar o aplicativo de automação em uma organização.

1. Gere um JWT usando o script Bash que você salvou. Por exemplo:

   Shell

   ~/gen-jwt.sh $INSTALLER_APP_CLIENT_ID ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem
   

2. Copie o JWT (a cadeia de caracteres longa após JWT= ) e salve-o como uma variável.

   Shell

   export INSTALL_JWT='abcde12345'
   

3. Use o JWT para autenticar uma solicitação de um token de acesso de instalação. Esta etapa usa o endpoint da API Criar um token de acesso de instalação para um aplicativo e requer a ID de instalação do aplicativo.

   Shell

   gh api --method POST "/app/installations/$INSTALLER_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $INSTALL_JWT"
   

4. Você deve ver um objeto JSON que contém uma token propriedade. Copie o token de acesso (o valor da token propriedade, sem aspas) e salve-o como a INSTALLER_APP_INSTALL_TOKEN variável.

   Shell

   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   

4. Instalar o aplicativo de automação

O token de acesso de instalação que você acabou de receber oferece permissão para chamar a API para instalar aplicativos em uma organização. Aqui, usaremos o token para instalar o aplicativo de automação (o segundo aplicativo que você criou) em uma organização específica. Na realidade, você pode chamar essa API várias vezes para instalar um aplicativo em várias organizações.

1. Execute o comando a seguir. Estamos usando o endpoint de API para instalar um aplicativo do GitHub em uma organização pertencente a uma empresa, autenticando com o token de instalação que você acabou de solicitar e passando o ID do cliente do aplicativo de automação que queremos instalar.

   Shell

   gh api --method POST \
     "/enterprises/$ENTERPRISE/apps/organizations/$ORG/installations" \
     --header "Authorization: Bearer $INSTALLER_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "client_id=$AUTOMATION_APP_CLIENT_ID" \
     --field "repository_selection=all"
   

2. Se tiver êxito, você deverá ver um grande número de propriedades retornadas, começando com a ID de instalação do aplicativo.

   Para verificar se o aplicativo foi instalado com êxito, acesse https://github.com/organizations/ORG/settings/installations, substituindo ORG pelo nome da organização. Você deverá ver o aplicativo recém-instalado na página.

3. Localize a ID de instalação da nova instalação e salve-a como AUTOMATION_APP_INSTALL_ID. Para localizar a ID, você pode copiar a primeira propriedade de ID retornada pela API ou clicar em Configurar ao lado da instalação do aplicativo na interface do usuário e copiar a ID da URL.

   Shell

   export AUTOMATION_APP_INSTALL_ID='12345678'
   

5. Autenticar o aplicativo de automação

Assim como você autenticou o aplicativo instalador para obter um token com escopo empresarial, agora você precisa executar o mesmo processo para o aplicativo de automação. Isso fornecerá a você um token com o escopo da organização e permissão para criar repositórios.

1. Gere um JWT com a ID do cliente e a chave privada do aplicativo de automação. Por exemplo:

   Shell

   ~/gen-jwt.sh $AUTOMATION_APP_CLIENT_ID ~/octocat-automation-app.2025-10-08.private-key.pem
   

2. Copie o JWT (a cadeia de caracteres longa após JWT= ) e salve-o como uma variável.

   Shell

   export AUTO_JWT='abcde12345'
   

3. Use o JWT para autenticar uma solicitação de um token de acesso de instalação, desta vez passando a ID de instalação e o JWT para o aplicativo de automação recém-instalado.

   Shell

   gh api --method POST "/app/installations/$AUTOMATION_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $AUTO_JWT"
   

4. Copie o novo token de acesso de instalação e salve-o como a AUTOMATION_APP_INSTALL_TOKEN variável.

   Shell

   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   

6. Automatizar um processo

O token de instalação que você acabou de receber oferece permissão para criar um repositório na organização em que o aplicativo está instalado.

1. Execute o comando a seguir. Observe que estamos autenticando com o token de instalação que acabamos de obter.

   Shell

   gh api --method POST \
     "/orgs/$ORG/repos" \
     --header "Authorization: Bearer $AUTOMATION_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "name=automatic-repo" \
     --field "description=Repository created automatically using GitHub App automation" \
     --field "private=false" \
     --field "auto_init=true"
   

2. Para verificar se o repositório foi criado com êxito, acesse https://github.com/orgs/ORG/repositories, substituindo ORG pelo nome da sua organização.

          <a href="https://docs.github.io/success-test/yes.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline">
          <span>Sim</span></a><a href="https://docs.github.io/success-test/no.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline"><span>Não</span></a>

7. Desinstalar os aplicativos

Para segurança, desinstale os aplicativos da empresa e da organização. Isso revogará todos os tokens associados aos aplicativos. Para obter instruções, confira Revisão e modificação de aplicativos GitHub instalados.

Próximas etapas

Você viu como instalar um aplicativo programaticamente em organizações e executar uma automação. Agora, você deve estar pronto para automatizar um processo real em várias organizações. Para obter mais informações sobre o que os aplicativos podem fazer, consulte Sobre a criação de aplicativos GitHub.