Publicação automatizada de pacotes no pub.dev

Você pode automatizar a publicação a partir de:

• GitHub Actions,
• Google Cloud Build ou,
• De qualquer outro lugar, usando uma service account do GCP.

As seções a seguir explicam como a publicação automatizada é configurada e como você pode personalizar os fluxos de publicação de acordo com as suas preferências.

Ao configurar a publicação automatizada, você não precisa criar um segredo de longa duração que seja copiado para o seu ambiente de deploy automatizado. Em vez disso, a autenticação depende de tokens OpenID Connect temporários, assinados por GitHub Actions (veja OIDC para GitHub Actions) ou pelo Google Cloud IAM.

Você pode usar chaves exportadas de service account em ambientes de deploy onde não há um serviço de identidade disponível. Essas chaves exportadas são segredos de longa duração; elas podem ser mais fáceis de usar em alguns ambientes, mas representam um risco maior caso vazem acidentalmente.

Você pode configurar a publicação automatizada usando GitHub Actions. Isso envolve:

• Habilitar a publicação automatizada no pub.dev, especificando:

  • O repositório do GitHub e,
  • Um tag-pattern que deve corresponder para permitir a publicação.

• Criar um workflow do GitHub Actions para publicar no pub.dev.

• Enviar uma git tag para a versão que será publicada.

As seções a seguir descrevem como concluir essas etapas.

Para habilitar a publicação automatizada do GitHub Actions para o pub.dev, você precisa ser:

• Um uploader do pacote, ou,
• Um admin do publisher (se o pacote pertencer a um publisher).

Se você tiver permissão suficiente, pode habilitar a publicação automatizada da seguinte forma:

1. Acesse a aba Admin (pub.dev/packages/<package>/admin).

2. Encontre a seção Automated publishing.

3. Clique em Enable publishing from GitHub Actions. Isso solicita que você especifique:

   • Um repositório (<organization>/<repository>, exemplo: dart-lang/pana),
   • Um tag-pattern (uma string que contém {{version}}).

O repositório é o <organization>/<repository> no GitHub. Por exemplo, se o seu repositório for https://github.com/dart-lang/pana, você deve especificar dart-lang/pana no campo de repositório.

O tag pattern é uma string que deve conter {{version}}. Somente GitHub Actions acionadas por um push de uma tag que corresponda a este tag pattern poderão publicar o seu pacote.

Exemplo: um tag pattern como v{{version}} permite que GitHub Actions (acionadas por git tag v1.2.3 && git push v1.2.3) publiquem a versão 1.2.3 do seu pacote. Por isso, também é importante que a chave version no pubspec.yaml corresponda a este número de versão.

Se o seu repositório contiver vários pacotes, dê a cada um um tag-pattern separado. Considere usar um tag-pattern como my_package_name-v{{version}} para um pacote chamado my_package_name.

Quando a publicação automatizada a partir do GitHub Actions está habilitada no pub.dev, você pode criar um workflow do GitHub Actions para publicação. Isso é feito criando um arquivo .github/workflows/publish.yml da seguinte forma:

# .github/workflows/publish.yml
name: Publish to pub.dev
​
on:
  push:
    tags:
    # must align with the tag-pattern configured on pub.dev, often just replace
      # {{version}} with [0-9]+.[0-9]+.[0-9]+
    - 'v[0-9]+.[0-9]+.[0-9]+' # tag-pattern on pub.dev: 'v{{version}}'
    # If you prefer tags like '1.2.3', without the 'v' prefix, then use:
    # - '[0-9]+.[0-9]+.[0-9]+' # tag-pattern on pub.dev: '{{version}}'
    # If your repository contains multiple packages consider a pattern like:
    # - 'my_package_name-v[0-9]+.[0-9]+.[0-9]+'
​
# Publish using the reusable workflow from dart-lang.
jobs:
  publish:
    permissions:
      id-token: write # Required for authentication using OIDC
    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
    # with:
    #   working-directory: path/to/package/within/repository

Certifique-se de que o padrão em on.push.tags corresponda ao tag pattern especificado no pub.dev. Caso contrário, o workflow do GitHub Action não funcionará. Se você publicar vários pacotes a partir do mesmo repositório, use um tag pattern por pacote, como my_package_name-v{{version}}, e crie um arquivo de workflow separado para cada pacote.

O arquivo de workflow acima usa dart-lang/setup-dart/.github/workflows/publish.yml para publicar o pacote. Trata-se de um workflow reutilizável que permite que a equipe do Dart mantenha a lógica de publicação e que o pub.dev saiba como o pacote foi publicado. Recomenda-se fortemente usar este workflow reutilizável.

Se o seu pacote precisar de código gerado, é preferível versionar esse código gerado no seu repositório. Isso simplifica a verificação de que os arquivos publicados no pub.dev correspondem aos arquivos do seu repositório. Se versionar código gerado ou artefatos compilados no repositório não for viável, você pode criar um workflow personalizado, seguindo este modelo:

# .github/workflows/publish.yml
name: Publish to pub.dev
​
on:
  push:
    tags:
    - 'v[0-9]+.[0-9]+.[0-9]+' # tag pattern on pub.dev: 'v{{version}'
​
# Publish using custom workflow
jobs:
  publish:
    permissions:
      id-token: write # Required for authentication using OIDC
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
      - name: Install dependencies
        run: dart pub get
      # Here you can insert custom steps you need
      # - run: dart tool/generate-code.dart
      - name: Publish
        run: dart pub publish --force

O workflow se autentica no pub.dev usando um token OIDC assinado pelo GitHub temporário. O token é criado e configurado no passo dart-lang/setup-dart. Para publicar no pub.dev, os passos seguintes podem executar dart pub publish --force.

Depois de configurar a publicação automatizada no pub.dev e criar um workflow do GitHub Actions, você pode publicar uma nova versão do seu pacote. Para publicar, envie uma git tag que corresponda ao tag pattern configurado.

$ cat pubspec.yaml

package: my_package_name
version: 1.2.3            # must match the version number used in the git tag
environment:
  sdk: ^2.19.0

$ git tag v1.2.3          # assuming my tag pattern is: 'v{{version}}'
$ git push origin v1.2.3  # triggers the action that publishes my package.

Depois do envio, revise os logs do workflow em https://github.com/<organization>/<repository>/actions.

Se a Action não tiver sido acionada, verifique se o padrão configurado em .github/workflows/publish.yml corresponde à git tag enviada. Se a Action falhou, os logs podem conter pistas sobre o motivo da falha.

Depois de publicado, você pode ver o evento de publicação no audit-log do pub.dev. A entrada do audit-log deve conter um link para a execução do GitHub Action que publicou a versão do pacote.

Se você não gosta de usar a CLI do git para criar tags, pode criar releases no GitHub em https://github.com/<organization>/<repository>/releases/new. Para saber mais, veja gerenciando releases em um repositório no GitHub.

Configurar a publicação automatizada a partir do GitHub Actions permite que qualquer pessoa que consiga enviar uma tag para o seu repositório acione a publicação no pub.dev. Você pode restringir quem pode enviar tags para o seu repositório usando regras de proteção de tags no GitHub.

Ao limitar quem pode criar tags que correspondam ao seu tag pattern, você limita quem pode publicar o pacote.

No momento, as regras de proteção de tags são pouco flexíveis. Você pode querer restringir quem pode acionar a publicação usando ambientes de deploy do GitHub, como descrito na próxima seção.

Ao configurar a publicação automatizada a partir do GitHub Actions no pub.dev, você pode exigir um ambiente do GitHub Actions. Para exigir um ambiente do GitHub Actions para a publicação, você precisa:

1. Acessar a aba Admin (pub.dev/packages/<package>/admin).
2. Encontrar a seção Automated publishing.
3. Clicar em Require GitHub Actions environment.
4. Especificar um nome de Environment (pub.dev costuma ser um bom nome).

Quando um ambiente é exigido no pub.dev, o GitHub Actions não consegue publicar a menos que tenha environment: pub.dev. Por isso, você precisa:

1. Criar um ambiente com o mesmo nome no GitHub (normalmente pub.dev).
2. Alterar o seu arquivo de workflow .github/workflows/publish.yml para especificar environment: pub.dev, conforme o exemplo a seguir:

# .github/workflows/publish.yml
name: Publish to pub.dev
​
on:
  push:
    tags:
    - 'v[0-9]+.[0-9]+.[0-9]+' # for tags like: 'v1.2.3'
​
jobs:
  publish:
    permissions:
      id-token: write # Required for authentication using OIDC.
    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
    with:
      # Specify the GitHub Action deployment environment.
      environment: pub.dev
      # working-directory: path/to/package/within/repository

O ambiente é refletido no token OIDC temporário assinado pelo GitHub usado para a autenticação no pub.dev. Assim, um usuário com permissão para enviar código para o seu repositório não consegue contornar as regras de proteção de ambientes modificando o arquivo de workflow.

Nas configurações do repositório no GitHub, você pode usar as regras de proteção de ambientes para configurar revisores obrigatórios. Se você configurar essa opção, o GitHub impede que as ações do ambiente sejam executadas até que um dos revisores obrigatórios aprove a execução.

Você pode configurar a publicação automatizada a partir do Google Cloud Build. Isso envolve:

• Registrar um projeto do Google Cloud (ou usar um projeto existente),
• Criar uma service account para publicar no pub.dev,
• Habilitar a publicação automatizada na aba admin do pacote no pub.dev, especificando o e-mail da service account criada para a publicação.
• Conceder à service account padrão do Cloud Build a permissão de personificar a service account criada para a publicação.
• Criar um arquivo cloudbuild.yaml que obtém um id_token OIDC temporário e o usa para publicar no pub.dev.
• Configurar um gatilho (trigger) do Cloud Build, para executar os passos do cloudbuild.yaml no seu projeto no Google Cloud Build.

As seções a seguir descrevem como concluir essas etapas.

Para publicar no pub.dev, você vai criar uma service account que recebe permissão para publicar o seu pacote no pub.dev. Depois, você vai conceder ao Cloud Build a permissão para personificar essa service account.

1. Crie um projeto de nuvem, caso você não tenha um projeto existente.

2. Crie uma service account da seguinte forma:

   $ gcloud iam service-accounts create pub-dev \
     --description='Service account to be impersonated when publishing to pub.dev' \
     --display-name='pub-dev'
   

   content_copy

   Isso cria uma service account chamada pub-dev@$PROJECT_ID.iam.gserviceaccount.com.

3. Conceda à service account a permissão para publicar o seu pacote.

   Para concluir esta etapa, você precisa ter a permissão de uploader no pacote ou ser um admin do publisher que é dono do pacote.

   a. Acesse a aba Admin (pub.dev/packages/<package>/admin). a. Clique em Enable publishing with Google Cloud Service account. a. Digite o e-mail da service account no campo Service account email. Você criou esta conta na etapa anterior: pub-dev@$PROJECT_ID.iam.gserviceaccount.com

Concluído este procedimento, qualquer pessoa que consiga personificar a service account pode publicar novas versões do pacote. Certifique-se de revisar quem tem permissão para personificar a service account e de alterar as permissões no projeto de nuvem conforme necessário.

Para publicar a partir do Cloud Build, você precisa dar à service account padrão do Cloud Build a permissão para personificar a service account criada para a publicação na seção anterior.

1. Habilite a API IAM Service Account Credentials no projeto de nuvem. Tentativas de personificar uma service account falharão sem essa API.

   # Enable IAM Service Account Credentials API
   $ gcloud services enable iamcredentials.googleapis.com
   

   content_copy

2. Encontre o número do projeto.

   # The PROJECT_NUMBER can be obtained as follows:
   $ gcloud projects describe $PROJECT_ID --format='value(projectNumber)'
   

   content_copy

3. Conceda a permissão para personificar a service account de publicação.

   # Grant default cloud
   $ gcloud iam service-accounts add-iam-policy-binding \
     pub-dev@$PROJECT_ID.iam.gserviceaccount.com \
     --member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
     --role=roles/iam.serviceAccountTokenCreator
   

   content_copy

Para publicar a partir do Cloud Build, você precisa especificar os passos para que o Cloud Build:

• Personifique a service account para obter um token OIDC temporário.
• Forneça o token OIDC temporário ao dart pub para uso na publicação.
• Execute dart pub publish para publicar o pacote.

Os passos para o Google Cloud Build são fornecidos em um arquivo cloudbuild.yaml; veja o schema do arquivo de configuração de build para a documentação completa do formato.

Para publicar no pub.dev a partir do Google Cloud Build, um arquivo cloudbuild.yaml como o seguinte é suficiente:

# cloudbuild.yaml
steps:
- id: Create temporary token
  name: gcr.io/cloud-builders/gcloud
  volumes:
  - name: temporary-secrets
    path: /secrets
  script: |
    gcloud auth print-identity-token \
      --impersonate-service-account=pub-dev@$PROJECT_ID.iam.gserviceaccount.com \
      --audiences=https://pub.dev \
      --include-email > /secrets/temporary-pub-token.txt
  env:
  - PROJECT_ID=$PROJECT_ID
- id: Publish to pub.dev
  name: dart
  volumes:
  - name: temporary-secrets
    path: /secrets
  script: |
    cat /secrets/temporary-pub-token.txt | dart pub token add https://pub.dev
    dart pub publish --force

O gcloud auth print-identity-token cria um id_token OIDC personificando a service account especificada. Esse id_token é assinado pelo Google, com uma assinatura que expira em até 1 hora. O parâmetro audiences informa ao pub.dev que ele é o destinatário pretendido do token. A opção --include-email é necessária para que o pub.dev reconheça a service account.

Depois que o id_token é criado, ele é gravado em um arquivo que fica em um volume; esse mecanismo é usado para passar dados entre os passos. Não armazene o token em /workspace, pois é nesse diretório que o repositório do qual você quer publicar é feito checkout. Não usar /workspace para guardar o token reduz o risco de você incluí-lo acidentalmente no pacote ao publicar.

Com as service accounts configuradas e um arquivo cloudbuild.yaml no repositório, você pode criar um Cloud Build Trigger pelo painel em console.cloud.google.com. Para criar um gatilho de build, você precisa conectar a um repositório de código e especificar quais eventos devem acionar um build. Você pode usar o GitHub, o Cloud Source Repository ou uma das outras opções. Para aprender a configurar um Cloud Build Trigger, veja criando e gerenciando gatilhos de build.

Para usar o cloudbuild.yaml do passo anterior, configure o tipo do Cloud Build Trigger como "Cloud Build Configuration", localizado no repositório, no arquivo /cloudbuild.yaml. Não especifique uma service account para o build que será acionado. Em vez disso, use a service account padrão do Cloud Build.

Ao configurar o gatilho do Cloud Build, considere quem pode acioná-lo. Porque acionar um build pode publicar uma nova versão do seu pacote. Considere permitir apenas builds manuais ou usar as aprovações do Cloud Build para controlar os builds, conforme descrito na próxima seção.

Ao configurar um gatilho do Cloud Build, você pode selecionar require approval before build executes. Se um gatilho do Cloud Build exigir aprovação, ele não será executado quando acionado. Em vez disso, ele aguardará a aprovação. Isso pode ser usado para limitar quem pode publicar novas versões do seu pacote.

Somente um usuário com o papel Cloud Build Approver pode conceder a aprovação. Ao aprovar, o aprovador pode especificar uma URL e um comentário.

Você também pode configurar notificações para aprovações pendentes. Para saber mais, veja controlando o build com aprovação.

Para permitir a publicação automatizada fora do GitHub Actions, você pode se autenticar usando service accounts de forma semelhante ao Cloud Build.

Isso normalmente envolve:

• Criar uma service account para publicação,
• Personificar a service account de publicação de uma de duas formas:
  • Workload Identity Federation
  • Chaves exportadas de service account

A seção do Cloud Build descreveu como criar uma service account para publicação. Isso deve fornecer uma service account, como pub-dev@$PROJECT_ID.iam.gserviceaccount.com.

Quando você executa em um serviço de nuvem que suporta OIDC ou SAML, pode personificar uma service account do GCP usando Workload Identity Federation. Isso permite que você aproveite os serviços de identidade do seu provedor de nuvem.

Por exemplo, se você fizer o deploy na EC2, pode configurar a workload identity federation com a AWS, permitindo que tokens temporários da AWS obtidos pelo serviço de metadados da EC2 personifiquem uma service account. Para aprender a configurar esses fluxos, veja workload identity federation.

Quando você executa em um sistema próprio sem serviços de identidade, pode exportar chaves de service account. As chaves exportadas permitem que você se autentique como essa service account. Para saber mais, veja como criar e gerenciar chaves de service account.

1. Crie chaves exportadas para uma service account existente.

   $ gcloud iam service-accounts keys create key-file.json \
     --iam-account=pub-dev@$PROJECT_ID.iam.gserviceaccount.com
   

   content_copy

2. Salve o arquivo key-file.json para uso posterior.

Para publicar um pacote usando chaves exportadas de service account:

1. Configure o gcloud para se autenticar usando o key-file.json (criado na etapa anterior)

   $ gcloud auth activate-service-account --key-file=key-file.json
   

   content_copy

2. Crie um token temporário para o pub.dev e passe-o para dart pub token add https://pub.dev. Para personificar a service account, inclua a opção --include-email.

   $ gcloud auth print-identity-token \
     --audiences=https://pub.dev \
     | dart pub token add https://pub.dev
   

   content_copy

3. Publique usando o token temporário. Adicione a opção --force para pular a confirmação yes/no.

   $ dart pub publish --force
   

   content_copy