pytest-mergify
Pytest plugin for Mergify Test Insights.
More information at https://mergify.com
Features
- Test tracing — Sends OpenTelemetry traces for every test to Mergify's API
- Flaky test detection — Intelligently reruns tests to detect flakiness with budget constraints
- Test quarantine — Quarantines failing tests so they don't block CI
- Test selection — Runs only the previously-failing tests when Mergify's merge queue reruns a job
Installation
Install the package alongside pytest (>= 6.0.0):
pip install pytest-mergify
The plugin is auto-discovered by pytest — no manual registration required.
Configuration
Set the MERGIFY_TOKEN environment variable with your Mergify API token.
The plugin activates automatically when running in CI (detected via the CI environment variable). To enable outside CI, set PYTEST_MERGIFY_ENABLE=true.
Environment Variables
| Variable | Description | Default |
|---|---|---|
MERGIFY_TOKEN |
Mergify API authentication token | (required) |
MERGIFY_API_URL |
Mergify API endpoint | https://api.mergify.com |
PYTEST_MERGIFY_ENABLE |
Force-enable outside CI | false |
PYTEST_MERGIFY_DEBUG |
Print spans to console | false |
MERGIFY_TRACEPARENT |
W3C distributed trace context | — |
MERGIFY_TEST_JOB_NAME |
Mergify test job name | — |
MERGIFY_TEST_SELECTION_ENABLE |
Opt this job into test selection (see below) | false |
For detailed documentation, see the official guide.
Test selection
When Mergify's merge queue reruns a job — a retry, or a step of a batch bisection — only the tests that failed on the previous attempt are informative. The plugin asks Mergify whether the current run is such a rerun and, if so, runs only those tests; the rest are reported as deselected.
Two other answers exist. Mergify may say the previous attempt of this job
already ran every one of these tests and they all passed: the run then executes
no test and exits green, and still reports itself so the attempt is visible.
Or Mergify may stop the run outright. That happens when several runs of this
job report under the same name and run the same tests: Mergify cannot tell
which one the current run repeats, and it will not guess which tests to skip.
The run then fails, showing Mergify's explanation of what it saw — usually
asking you to give each of those runs its own MERGIFY_TEST_JOB_NAME.
This is off until you turn it on, per job. Installing the plugin is not
enough: a feature that decides not to run tests starts only where you wrote
that it should. Set MERGIFY_TEST_SELECTION_ENABLE=true on the job you want
reduced:
- name: Run tests
run: pytest
env:
MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
MERGIFY_TEST_SELECTION_ENABLE: "true"
A job that does not set it never queries the endpoint and always runs the full
suite; everything else the plugin does — test tracing, flaky detection,
quarantine — is unaffected either way. Anything that is not a recognised yes
(unset, empty, false, or a value the plugin cannot parse) means no.
Past that there is nothing to configure: the plugin uses the token and job identity it already has, and Mergify decides. Every remaining situation — a normal run, a rerun Mergify has no previous results for, an unreachable API, an answer from a newer Mergify this plugin does not understand — runs the full suite, so the feature never costs coverage. It is also enabled per organization on Mergify's side, so a job that opts in stays inactive until your organization is opted in too.
An opted-in job also tells Mergify what it concluded when its session ends — which tests failed, how many ran — in one small request sent before the test results are uploaded. That is what the next rerun of the job is answered from, seconds after this one finished, without waiting for the results to be processed. If that request fails, the run's own result is untouched: the terminal says so, and the next rerun simply runs the full suite.
Development
Prerequisites
- Python >= 3.8
- uv
Setup
uv sync
Running Tests
uv run poe test
Linting
uv run poe linters
License
Apache-2.0
Metadata
Release files for pytest-mergify 2026.10.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pytest_mergify-2026.10.3-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_x86_64.whl | CPython 3.8 | abi3 | Linux musl 1.2+ x86-64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_aarch64.whl | CPython 3.8 | abi3 | Linux musl 1.2+ ARM64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details |
| pytest_mergify-2026.10.3-cp38-abi3-macosx_10_12_x86_64.whl | CPython 3.8 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 21.7 MB
Release files / pytest_mergify-2026.10.3-cp38-abi3-win_amd64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
7b2937107f81004bcd4fad7bd1e8b5b17bfb703762d5f0078f588411a925cb9d
|
|
BLAKE2b-256 checksum How to use checksums |
704fc3291311fb804196a323451b0b5b2e3a8a882d8b44f7bc4610d114d14189
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_x86_64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.8 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
fb65483c7c3039465b8e02d2cdc7196f8a10e41c3258896cf210326e0e3bc19b
|
|
BLAKE2b-256 checksum How to use checksums |
68495a0a5a6e48f2ce556130a6b05fd5a9905bb49bf5dfb0dc589b3093a1393a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_aarch64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.8 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
8fda28733fb10603ec0f9feff51f09f7379694401a73381596344eec97474568
|
|
BLAKE2b-256 checksum How to use checksums |
b9c694182d730b991e9743e8ec5861eeb832053439c1d1b97984430ef8a44ac7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
a031c797bfdef5ff0c56ef936217fcc17c3f929d13349edf680daa3ab3255c1d
|
|
BLAKE2b-256 checksum How to use checksums |
41bc2188c93b8a467c4200ffdd3b186bcef0ecf2449780ecbe1dd3335d02e10a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
957586af0e33e79f9ca1c78734a6db7c08d2b46feb9034ba9d14580ba9f6dbdf
|
|
BLAKE2b-256 checksum How to use checksums |
f7362a882cf14b85c917ac32665dc6dcafc1b79128c4694a6b41001d9d310c34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.8 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
6197efa6873e59aa6b404f37d0d06b9096e47b12c953bdf68dcb7e3895fe2850
|
|
BLAKE2b-256 checksum How to use checksums |
a9850e6b05e55a0e77bbbe24476b6c662a2ff01a53530f2853f19c4bb95b9c4f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / pytest_mergify-2026.10.3-cp38-abi3-macosx_10_12_x86_64.whl
| Download URL | pytest_mergify-2026.10.3-cp38-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.8 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
6f188298f7d1c8bbb948c1fedcea7f25d4d588b9f7cf5293090f92eee98d1481
|
|
BLAKE2b-256 checksum How to use checksums |
3b0f07e17377b6ca1cad8fa3b111eda0b07235282fe36359a5f247e245fa9574
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
