hugrverse-actions

Reusable workflows for projects in the hugrverse.

To call use workflow in your project, add it to a workflow in your project's .github/workflows directory. See the workflow list below for usage instructions, including the workflow triggers.

Some workflows may require additional inputs, such as a [GITHUB_PAT] to access the GitHub API. For these we generate fine-grained access tokens with the @hugrbot bot account, which must be stored in the repository secrets.

The following workflows are available:

• add-to-project: Adds new issues to a GitHub project board when they are created.
• coverage-trend: Checks the coverage trend for the project, and produces a summary that can be posted to slack.
• create-issue: Creates a new issue in the repository, avoiding duplicates.
• drop-cache: Drops the cache for a branch when a pull request is closed.
• pr-title: Checks the title of pull requests to ensure they follow the conventional commits format.
• rs-semver-checks: Runs cargo-semver-checks on a PR against the base branch, and reports back if there are breaking changes.
• slack-notifier: Post comments on slack, with a rate limit to avoid spamming the channel.

add-to-project

Adds new issues to a GitHub project board when they are created.

Usage

name: Add issues to project board
on:
  issues:
    types:
      - opened

jobs:
    add-to-project:
        uses: CQCL/hugrverse-actions/.github/workflows/add-to-project.yml@main
        with:
            project-url: https://github.com/orgs/{your-org}/projects/{project-id}
        secrets:
            GITHUB_PAT: ${{ secrets.ADD_TO_PROJECT_PAT }}

Token Permissions

The fine-grained GITHUB_PAT secret must include the following permissions:

Permission	Access
Projects	Read and write
Pull requests	Read

Note that fine-grained access tokens cannot grant permissions to projects and repositories in different organisations simultaneously. In those cases, you will need an unrestricted classical github token instead.

coverage-trend

Compares the project coverage on Codecov against the last workflow run, and produces a summary of the changes that can be posted to slack.

If the project didn't have new commits that changed the coverage since the last run, the should_notify output will be set to false and the msg output will be empty.

Usage

name: Notify coverage changes
on:
  schedule:
    # 04:00 every Monday
    - cron: '0 4 * * 1'
  workflow_dispatch: {}

jobs:
    coverage-trend:
        uses: CQCL/hugrverse-actions/.github/workflows/coverage-trend.yml@main
        secrets:
            CODECOV_GET_TOKEN: ${{ secrets.CODECOV_GET_TOKEN }}
    # Post the result somewhere.
    notify-slack:
      needs: coverage-trend
      runs-on: ubuntu-latest
      if: needs.coverage-trend.outputs.should_notify == 'true'
      steps:
        - name: Send notification
          uses: slackapi/slack-github-action@v1.27.0
          with:
            channel-id: "SOME CHANNEL ID"
            slack-message: ${{ needs.coverage-trend.outputs.msg }}
          env:
            SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Outputs

• should_notify: Whether there has been a change in coverage since the last run, which we can post about.
• msg: A message summarising the coverage changes. This is intended to be posted to slack.

Token Permissions

CODECOV_GET_TOKEN is a token generated by Codecov to access the repository's coverage data.

drop-cache

Drops the cache for a branch when a pull request is closed. This helps to avoid cache pollution by freeing up some of github's limited cache space.

Usage

name: cleanup caches by a branch
on:
  pull_request:
    types:
      - closed

jobs:
    drop-cache:
        uses: CQCL/hugrverse-actions/.github/workflows/drop-cache.yml@main

create-issue

Creates a new issue in the repository, avoiding duplicates. The workflow takes a "unique-label" input, which is used to check if an issue with that label already exists.

The specified labels must already exist in the repository, otherwise the workflow will fail.

Usage

name: Create an issue
on:
  schedule:
    # 12:00 every Monday
    - cron: '0 12 * * 1'

jobs:
    create-issue:
        uses: CQCL/hugrverse-actions/.github/workflows/create-issue.yml@main
        secrets:
            GITHUB_PAT: ${{ secrets.GITHUB_PAT }}
        with:
            title: "Hello 🌎!"
            body: "This is a new issue."
            unique-label: "hello-world"
            # Optionally, set the target repository.
            repository: "CQCL/hugrverse-actions"
            # Optional list of labels to add to the issue.
            other-labels: "greetings,scheduled"

Token Permissions

The fine-grained GITHUB_PAT secret must include the following permissions:

Permission	Access
Issues	Read and write

pr-title

Checks the title of pull requests to ensure they follow the conventional commits format. If the title does not follow the conventional commits, a comment is posted on the PR to help the user fix it.

Usage

name: Check Conventional Commits format
on:
  pull_request_target:
    branches:
      - main
    types:
      - opened
      - edited
      - synchronize
      - labeled
      - unlabeled
  merge_group:
    types: [checks_requested]

jobs:
    check-title:
        uses: CQCL/hugrverse-actions/.github/workflows/pr-title.yml@main
        secrets:
            GITHUB_PAT: ${{ secrets.GITHUB_PAT }}

Token Permissions

The fine-grained GITHUB_PAT secret must include the following permissions:

Permission	Access
Pull requests	Read and write

rs-semver-checks

Runs cargo-semver-checks on a PR against the base branch, and reports back if there are breaking changes. Suggests adding a breaking change flag to the PR title if necessary.

Usage

name: Rust Semver Checks
on:
  pull_request_target:
    branches:
      - main

jobs:
    rs-semver-checks:
        uses: CQCL/hugrverse-actions/.github/workflows/rs-semver-checks.yml@main
        secrets:
            GITHUB_PAT: ${{ secrets.GITHUB_PAT }}

The workflow compares against the base branch of the PR by default. Use the baseline-rev input to specify a different base commit.

Token Permissions

The fine-grained GITHUB_PAT secret must include the following permissions:

Permission	Access
Pull requests	Read and write

Note that repository secrets are not available to forked repositories on pull_request events. To run this workflow on pull requests from forks, ensure the action is triggered by a pull_request_target event instead.

slack-notifier

Post comments on slack using slackapi/slack-github-action, adding a rate limit to avoid spamming the channel.

Usage

name: Send a slack message
on:
  pull_request:
    branches:
      - main

jobs:
    message-slack:
        uses: CQCL/hugrverse-actions/.github/workflows/slack-notifier.yml@main
        with:
            channel-id: "SOME CHANNEL ID"
            slack-message: "Hello 🌎!"
            # A minimum time in minutes to wait before sending another message.
            timeout-minutes: 60
            # A repository variable used to store the last message timestamp.
            timeout-variable: "HELLO_MESSAGE_TIMESTAMP"
        secrets:
            GITHUB_PAT: ${{ secrets.GITHUB_PAT }}
            SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Inputs

• channel-id: The ID of the channel to post the message to. (required)
• slack-message: The message to post. (required)
• timeout-variable: A repository variable used to store the last message timestamp. (required)
• timeout-minutes: A minimum time in minutes to wait before sending another message. Defaults to 24 hours.

Outputs

• sent: A boolean indicating if the message was sent.

Token Permissions

SLACK_BOT_TOKEN is a token generated by Slack with chat:write access to the channel. See the slackapi/slack-github-action documentation for more information. If you are using a slack app, make sure to add it to the channel. See formatting options in the Slack API documentation.

The fine-grained GITHUB_PAT secret must include the following permissions:

Permission	Access
Variables (repository)	Read and write