Pular para o conteúdo principal

GitHub

Nesta seção, você encontra como integrar o SCM com o provedor GitHub usando o StackSpot Workflow.


A integração do seu

SCM
com a StackSpot traz benefícios para as equipes e podem ser executados remotamente via pipeline de CI/CD.

Atualmente, a StackSpot possui 5 fluxos possíveis de serem executados:

  1. Criação de Aplicação;
  2. Criação de Infraestrutura;
  3. Aplicação de Plugins;
  4. Execução de Actions.
  5. Execução de Workflows.

Pré-Requisito

1. Ter um repositório para as pipelines

Para integrar o SCM com a StackSpot, o primeiro passo é ter um repositório próprio da sua Organização para as pipelines. Desta forma, quando definidas, você poderá acioná-las remotamente via API informando os dados de entrada para cada fluxo.

Você pode utilizar um já existente, ou criar um novo. Confira aqui como criar um repositório no GitHub.

2. Gerar o Personal Access Token no GitHub

  • Você precisa ter permissão de escrita no repositório do Workflow para seguir os próximos passos.
  1. Acesse a sua conta do GitHub e faça o login;
  2. Clique sobre a sua foto e em seguida, em 'Settings';
  3. Ao final da página, clique em 'Developer Settings';
  4. Agora clique em 'Personal Access Tokens' e, em seguida no mesmo menu, clique na opção 'Tokens Classic';
  5. Dentro da seção clique no botão 'Generate new Token' e selecione a opção 'Generate new Token (classic)';
  6. No formulário "New personal access token (classic)", preencha na sequência o campo 'Note' com a descrição do objetivo do token. Em seguida, clique no botão "Expiration" e selecione ou defina um prazo de expiração para o seu token;
  7. Em seguida, na seção "Select scopes", marque as seguintes checkbox na sequência:
  • Todas as opções de "repo":
    • repo:statusAccess;
    • repo_deployment;
    • public_repo;
    • repo:invite;
    • security_events.
  • A opção "workflow";
  • A opção "write:packages".

Confira um exemplo na imagem a seguir:

Imagem com as permissões 'repo, workflow e write:packages selecionadas'
Informação Adicional

Os escopos podem depender das atividades que sua empresa precisa executar. Por isso, selecione todos os que são necessários para você.

  1. Ao final da página clique no botão 'Generate Token'. O código gerado será exibido temporariamente, copie e salve o código gerado.

  2. (Opcional) Se a sua organização possuir o login via SSO (Single Sign On) configurado, autorize o seu Token:

  • No GitHub, acesse 'Settings' e depois 'Developer Settings'. No seu token, clique no botão 'Configure SSO':

Os gifs/imagens são um exemplo, procure pelo nome da sua Organização no GitHub.

Em seguida, consulte se o seu token foi autorizado conforme o exemplo a seguir:

Página localizada no menu Settings/ Developer Settings > Personal access tokens (classic) para consultar o token autorizado.

Para mais informações sobre o Personal Access Token, consulte a documentação do GitHub.

Configurar as pipelines automaticamente (Recomendado)

Os passos a seguir são feitos via STK CLI; Para criar as pipelines automaticamente, você precisa ter um repositório criado. Confira como criar um repositório no GitHub.

Passo 1. Execute os comandos a seguir:

  1. Se estiver com um Workspace ativo, use o comando a seguir para sair do Workspace:
stk exit workspace
  1. Após sair do Workspace, execute o Workflow com o comando a seguir:
stk run workflow stackspot-core/stackspot-setup-scm@3

Passo 2. O terminal pergunta qual é o seu provedor SCM. Selecione a opção GitHub.

Passo 3. Responda as seguintes perguntas:

  • Organization name: informe o nome do seu usuário do GitHub.
  • Repository Name: informe o nome do repositório que você criou para executar os Workflows da StackSpot.
  • Personal Access Token: informe o Personal Access Token gerado anteriormente no GitHub.
  • The repository to setup scm already exists? (Y/n): responda 'Y' para sim e 'n' para não. Para informar se o repositório da configuração do SCM já existe.
  • Want to do the setup in main branch or create a pull request? (Y/n): responda 'Y' para sim e 'n' para não. Ao escolher 'Y' (sim), informe em Target branch a branch usada para criar o pull request ou informe 'n' (não) para manter a configuração na branch 'main'.
Atenção!

O usuário do token e o próprio Personal Access Token precisam ter permissão de escrita no repositório da organização. Caso o repositório não exista,você deve adicionar a permissão para criar repositórios.

Dica!

Em alguns SCMs o Project Name e Repository Name podem significar a mesma coisa. Confira a seguir como identificar esses campos na URL:

https://github.com/[GITHUB-USERNAME]/[REPOSITORY-NAME]

Exemplo:
https://github.com/stack-spot/stackspot-workflows-action

Para mais informações, siga a documentação do GitHub.

Este não é o Personal Access Token do Portal.

Create a repository: Esta opção é exibida no terminal caso a Action não encontre nenhum repositório. Por isso, você deve informar a opção Sim para criar um novo repositório. Caso responda Não a Action será encerrada.

Confira o seu repositório no GitHub, na seção Actions. Nela o "StackSpot workflow dispatch" estará configurado. Dentro das Configurações do seu projeto no GitHub, o Webhook também já está configurado.

Se a configuração foi executada com sucesso, o próximo passo é fazer a integração do GitHub com a sua conta da StackSpot.

Se não foi possível concluir a configuração de forma automática, siga os passos a seguir para realizar toda a configuração manualmente:

Criar o repositório e pipelines manualmente

Passo 1. No terminal STK CLI, execute os comandos a seguir:

mkdir <repo-name>
cd <repo-name>
mkdir .github
cd .github
mkdir workflows

Exemplo:

mkdir repo-runner-actions
cd repo-runner-actions
mkdir .github
cd .github
mkdir workflows

Passo 2. Crie o arquivo "stackspot.yml" no caminho ".github/workflows" com o seguinte conteúdo:

.github/workflows/stackspot.yml
name: Stackspot resume workflow
on:
  workflow_dispatch:
    inputs:
      workflow_execution_id:
        type: text
        required: true
      workflow_inputs:
        type: text
        required: false
jobs:
  run:
    name: Run workflow
    runs-on: ubuntu-latest
    env:
      LANG: C.UTF-8
      LANGUAGE: C.UTF-8
      LC_ALL: C.UTF-8
      PYTHONIOENCODING: utf-8
      HTTP_ENABLE_DEBUG: false
    steps:
      - name: "[StackSpot] Install CLI"
        run: |
          cd /tmp
          curl -fsSL https://stk.stackspot.com/install.sh | bash         
          echo "~/.stk/bin" >> $GITHUB_PATH
          stk --version
          stk upgrade

      - name: "[StackSpot] Login"
        run: |
          stk login -id ${{ secrets.STK_CLIENT_ID }} -key ${{ secrets.STK_CLIENT_KEY }} -r ${{ vars.STK_REALM }}

      - name: "[StackSpot] run workflow"
        run: |
          stk resume workflow ${{ inputs.workflow_execution_id }}

Passo 3. Faça o commit das alterações utilizando os comandos a seguir:

git init
git remote add origin https://github.com/<github-username>/<repository-name>.git
git add .
git commit -m "Setup Runner"
git push

Exemplo:

git init
git remote add origin https://github.com/my-username/repo-runner-actions.git
git add .
git commit -m "Setup Runner"
git push
Dica!

Em alguns SCMs o Project Name e Repository Name podem significar a mesma coisa. Confira a seguir como identificar esses campos na URL:

https://github.com/[GITHUB-USERNAME]/[REPOSITORY-NAME]

Exemplo:
https://github.com/stack-spot/stackspot-workflows-action

Passo 4. Configure um Webhook no repositório criado. Sigas as instruções a seguir:

  1. Acesse a sua conta do GitHub e faça o login;
  2. Clique sobre a sua foto e em seguida, em 'Your repositories';
  3. Clique no repositório criado para executar as pipelines e, em seguida, clique em 'Settings';
  4. Agora clique em Webhooks e, em seguida, clique no botão Add webhook;
  5. Preencha os campos com as informações a seguir:
  • Payload: ereencha com o endereço: https://workflow-api.v1.stackspot.com/workflows/github/callback;
  • Content type: selecione a opção application/json;
  • Secret: --- (Não preencher);
  • SSL Verification: marque a opção 'Enable SSL verification';
  • Which events would you like to trigger this webhook? selecione a resposta 'Let me select individual events':
    • Uma lista de checkbox será carregada, marque a opção 'Workflow runs';
  1. Marque a opção 'Active';
  2. Para finalizar, clique no botão 'Add webhook'.

Página de configuração de Webhooks no GitHub, destacando os passos para adicionar um novo webhook com as configurações específicas para integração com a StackSpot.

Se a configuração foi executada com sucesso, o próximo passo é fazer a integração do GitHub com a sua conta da StackSpot.

Integrar o Github com a StackSpot

Os passos a seguir são feitos no Portal da StackSpot.

Configurar via GitHub PAT (Personal Access Token)

Atenção!

Por segurança, credenciais como o Personal Access Token (PAT) são armazenadas de forma criptografada na StackSpot. Após serem salvos, não é possível consultar ou visualizar novamente essas informações pela plataforma.

Passo 1. Acesse diretamente link do Portal da Conta; ou após fazer login no Portal StackSpot, clique no seu avatar de perfil;

Passo 2. Clique na opção 'Organização';

Passo 3. No Portal da Conta, clique em 'EDP' e depois clique em ’SCM’;

Passo 4. Em seguida, clique no botão Configurar Integração SCM’. No campo Selecione um Provedor, selecione a opção GitHub;

Passo 5. Em Método de autenticação, selecione a opção PAT (Personal Access Token) e preencha os seguintes campos:

Passo 6. Em Configuração de Workflow, escolha como a Organização deseja gerenciar o acesso ao SCM. Para isso, habilite ou desabilite a opção 'A organização vai gerenciar o acesso ao SCM via User PAT?':

  • Habilitado: O usuário irá gerenciar o acesso ao GitHub via PAT (Personal Access Token) ou GitHub App.
  • Desabilitado: A empresa irá gerenciar o acesso ao GitHub.

Passo 7. No campo URL do Workflow, insira a URL do repositório criado com as pipelines para a StackSpot identificar onde o seu workflow está configurado. Por exemplo: https://github.com/my-organization/repo-runner-actions.

Passo 8. Você será redirecionado para a tela de Review. Confira seus dados e clique em 'Integrar com StackSpot'.

Pronto, sua configuração está completa.

Configurar via GitHub App

Antes de começar:

Você deve criar um GitHub App se você não possuir um. Para saber como, acesse a documentação oficial do GitHub.

Atenção!

No GitHub, depois de criar o App, conceda os seguintes acessos:

  1. Acesse o menu 'Settings > Developer settings > GitHub Apps';

  2. Localize o seu App e clique no botão 'Edit';

  3. Clique no menu 'Permissions & events' e, em seguida, abra o menu 'Repository permissions';

  4. Na lista de ações, conceda a permissão de 'Read and write' para os itens e salve as mudanças:

  • Contents
  • Pull requests

Página de Apps do GitHub

Se o seu App criar workflows, você precisa conceder a permissão de 'Read and write' para 'Workflows':


Página de Apps do GitHub

Se o seu App precisa acessar Actions para manipular workflows, workflow runs ou artefatos, você precisa conceder a permissão de 'Read and write' para 'Actions':


Página de Apps do GitHub

Você deve conceder os acessos para cada recurso que o seu App precisar.

Após instalar o App em sua Conta ou Organização, selecione os repositórios que você deseja trabalhar com a StackSpot. Para isso, siga os passos a seguir:

  1. No GitHub, acesse o menu 'Settings > Applications';

  2. Localize o seu App e clique no botão 'Configure';

  3. No menu 'Repository access', marque a opção 'Only select repositories' e selecione os repositórios que você deseja trabalhar com a StackSpot.


Página de integrações do GitHub

Após conceder os acessos ao seu App, siga os passos a seguir:

Passo 1. Acesse diretamente link do Portal da Conta; ou após fazer login no Portal StackSpot, clique no seu avatar de perfil;

Passo 2. Clique na opção 'Organização';

Passo 3. No Portal da Conta, clique em 'EDP' e depois, clique em 'SCM';

Passo 4. Em seguida, clique em ’Adicionar Integração SCM’. No campo Select a provider, selecione o GitHub;

Passo 5. Em Método de autenticação, selecione a opção GitHub APP e preencha os seguintes campos:

  • AppID: ID da Aplicação, por exemplo, 145236.
  • InstallerID: ID de instalação do APP, encontrado ao final da url, por exemplo, URL:https://github.com/settings/installations/88969132, o InstallerID será o valor: 88969132.
Informação Adicional

Todas as informações que você precisa para preencher os campos do GitHub App podem ser acessados em:

  • Para usuários: Navegue para Settings > Applications > Your GitHub App. Os dados estarão nas opções: General, Permissions & Events, Install App, Advanced e Optional features.

  • Para organizações: Navegue pra Settings > Installed GitHub Apps. Os dados estarão nas opções: General, Permissions & Events, Install App, Advanced e Optional features.

Passo 6. Faça o upload do arquivo .pem da Private Key e clique no botão 'Próximo passo';

Passo 7. Em Configuração de Workflow, desabilite a opção 'A organização vai gerenciar o acesso ao SCM via User PAT?'.

Informação Adicional

Ao habilitar este botão, os Membros da sua Conta terão que configurar o Acesso de SCM individual deles.

Passo 8. No campo URL do Workflow, insira a URL do repositório criado com as pipelines para a StackSpot identificar onde o seu workflow está configurado. Por exemplo: https://github.com/my-organization/repo-runner-actions.

Passo 9. Você será redirecionado para a tela de Review. Confira seus dados e clique no botão 'Integrar com StackSpot'.

Pronto, sua configuração está completa.