---
myst:
  html_meta:
    "description": "Configure GitHub Actions workflows generated by plone.meta"
    "property=og:description": "Configure GitHub Actions workflows generated by plone.meta"
    "property=og:title": "Configure GitHub Actions"
    "keywords": "plone.meta, GitHub Actions, CI/CD, test matrix"
---

# Configure GitHub Actions

<!-- diataxis: how-to -->

`plone.meta` generates a {file}`.github/workflows/meta.yml` file that references reusable workflows from the plone/meta repository.

## Select CI jobs

Choose which jobs to include in {file}`meta.yml`:

```toml
[github]
jobs = [
    "qa",
    "coverage",
    "dependencies",
    "release_ready",
    "circular",
]
```

:::{note}
The `"test"` job is no longer included in the default jobs list. Testing is now handled by the separate {file}`test-matrix.yml` workflow, which is generated automatically when `use_test_matrix` is enabled (the default).
:::

Available jobs:

qa
: Runs `tox -e lint` for code quality checks.

test
: Runs `tox -e test` with a single Python version. Not included by default;
  use the test matrix workflow instead (see below).

coverage
: Runs `tox -e coverage` and outputs a coverage report.

dependencies
: Validates dependencies with `z3c.dependencychecker`.

release_ready
: Checks if the package is ready for release.

circular
: Detects circular dependencies.

## Pin the workflow version

By default, workflows reference the `2.x` branch of plone/meta.
Pin to a specific tag:

```toml
[github]
ref = "v3"
```

## Set environment variables

```toml
[github]
env = """
  debug: 1
  image-name: 'org/image'
  image-tag: 'latest'
"""
```

## Install OS-level dependencies

Specify Ubuntu package names:

```toml
[github]
os_dependencies = "git libxml2 libxslt1-dev"
```

## Add lines after OS dependency installation

Use `extra_lines_after_os_dependencies` to insert additional setup steps that run after the OS-level dependencies are installed but before tests:

```toml
[github]
extra_lines_after_os_dependencies = """
  run: |
    curl -sSL https://example.com/setup.sh | bash
"""
```

## Test matrix workflow

When `use_test_matrix` is enabled (the default), plone.meta generates a separate {file}`test-matrix.yml` workflow that tests all combinations of Plone versions and Python versions.
This replaces the old single-version `test` job.

The matrix is configured in the `[tox]` section:

```toml
[tox]
use_test_matrix = true
test_matrix = {"6.2" = ["3.14", "3.13", "3.12", "3.11", "3.10"], "6.1" = ["3.13", "3.12", "3.11", "3.10"]}
```

Using `"*"` as shorthand includes all currently supported Python versions for a given Plone version:

```toml
[tox]
test_matrix = {"6.2" = ["*"]}
```

## Add extra workflow jobs

```toml
[github]
extra_lines = """
  another:
    uses: org/repo/.github/workflows/file.yml@main
"""
```
