GitHub
Nesta seção, você encontra como integrar o SCM com o provedor GitHub.
A integração do seu
- Criação de Aplicação;
- Criação de Infraestrutura;
- Aplicação de Plugins;
- Execução de Actions.
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.
- Acesse a sua conta do Github e faça o login;
- No menu localizado no lado superior direito da página, clique sobre a sua foto e em seguida, em 'Settings';
- No menu principal, ao final do menu, clique em 'Developer Settings';
- No menu principal, clique em 'Personal Access Tokens' em seguida no mesmo menu, clique na opção 'Tokens Classic';
- Dentro da seção, à esquerda na página, localize e clique no botão 'Generate new Token' e selecione a opção 'Generate new Token (classic)';
- O formulário "New personal access token (classic)" é carregado, 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;
- 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".
Como na imagem:
Os escopos podem depender das atividades que sua empresa precisa executar. Por isso, selecione todos os que são necessários para você.
-
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.
-
(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' e no seu token, clique em 'Configure SSO':
Em seguida, consulte se o seu token foi autorizado conforme o exemplo:
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 GitHhub.
Passo 1. Abra seu terminal e clone o repositório da Action:
git clone https://github.com/stack-spot/stackspot-workflows-action.git
O conteúdo é salvo dentro da sua pasta corrente.
Passo 2. Acesse a pasta do repositório clonado e execute o comando:
cd stackspot-workflows-action
stk run action .
Passo 3. O terminal pergunta qual é o seu provedor SCM. Selecione a opção GitHub.
Passo 4. Responda as seguintes perguntas:
- Personal Access Token: Informe o Personal Access Token gerado anteriormente no GitHub.
- 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.
Se o repositório informado existir e nele também existir a branch main
, um Pull Request será criado para a main
.
Se o repositório não existir, a Action cria o repositório e a branch main
.
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.
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.
Não é o Personal Access Token do Portal.
- Create a repository: Essa opção aparece no terminal caso a Action não encontre nenhum repositório, você deve informar a opção Sim para criar um novo repositório. Caso responda Não a Action será encerrada.
Pronto! A Action foi executada.
Confira o seu repositório no GitHub, na seção Actions. Você verá o "Stackspot workflow dispatch" 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:
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 "middle-flow.yml" no caminho ".github/workflows" com o seguinte conteúdo:
name: Stackspot workflow dispatch
run-name: ${{ inputs.correlation_id }}
on:
workflow_dispatch:
inputs:
correlation_id:
description: Correlation id
required: true
workflow_name:
description: Workflow path
required: true
secrets:
description: Secrets info (json)
required: true
api_inputs:
description: Workflow inputs (json)
required: true
jobs:
run:
name: Run workflow ${{ github.event.inputs.workflow_name }}
runs-on: ubuntu-latest
steps:
- name: Running ${{ inputs.workflow_name }}
run: |
secret_stk_login=$(echo '${{ inputs.secrets }}' | jq -cr '.cli_token')
execution_id=$(echo '${{ inputs.api_inputs }}' | jq -cr '.execution_id')
http_code=$(curl -s -o script.sh -w '%{http_code}' https://workflow-api.v1.stackspot.com/workflows/$execution_id --header "Authorization: Bearer $secret_stk_login";)
if [[ "$http_code" -ne "200" ]]; then
echo "------------------------------------------------------------------------------------------"
echo "---------------------------------------- Debug Starting ----------------------------------"
echo "------------------------------------------------------------------------------------------"
echo "HTTP_CODE:" $http_code
echo "RESPONSE_CONTENT:"
cat script.sh
exit $http_code
echo "------------------------------------------------------------------------------------------"
echo "---------------------------------------- Debug Ending ------------------------------------"
echo "------------------------------------------------------------------------------------------"
else
chmod +x script.sh
echo "------------------------------------------------------------------------------------------"
echo "---------------------------------------- Starting ----------------------------------------"
echo "------------------------------------------------------------------------------------------"
bash script.sh
echo "------------------------------------------------------------------------------------------"
echo "---------------------------------------- Ending ----------------------------------------"
echo "------------------------------------------------------------------------------------------"
fi
Passo 3. Faça o commit das alterações utilizando os comandos:
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
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:
- Acesse a sua conta do Github e faça o login;
- No menu localizado no lado superior direito da página, clique sobre a sua foto e em seguida, em 'Your repositories';
- Clique no repositório criado para executar as pipelines e, em seguida, no menu clique em 'Settings';
- No menu principal, clique em Webhooks e em seguida no botão Add webhook;
- Preencha os campos com as informações a seguir:
- Payload: Preencha 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';
- Marque a opção 'Active';
- Para finalizar, clique no botão 'Add webhook'.
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)
Passo 1. Faça o login no Portal da StackSpot, no lado superior esquerdo da tela, clique no botão seletor e selecione a opção Conta;
Passo 2. No menu principal, na seção Configurações, clique em ’Integração de SCM’. Em seguida, clique no botão Configurar Integração SCM’;
Passo 3. No campo Select a provider, selecione GitHub;
Passo 4. Em Método de autenticação, selecione a opção PAT (Personal Access Token) e preencha os seguintes campos:
- Usuário: O nome do seu usuário no Github;
- Token: Utilize o seu Personal Access Token que você gerou anteriormente.
Passo 5. 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 6. 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 7. 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.
No GitHub, depois de criar o App, conceda os seguintes acessos:
-
Acesse o menu 'Settings > Developer settings > GitHub Apps';
-
Localize o seu App e clique no botão 'Edit';
-
Clique no menu 'Permissions & events' e em seguida, abra o menu 'Repository permissions';
-
Na lista de ações, conceda a permissão de 'Read and write' para os itens e salve as mudanças:
- Contents;
- Pull requests.
Se o seu App criar workflows, você precisa conceder a permissão de 'Read and write' para 'Workflows':
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':
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.
-
No GitHub, acesse o menu 'Settings > Applications';
-
Localize o seu App e clique no botão 'Configure';
-
No menu 'Repository access', marque a opção 'Only select repositories' e selecione os repositórios que você deseja trabalhar com a StackSpot.
Após conceder os acessos ao seu App, siga os passos:
Passo 1. Faça o login na Plataforma da StackSpot e acesso o menu Conta;
Passo 2. No menu principal, na seção Configurações, clique em ’Integração de SCM’. Em seguida, clique em ’Adicionar Integração SCM’;
Passo 3. No campo Select a provider, selecione o GitHub;
Passo 4. 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
.
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 no menu principal 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 no menu principal nas opções: General, Permissions & Events, Install App, Advanced e Optional features.
Passo 5. Faça o upload do arquivo .pem
da Private Key e clique em 'Próximo passo';
Passo 6. Em Configuração de Workflow, desabilite a opção 'A organização vai gerenciar o acesso ao SCM via User PAT?'.
Ao habilitar este botão, os membros da sua conta terão que configurar o Acesso de SCM individual deles.
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.