GitHub Packages e GitHub Actions - Distribuindo contextos delimitados

Regras de negócio e testes de unidade

O ponto principal de todo sistema são as regras de negócio e, consequentemente, os testes de unidade. Se você organiza tudo e mantém a regra na aplicação, mas não executa testes automatizados, está jogando metade dos benefícios no lixo.

Por isso, a premissa era manter os processos centralizados. Hoje temos integrações com gateways de pagamento, com o site e, futuramente, com o App.

Todos esses canais devem seguir o mesmo fluxo, o mesmo processo e as mesmas regras. Logo, concentramos todas as interfaces (contratos) e fluxos no Core da aplicação, separados nos contextos que mencionei.

Se você já fez os cursos Modelando Domínios Ricos e Refatorando para Testes de unidade, sabe quanto eu valorizo a orientação a objetos na modelagem. Inclusive, costumo brincar que o Core precisa funcionar só com os objetos do contexto, sem depender de API ou de dados.

Com esses objetos funcionando, basta persistir o estado em um banco e expor tudo via API. Gosto de pensar assim.

Mais adiante, é justamente esse Core que vamos empacotar e publicar no GitHub Packages.

Múltiplas arquiteturas

Outro ponto importante é que os contextos nem sempre seguem o mesmo padrão, porque agem de forma independente. Por exemplo, o contexto de conteúdos é extremamente voltado para leitura, então não faz sentido ter nele uma estrutura complexa de validação.

Nesse caso, temos apenas repositórios expondo informações. Já o contexto de assinaturas precisa de uma validação muito mais firme, porque envolve pagamentos, dados sensíveis e muitos testes de unidade.

Ou seja, one size doesn't fit all. Em bom português, arquitetura não tem bala de prata.

Quanto menor, melhor

Um componente pequeno é fácil de mudar ou até de jogar fora. Além disso, uma única pessoa consegue gerenciá-lo.

Fácil entendimento

Componentes menores também são mais fáceis de entender. Mesmo dentro do meu negócio, há processos de marketing, por exemplo, que me tomam tempo.

Como funciona a sinalização de uma nova assinatura para a ferramenta de marketing? E como funciona o processo que coloca um aluno em um funil de vendas?

Esses processos podem ser simples quando tratados individualmente, mas ficam complexos quando convivem muito juntos. Assim, a ideia de um componente é executar o processo com o mínimo de esforço e informação, para que outros sistemas também possam usá-lo.

Com o GitHub Packages, esse componente vira uma dependência versionada que qualquer sistema da empresa consegue instalar.

Fácil manutenção

Como disse Robert C. Martin, o Uncle Bob, criar um software para rodar uma vez é fácil, mas criar um software para ser mantido por muito tempo é difícil. Na teoria tudo é lindo, mas na prática a teoria é outra, e às vezes as coisas precisam acontecer para ontem.

Embora eu odeie essa situação e lute para evitá-la, não podemos ser hipócritas e dizer que estamos livres disso. Então, gambiarras vão acontecer, mas devem ser raras, e uma boa divisão permite refazer um componente com facilidade.

Por exemplo, na integração com um gateway de pagamentos, usamos o SDK em .NET que o próprio gateway fornece, o que foi uma péssima decisão. Ele não atende em diversos pontos e ainda depende de versões anteriores do .NET.

Porém, como esse componente é pequeno, já temos uma issue aberta para refazê-lo com o RestSharp, chamando a API do gateway diretamente. Juntando isso a uma boa modelagem e a testes de unidade, conseguimos uma manutenção tranquila.

Deploy independente com GitHub Packages

Outra vantagem de componentes independentes é a publicação. Se os Jobs de integração, o site, a API e o App consomem esses componentes, uma simples modificação neles pode gerar um novo deploy de tudo.

Por isso, separamos os contextos em repositórios próprios e os distribuímos como pacotes NuGet. Nesse cenário, trabalhamos com versionamento semântico para não quebrar o que já está rodando.

Dessa forma, conseguimos distribuir versões novas de forma independente. Por exemplo, algumas funcionalidades do Core só deveriam afetar as integrações naquele momento, enquanto o site precisava continuar como estava.

Com uma referência direta entre projetos de uma mesma solução, isso não aconteceria de forma tão amena.

Iniciando um projeto

Para criar um pacote, basta gerar uma nova Class Library com um nome que faça sentido para o seu negócio.

dotnet new classlib -o MyContext

Não vou me ater ao código aqui. Então, abra o projeto, modifique o que desejar e certifique-se de que ele compila.

Gerando um pacote NuGet

Sempre que compilamos uma Class Library, o resultado é uma DLL, mas queremos gerar um pacote. Por isso, o primeiro passo é incluir algumas informações no arquivo .csproj.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>

    <PackageId>MyContext</PackageId>
    <Version>1.0.0</Version>
    <Authors>André Baltieri</Authors>
    <Company>balta.io</Company>
    <PackageDescription>My first package</PackageDescription>
    <RepositoryUrl>https://github.com/balta-io/MyContext</RepositoryUrl>
  </PropertyGroup>
</Project>

Essas informações vão dentro do pacote e ficam visíveis para quem for baixá-lo. Além disso, segundo a documentação do GitHub, o RepositoryUrl vincula o pacote publicado ao repositório correspondente.

Feito isso, podemos compilar e empacotar o projeto com os comandos abaixo.

dotnet build --configuration Release
dotnet pack --configuration Release

O comando pack gera um arquivo .nupkg na pasta bin/Release do projeto. A versão do pacote vem do .csproj que editamos.

Publicando o pacote no NuGet.org

Com o .nupkg gerado, você pode publicá-lo no NuGet.org e deixá-lo visível para todos que usam o Visual Studio, por exemplo. Para isso, basta se autenticar no site e fazer o upload do pacote.

Se preferir a linha de comando, use o comando abaixo.

dotnet nuget push "bin/Release/*.nupkg" -s nuget --skip-duplicate

O -s nuget indica que o destino é o NuGet.org. Já o --skip-duplicate evita erro quando aquela versão do pacote já existe.

Autenticação com token de acesso pessoal

Se usamos -s nuget para enviar um pacote ao NuGet público, basta trocar o source para publicar no GitHub Packages. O único detalhe é a autenticação, já que só usuários da sua empresa podem publicar.

Então, para publicar direto da sua máquina, você precisa de um PAT (Personal Access Token), gerado no seu perfil em Developer Settings. Segundo a documentação, um token clássico precisa do escopo write:packages para publicar e de read:packages para instalar.

dotnet nuget push "bin/Release/*.nupkg" -k <TOKEN> -s https://nuget.pkg.github.com/<ORGANIZATION>/index.json --skip-duplicate

Feito isso, o pacote já aparece em https://github.com/orgs/<ORGANIZATION>/packages.

Workflow de publicação no GitHub Packages

Assim, podemos substituir nosso token por ${{ secrets.GITHUB_TOKEN }}, e o GitHub cuida do resto. Vamos então criar o arquivo .yml na pasta .github/workflows, que é a estrutura da qual os GitHub Actions dependem.

# .github/workflows/main.yml
name: Build and deploy MyContext Package

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@main

    - name: Set up .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '5.0.x'
        source-url: https://nuget.pkg.github.com/<ORGANIZATION>/index.json
      env:
        NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    - name: Build with dotnet
      run: dotnet build --configuration Release

    - name: Create the Package
      run: dotnet pack --configuration Release

    - name: Publish
      run: dotnet nuget push "bin/Release/*.nupkg" -k ${{ secrets.GITHUB_TOKEN }} -s https://nuget.pkg.github.com/<ORGANIZATION>/index.json --skip-duplicate

Feito isso, basta enviar o código para a branch main, e o pacote chega ao GitHub Packages com deploy automatizado. A cada nova versão no .csproj, o workflow publica um pacote novo.

Vale uma observação para repositórios atuais. Se a organização restringir as permissões padrão do GITHUB_TOKEN, inclua no job a chave permissions com packages: write e contents: read.

Guardando usuário e token em secrets

Na configuração que usamos, o ${{ secrets.GITHUB_TOKEN }} não funcionava para ler pacotes de outro repositório. Por isso, a maneira mais segura de guardar usuário e token é usar os Secrets do repositório, em https://github.com/<ORGANIZATION>/<REPOSITORY>/settings/secrets/actions.

Os secrets funcionam como pares de chave e valor. Uma vez criados, você não consegue mais visualizá-los, apenas removê-los ou substituí-los.

Dessa forma, adicionamos mais um passo ao workflow de publicação da aplicação, que chamei de Add GitHub Packages Source.

- name: Set up .NET Core
  uses: actions/setup-dotnet@v1
  with:
    dotnet-version: '5.0.x'

- name: Add GitHub Packages Source
  run: dotnet nuget add source https://nuget.pkg.github.com/<ORGANIZATION>/index.json -n github -u ${{ secrets.PACKAGES_USER }} -p ${{ secrets.PACKAGES_TOKEN }} --store-password-in-clear-text

- name: Build with dotnet
  run: dotnet build --configuration Release

Pronto, você tem um deploy automatizado que consome um pacote privado do GitHub Packages, também publicado de forma automática.

Vale saber que a documentação atual do GitHub descreve uma alternativa. Em registros com permissões granulares, você adiciona o repositório consumidor em Manage Actions access, e o GITHUB_TOKEN passa a ler o pacote sem PAT.

Se você mantém vários repositórios com passos parecidos, vale também conhecer os workflows reutilizáveis no GitHub Actions. Com eles, o passo de autenticação fica centralizado em um único lugar.