Skip to content

chore: fix CI/CD pipeline section and add skip functionality docs #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cidrblock merged 3 commits into from
Jun 12, 2026
+49 −27
Merged

chore: fix CI/CD pipeline section and add skip functionality docs #564

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7db217a
docs(fix): Usage in a CI/CD pipeline.
dbrennand Jun 12, 2026
3a6a548
docs: add skip functionality section
dbrennand Jun 12, 2026
64e7957
docs(fix): indentation for `note`
dbrennand Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 49 additions & 27 deletions docs/user_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,44 +137,66 @@ tox -e unit-py3.13-2.19 --ansible -- --junit-xml=tests/output/junit/unit.xml

## Usage in a CI/CD pipeline

The repo contains a GitHub workflow that can be used in a GitHub actions CI/CD pipeline. The workflow will run all tests across all available environments unless limited by the `skip` option in `pyproject.toml` (or `tox-ansible.ini`).
A GitHub Actions matrix is dynamically created by `tox-ansible` using the `--gh-matrix` and `--ansible` flags. The list of environments is converted to a list of entries in json format which is stored under the `envlist` key in the file specified by the `GITHUB_OUTPUT` environment variable.

Each environment will be run in a separate job. The workflow will run all jobs in parallel.
Below shows relevant snippets from a GitHub Action workflow which:

The GitHub matrix is dynamically created by `tox-ansible` using the `--gh-matrix` and `--ansible` flags. The list of environments is converted to a list of entries in json format and added to the file specified by the "GITHUB_OUTPUT" environment variable. The workflow will read this file and use it to create the matrix.
1. Uses the `--gh-matrix` flag to generate a list of environments.
2. Creates individual jobs for each environment using a [matrix strategy](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations).

A sample use of the GitHub workflow might look like this:
!!! note

This is not a production ready GitHub Action workflow. It is missing key steps for readability purposes. You will need to set up Python and install `tox-ansible` in your GitHub Action workflow.

```yaml
name: Test collection
# .github/workflows/tox-ansible.yml
name: Tox Ansible
# ...
jobs:
generate-matrix:
# ...
outputs:
envlist: ${{ steps.matrix.outputs.envlist }}
steps:
# ...
- name: Generate matrix
id: matrix
run: |
tox --ansible --conf tox-ansible.ini --gh-matrix

tox-ansible:
needs: generate-matrix
# ...
strategy:
fail-fast: false
matrix:
env: ${{ fromJSON(needs.generate-matrix.outputs.envlist) }}
steps:
# ...
- name: Run tox environment ${{ matrix.env.name }}
run: |
tox --ansible --conf tox-ansible.ini -e ${{ matrix.env.name }}
```

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
## Skip functionality

on:
pull_request:
branches: [main]
workflow_dispatch:
Circumstances may require certain tests to be skipped. `tox-ansible` supports skipping tests via `skip` in `[tool.tox-ansible]` (pyproject.toml) or `[ansible]` (tox-ansible.ini).

jobs:
tox-ansible:
uses: ansible/tox-ansible/.github/workflows/run.yml@main
Example for `pyproject.toml`:

```toml
# pyproject.toml
[tool.tox-ansible]
skip = sanity-py3.13
```

Sample `json`
Example for `tox-ansible.ini`:

```json
[
// ...
{
"description": "Integration tests using ansible-core devel and python 3.11",
"factors": ["integration", "py3.11", "devel"],
"name": "integration-py3.12-devel",
"python": "3.11"
}
// ...
]
```ini
# tox-ansible.ini
[ansible]
skip =
sanity-py3.13
```

## Testing molecule scenarios
Expand Down