Conhecendo o Backstage [Parte III]
Depois de um (longo) tempo desde o último post sobre a série dedicada ao Backstage, retomamos nossa trajetória. Porém, se você encontrou este post “por acaso”, recomendo que inicie a leitura pela Parte I. Assim você poderá compreender melhor o “caminho” que estou propondo.
Nesta terceira parte irei apresentar o processo para integração de uma organização do GitHub no Backstage.
Integração com o GitHub
Chegou o momento de começarmos a explorar o que o Backstage fornece de mais atrativo para a comunidade, e destaco para esta série a integração com o GitHub.
Como o objetivo do Backstage é auxiliar organizações/companhias a centralizar informações de seus departamentos de tecnologia, irei propor um cenário para que nosso processo de descoberta da ferramenta faça mais sentido:
- Iremos criar uma GitHub Org “Fake”*;
- Após criada a organização, crie (ao menos) cinco repositórios simples e privados na mesma;
- Adicione alguns times/squads.
OBSERVAÇÃO: Não se preocupe, você não terá custos. Essa proposta é para que nos aproximemos do cenário real, ou seja, produtivo, em que o Backstage é implementado.
Bom, deste ponto em diante partiremos do princípio que você seguiu minha proposta de cenário para que continuemos com o desenvolvimento de nosso aplicativo Backstage.
Autenticação utilizando GitHub
Iremos criar nosso próprio sistema de autenticação para nosso aplicativo Backstage. Se você ainda não se atentou, nossa aplicação está “aberta” e poderia ser acessada por qualquer usuário da Internet. Aí você pode pensar: “Mas Paulo, nossa aplicação só roda no ambiente local!”, sim meu amigo (a), mas a ideia é proporcionar uma base de conhecimento para que você possa desenvolver uma aplicação que será utilizada no ambiente produtivo.
Vamos então, desenvolver nossa autenticação com base no GitHub a partir deste ponto:
1. Acesse o link a seguir, substituindo a “variável” your-org-fake pelo nome da organização criada anteriormente:
https://github.com/organizations/{your-org-fake}/settings/applications/new
IMPORTANTE: Para este tutorial criei a organização “Tutorial Backstage”
2. Preencha as informações, conforme imagem a seguir:
Após concluir os cadastros, basta clicar em “Register application”.
OBSERVAÇÃO: Se quiser apenas utilizar a mágica do “Ctrl+C” e “Ctrl+V”, segue:
Application name: Backstage Tutorial
Homepage URL: http://localhost:3000
Autorization callback URL: http://localhost:7007/api/auth/github/handler/frame
3. Será gerada uma “Client ID” na tela seguinte, copie este valor.
4. Na seção “Client secrets”, clique no botão “Generate a new client secret”, conforme destacado:
Provavelmente o GitHub solicitará que você confirme essa ação. Seja através de senha, ou autenticação em dois fatores.
ATENÇÃO!
Será gerada uma credencial para seu Aplicativo, não deixe de copiar os valores antes de qualquer ação.
5. Agora iremos atualizar nosso arquivo .env, com as variáveis GITHUB_AUTH_CLIENT_ID e GITHUB_AUTH_CLIENT_SECRET, com os valores do “Client ID” e “Client secrets” descritos nos “passos 3 e 4” respectivamente.
6. No arquivo app-config.yaml, iremos invocar as variáveis criadas, de maneira que nosso código ficará semelhante ao apresentado a seguir:
7. Ao rodar o comando direnv allow, você deverá receber algo parecido em seu terminal:
direnv: loading ~/Projects/backstage-studies/.envrc
direnv: export +GITHUB_AUTH_CLIENT_ID +GITHUB_AUTH_CLIENT_SECRETS +POSTGRES_DB +POSTGRES_HOST +POSTGRES_PASSWORD +POSTGRES_PORT +POSTGRES_USER8. No arquivo App.tsx(packages/app/src/App.tsx) realizaremos algumas adequações no código:
9. Reinicie sua aplicação com o comando yarn dev.
10. Será exibida a tela solicitando seu login com sua conta GitHub, basta você autorizar o aplicativo de autenticação que criamos conforme imagem abaixo:
IMPORTANTE: Se você clicar no menu lateral na opção “Settings”, poderá visualizar que os dados da sua conta no GitHub serão exibidos:
Configurando a integração Backstage <> GitHub
“Como assim, Paulo? Já não configuramos isso desde o início desta seção?”. Provavelmente estas foram potenciais perguntas que você fez, e a resposta é que nós começamos a configurar a integração partindo da autenticação, de maneira que não permitamos que usuários que não estejam vinculados a nossa organização acessem nossa aplicação.
A partir deste ponto, iremos configurar a integração que permitirá ao nosso aplicativo, ler e exibir informações sobre:
- Usuários;
- Equipes/Times;
- Repositórios.
Requisitos
Para prosseguir com esta configuração, é necessário que:
- A configuração de autenticação implementada;
- Aplicação esteja “parada” (basta rodar
Ctrl+Cno seu terminal).
Passo a passo
1. Rode o comando yarn add --cwd packages/backend @backstage/integration @backstage/plugin-catalog-backend-module-github para instalar as dependências necessárias para a nossa integração com o GitHub.
2. Rode o comando a seguir, substituindo a “variável” your-org-fake pelo nome da organização que você criou, para gerar automaticamente (através da CLI do Backstage) as credenciais necessárias para a integração: yarn backstage-cli create-github-app {your-org-fake}
3. Será exibida a seguinte mensagem de confirmação, marque o terceiro item e tecle “Enter”, mas não se preocupe, iremos detalhar as configurações necessárias:
4. Você será direcionado, novamente, para o GitHub e será solicitado que você registre um nome para o GitHub App:
IMPORTANTE: Quando você confirmar a criação, será gerado em seu projeto um arquivo com a seguinte “estrutura de nome”:
github-app-{{nome-indicado-para-o-app}}-credentials.yaml. Além disso, será exibido em seu terminal uma sugestão de configuração (que iremos utilizar em breve).
5. Instale o aplicativo criado em todos os repositórios da sua organização:
A partir deste ponto, iremos configurar as permissões que nosso GitHub App precisa para que a integração seja eficiente junto ao Backstage.
6. Clique na guia “App settings” conforme destacado:
7. No menu lateral esquerdo, clique em “Permissions & events”:
8. Agora iremos conceder as permissões mínimas que o Backstage precisa para acessar as informações de nossa organização:
Repository Permissions
Metadata — Read-only
Contents — Read and write
Pull-Request — Read and write
Organization Permissions
Members — Read-only
9. Após concluir as adequações, clique em “Save changes”.
10. Será necessária a aprovação do GitHub App em nossa organização. Mesmo você sendo o owner, é uma questão de segurança que o GitHub aplica para “nos proteger” de ações involuntárias ou mesmo ataques. Para isso, acesse o link (substituindo a “variável” your-org-fake pelo nome da organização que você criou): https://github.com/organizations/{your-org-fake}/settings/installations
11. Clique em “Review request” e na tela a seguir em “Accept new permissions”.
ATENÇÃO: Toda vez que você alterar alguma permissão do seu GitHub App será necessária uma NOVA aprovação.
12. No arquivo app-config.yaml iremos adicionar os parâmetros de configuração para nossa integração. E destaque para o arquivo que foi gerado em nosso “passo 4” desta seção, pois ele será utilizado aqui:
13. Agora iremos realizar adequações no arquivo catalog-ts(packages/backend/src/plugins/catalog.ts):
14. Rode o comando yarn dev para iniciar a aplicação novamente.
Você deve perceber que na guia “Catalog” não recebemos mais nenhum projeto na lista, e aí deve estar se perguntando “Ué Paulo?! Tu não disse que nós integramos a nossa organização com o Backstage?”. A resposta é sim, e nós já concluímos este processo. Porém, a listagem de projetos ainda necessita de mais alguns pequenos detalhes que iremos nos aprofundar na seção Catálogo de Software. Para fechar este “capítulo”, vou lhe dar uma dica para validar se os usuários e times estão sendo listados:
- Clique no dropdown no canto superior esquerdo (conforme destacado abaixo) e selecione “Users” ou “Groups” para validar que apenas os usuários e times cadastrados em sua organização estão sendo exibidos.
Essa é uma série de post’s, então não deixe de ler as outras “partes”:
- Parte I — Conhecendo o Backstage
- Parte II — Utilizando o Banco de Dados
- Parte III (este post)