semantic-release-pub

semantic-release plugin to publish a Dart or Flutter package.

Step	Description
verifyConditions	Verify the presence of the GOOGLE_SERVICE_ACCOUNT_KEY environment variable, the ability to exchange an identity from the service account, and the dart or flutter executable.
prepare	Update the pubspec.yaml version.
publish	Publish the Dart or Flutter package to the registry.

Installation

Install via npm:

npm install --save-dev semantic-release-pub

Or via yarn:

yarn add --dev semantic-release-pub

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer", 
    "@semantic-release/release-notes-generator", 
    "semantic-release-pub"
  ]
}

Configuration

pub.dev authentication

You can publish to pub.dev using either Google Service Account or GitHub Actions OIDC.

Note that when using GitHub Actions OIDC, pub.dev only allows authentication when the workflow is triggered by a tag event. See here for more details.

Google Service Account

The following instructions are referenced from the documentation of Dart. Below are the key steps to allow authentication to pub.dev.

1. Create a Google Cloud project, if you don’t have an existing project.

2. Create a service account either through the Google Cloud Console under IAM and admin > Service accounts or as follow:

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

3. Grant the service account permission to publish your package.

   To complete this step, you must have uploader permission on the package or be an admin of the publisher that owns the package.

   1. Navigate to the package Admin tab (pub.dev/packages//admin).
   2. Click Enable publishing with Google Cloud Service account.
   3. Type the email of the service account into the Service account email field.

      You created this account in the previous step: pub-dev@$PROJECT_ID.iam.gserviceaccount.com

4. Create exported service account keys for the service account either through the Google Cloud Console under Service account actions > Manage keys > Add key > Create new key > JSON > Create or as follow:

   gcloud iam service-accounts keys create key-file.json \
       PROJECT_ID.iam.gserviceaccount.com

5. Copy the content of the JSON key file and set it as an environment variable under GOOGLE_SERVICE_ACCOUNT_KEY.

GitHub Actions OIDC

The following instructions are referenced from the documentation of Dart. Below are the key steps to allow authentication to pub.dev via GitHub Actions OIDC.

1. Enable automated publishing.

   To complete this step, you must have uploader permission on the package or be an admin of the publisher that owns the package.

   1. Navigate to the package Admin tab (pub.dev/packages//admin).
   2. Click Enable publishing from GitHub Actions.
   3. Then fill in the necessary information.

2. In your workflow, add the id-token permission.

   jobs:
     publish:
       permissions:
         id-token: write

Environment variables

Variable	Description
GOOGLE_SERVICE_ACCOUNT_KEY	The google service account key created from the above steps. Not required if using GitHub Actions OIDC.

Options

Option	Description	Default
cli	The dart or flutter CLI to use to publish the package to the registry.	dart
publishPub	Whether to publish the package to the registry. If set to false, the pubspec.yaml version will still be updated.	true
updateBuildNumber	Whether to write build number for every newly bumped version in pubspec.yaml. Note that the build number will always be increased by one. Learn more on Flutter docs.	false
useGithubOidc	Whether to use GitHub OIDC. If set to true, authentication to pub.dev will be done using GitHub OIDC. Otherwise, the GOOGLE_SERVICE_ACCOUNT_KEY will be used.	false

Examples

Publishing a Flutter package

{
  "plugins": [
    "@semantic-release/commit-analyzer", 
    "@semantic-release/release-notes-generator", 
    [
      "semantic-release-pub",
      {
        "cli": "flutter"
      }
    ]
  ]
}

See here for a sample pull request utilising this plugin and semantic-release to publish a Flutter package.

Using GitHub Actions OIDC

{
  "plugins": [
    "@semantic-release/commit-analyzer", 
    "@semantic-release/release-notes-generator", 
    [
      "semantic-release-pub",
      {
        "useGithubOidc": true
      }
    ]
  ]
}