firehose

What's this?

This is a tool to automate publishing of pub packages from GitHub actions.

Conventions and setup

When run from a PR, this tool will validate the package pubspecs and changelogs and indicate whether the criteria for publishing has been met. Generally, each PR should add a new entry to the changelog, rev the pubspec version, and the changelog version and pubspec version should agree.

When run in response to a git tag event (a tag with a pattern like v1.2.3 or name_v1.2.3 for monorepos), this tool will publish the indicated package.

Pre-release versions

Pre-release versions (aka, '1.2.3-dev') are handled specially; this tool will validate the package but will not auto-publish it. This can be used to accumulate several changes and later publish them as a group.

Disabling auto-publishing

In order to disable package validation and auto-publishing, add the publish_to: none key to your pubspec.

PR branch actions

For PRs, this tool:

• determines repo packages
• validates that the changelog version equals the pubspec version
• performs a dart pub publish --dry-run

Git tag actions

In response to a git tag event, this tool:

• validates the tag is well-formed
• determines the indicated package
• attempts to publish that package (dart pub publish --force)

Mono-repos

This tool can work with either single package repos or with mono-repos (repos containing several packages). It will scan for and detect packages in a mono repo; to omit packages from validation and auto-publishing, add a publish_to: none key to its pubspec.

For single package repos, the tag pattern should be v1.2.3. For mono-repos, the tag pattern must be prefixed with the package name, e.g. foo-v1.2.3.

Integrating this tool into a repo

• copy the yaml below into a .github/workflows/publish.yaml file in your repo
• update the target branch below if necessary (currently, main)
• if publishing from a mono-repo, adjust the ‘tags’ line below to tags: [ '[0-9A-z]+-v[0-9]+.[0-9]+.[0-9]+' ]
• from the pub.dev admin page of your package, enable publishing from GitHub Actions

# A CI configuration to auto-publish pub packages.

name: Publish

on:
  pull_request:
    branches: [ main ]
    types: [opened, synchronize, reopened, labeled, unlabeled]
  push:
    tags: [ 'v[0-9]+.[0-9]+.[0-9]+' ]

jobs:
  publish:
    uses: dart-lang/ecosystem/.github/workflows/publish.yaml@main
    permissions:
      id-token: write
      pull-requests: write

Enabling comments on forks

• add the following to your publish.yaml:

    with:
       write-comments: false

• copy the yaml below into a .github/workflows/post_summaries.yaml file in your repo

# A CI configuration to write comments on PRs.

name: Comment on the pull request

on:
  workflow_run:
    workflows: 
      - Publish
    types:
      - completed

jobs:
  upload:
    uses: dart-lang/ecosystem/.github/workflows/post_summaries.yaml@main
    permissions:
      pull-requests: write

Publishing from a specific version of the SDK

Callers may optionally specify the version of the SDK to use when publishing a package. This can be useful if your package has a very recent minimum SDK constraint. This is done via the sdk input parameter. Note that this parameter is not required; it defaults to stable - using the most recent stable release of the Dart SDK. To pass this value:

jobs:
  publish:
    uses: dart-lang/ecosystem/.github/workflows/publish.yml@main
    with:
      sdk: beta

Publishing from a protected Github environment

Callers may optionally specify the name of a github environment for the publish job to use. This is useful if you want to require approvals for the publish job to run. To pass this value:

jobs:
  publish:
    uses: dart-lang/ecosystem/.github/workflows/publish.yml@main
    with:
      environment: pub.dev # Can be any name, this is the convention though.

Make sure to also require this environment to be present in your package admin settings. See the pub.dev documentation on this.

Workflow docs

The description of the common workflow for repos using this tool can be found at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

health

What's this?

This is a Github workflow to check PR health.

Conventions and setup

When run from a PR, this tool will check a configurable subset of the following

• The package versioning is correct and consistent, see firehose description above.
• A changelog entry has been added.
• All .dart files have a license header.
• How the test coverage is affected by the PR.
• The package versioning takes into account any breaking changes in the PR.
• The PR contains DO_NOT_SUBMIT strings in the files or the description.
• Any symbols are visible in the public API, but not exported.

This tool can work with either single package repos or with mono-repos (repos containing several packages).

Integrating this tool into a repo

1. Copy the yaml below into a .github/workflows/health.yaml file in your repo
2. Update the target branch below if necessary (currently, main)

name: Health
on:
  pull_request:
    branches: [ main ]
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  health:
    uses: dart-lang/ecosystem/.github/workflows/health.yaml@main
#   with:
#     sdk: beta
#     checks: "version,changelog,license,coverage,breaking,do-not-submit,leaking"
#     fail_on: "version,changelog,do-not-submit"
#     warn_on: "license,coverage,breaking,leaking"
#     coverage_web: false
#     upload_coverage: false
#     use-flutter: true
#     ignore_license: "**.g.dart"
#     ignore_coverage: "**.mock.dart,**.g.dart"
#     ignore_breaking: "pkgs/helper_package/**"
#     ignore_packages: "pkgs/helper_package2"
#     checkout_submodules: false
#     experiments: "native-assets"
    permissions:
      pull-requests: write

3. Copy the yaml below into a .github/workflows/post_summaries.yaml file in your repo. This is a necessary workaround to get PR Health comments on PRs from forks.

name: Comment on the pull request

on:
  # Trigger this workflow after the Health workflow completes. This workflow will have permissions to
  # do things like create comments on the PR, even if the original workflow couldn't.
  workflow_run:
    workflows: 
      - Health
      # - Publish
    types:
      - completed

jobs:
  upload:
    uses: dart-lang/ecosystem/.github/workflows/post_summaries.yaml@main
    permissions:
      pull-requests: write

Checks

Options

Workflow docs

The description of the common workflow for repos using this tool can be found at https://github.com/dart-lang/ecosystem/wiki/Pull-Request-Health.

Running locally

To run the health workflow locally, simply run

dart pub global activate --source git https://github.com/dart-lang/ecosystem --git-path pkgs/firehose/
dart pub global run firehose:health

or configure it further, for example

dart pub global run firehose:health --check unused-dependencies,license --comment test.md