Skip to content

GitHub Actions#

This page describes how to write GitHub Actions workflows in Autoware repositories. pre-commit formats and checks the workflow files with Prettier and yamllint, like all other YAML files.

References#

Do not edit synced workflows#

Many workflows are the same in all Autoware repositories, for example pre-commit, semantic-pull-request, spell-check-differential, and sync-files. The sync-files workflow copies them from sync-file-templates. The list of the synced files of a repository is in its .github/sync-files.yaml. A synced file starts with this comment:

# This file is automatically synced from:
# https://github.com/autowarefoundation/sync-file-templates
# To make changes, update the source repository and follow the guidelines in its README.

Do not change a synced file in your repository, because the next sync overwrites it. Send the change to sync-file-templates.

Name the files#

  • Put workflows in .github/workflows/ and use the .yaml extension.
  • Give the workflow the same name as the file, for example name: pre-commit in pre-commit.yaml. Then the name of a check on a pull request tells you which file to open.
  • Use a name that says what the workflow does. Add -differential to a workflow that checks only the changed packages or files, as in build-and-test-differential and spell-check-differential.

Reuse actions and workflows#

Do not copy the same steps into many workflows. Use the composite actions and the reusable workflows of autoware-github-actions, for example colcon-build, colcon-test, get-modified-packages, pre-commit, and spell-check. Refer to them with the v1 tag:

- name: Get modified packages
  id: get-modified-packages
  uses: autowarefoundation/autoware-github-actions/get-modified-packages@v1

The v1 tag moves to each new release of autoware-github-actions. If a step is useful for more than one repository, add it to autoware-github-actions as a new action.

A step that only one repository uses can be a local composite action in .github/actions/. For example, the autoware repository has .github/actions/free-disk-space.

Write the workflow#

This is the spell-check-differential workflow of the autoware repository 2.0.0. It shows the main conventions:

name: spell-check-differential

on:
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  spell-check-differential:
    runs-on: ubuntu-24.04
    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Run spell-check
        uses: autowarefoundation/autoware-github-actions/spell-check@v1
        with:
          cspell-json-url: https://raw.githubusercontent.com/autowarefoundation/autoware-spell-check-dict/main/.cspell.json
          dict-packages: |
            https://github.com/autowarefoundation/autoware-spell-check-dict
            https://github.com/tier4/cspell-dicts
  • Set a concurrency group with cancel-in-progress: true for pull request workflows. Then a new push cancels the run for the old commit.
  • Use a fixed runner version, such as ubuntu-24.04, not ubuntu-latest. Then a new runner image does not change the build without a pull request.
  • Give each step a name that starts with a verb, for example Check out repository or Run spell-check.
  • Refer to third-party actions by their major version tag, for example actions/checkout@v7. Dependabot updates these tags. The dependabot.yaml of sync-file-templates checks the github-actions ecosystem every month.

Formatting#

yamllint checks the workflow files with the .yamllint.yaml of the repository:

  • Do not start the file with ---.
  • Quote strings only when necessary.
  • Put at least one space between the code and a # comment.
  • The truthy rule does not check keys, so on: is allowed.

Prettier formats the files. It uses two spaces of indentation.

Security#

  • Give the GITHUB_TOKEN only the permissions that the job needs. Use the permissions key.
  • Do not run the code of a pull request in a workflow that has access to secrets. A workflow that runs on pull_request_target or workflow_run has access to the secrets of the repository. Do not check out and build the code of the pull request in such a workflow.
  • Do not put untrusted input, such as the title of a pull request, directly into a run script with ${{ }}. Pass it in an environment variable instead.
  • To push commits or open pull requests from a workflow, Autoware workflows use a GitHub App token, not a personal access token. See the pre-commit workflow for an example that uses the APP_ID and PRIVATE_KEY secrets.