pytest-mergify
Pytest plugin for Mergify Test Engine.
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 first the tests a merge-queue bisection step failed in the step above, and stops as soon as one fails again
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 MERGIFY_CI_ENABLE=true.
Environment Variables
| Variable | Description | Default |
|---|---|---|
MERGIFY_TOKEN |
Mergify API authentication token | (required) |
MERGIFY_API_URL |
Mergify API endpoint | https://api.mergify.com |
MERGIFY_CI_ENABLE |
Force-enable outside CI | false |
MERGIFY_CI_DEBUG |
Print spans to console instead of uploading | 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 |
The names these replace, PYTEST_MERGIFY_ENABLE and PYTEST_MERGIFY_DEBUG,
are deprecated: they still work when the new name is not set, and the plugin
says which one to switch to at the end of the session.
For detailed documentation, see the official guide.
Test selection
When Mergify's merge queue splits a failed batch, each bisection step only needs to tell whether it is red. The plugin asks Mergify whether the current run is such a step and, if so, runs first the tests this job failed in the run the step was split from (Fail First). They run before every other test; if one of them fails again, the step is red whatever the rest does, so the run stops there (exit code 1, the remaining tests not run) and the queue can split again without waiting for the suite. If they all pass, the rest of the suite runs as usual. No test is ever skipped, so a green step still comes from a full suite. A test a retry rescued, or a quarantined failure, does not stop the run.
This is off until you turn it on, per job. Installing the plugin is not
enough: set MERGIFY_TEST_SELECTION_ENABLE=true on the job you want to run
its failures first:
- 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 its
suite in its usual order; 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 other situation — a run that is not a bisection step, an unreachable API, an answer from a newer Mergify this plugin does not understand — runs the full suite in its usual order. 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.
Under pytest-xdist this works with the load (the default with -n) and
worksteal schedulers; with loadgroup, tests marked xdist_group still run
before them. With loadscope and loadfile, xdist
schedules whole modules or classes by size, so those tests do not run first:
the run still stops once they have all run and one failed again. Workers on a
remote gateway (--tx ssh=…) run to the end.
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 bisection step 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 step simply runs its full suite in its usual order.
Development
Prerequisites
- Python >= 3.10
- uv
Setup
uv sync
Running Tests
uv run poe test
uv run poe build builds the wheel into dist/; when one is there,
poe test runs against it rather than the project's own install, which is
how CI builds the extension once for every Python version. Every uv-driven
build of the extension uses Cargo's dev profile.
Linting
uv run poe lint
License
Proprietary. Use is governed by the Mergify Terms of Service.
Metadata
Release files for pytest-mergify 2026.10.7
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.7-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| pytest_mergify-2026.10.7-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 24.7 MB
Release files / pytest_mergify-2026.10.7-cp310-abi3-win_amd64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8b1af12d6a7b2228002465736cf248e4b63900df58e26377bb7b39576b974f61
|
|
BLAKE2b-256 checksum How to use checksums |
c48e4ca8452d91b69831a6778e6c549abfbddf91923206024261efc424f56173
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 3.9 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3e4a8b6d7adc64b611f6daa49ffca64c21448385984c173b9d36f8ecbf182b0d
|
|
BLAKE2b-256 checksum How to use checksums |
fc13330ae3cc3f96bb4599a82140de4ae7efd001eaa2ddbef8fa8544ee7d9ce4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
897302350111dfdff59972201a37cbb615a9102be3cecf08b53be28bc6aa4731
|
|
BLAKE2b-256 checksum How to use checksums |
29272704eac15b0a495f3d0d20e4e102881030643f7ee3db9fe55f4dd3175487
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
71c364557431420c145df73a0cf11ec6de2ddf69a260ae62493ec0f04c0fe4d6
|
|
BLAKE2b-256 checksum How to use checksums |
4900a0e7a52793f8a25427c76edfa41127ab37e0487873449e77d6112ecb3e82
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
bf01a189c79f3e8acb4967bcd03230a2f9260efe30f5d5823bef0ce2d95a505f
|
|
BLAKE2b-256 checksum How to use checksums |
357b9c7d6a4f008e37c58db6c284665c2848e9e74a94f5cf1f91e5ee5546a82d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f62129434cc6279162508091193f683defa1e1a4b5e508038f0ceeda0b01b10a
|
|
BLAKE2b-256 checksum How to use checksums |
c18d5f21fccff6bbbfdeb32c68e0c107b525500e3fd21098bf5caff37ff1e269
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logRelease files / pytest_mergify-2026.10.7-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | pytest_mergify-2026.10.7-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
1fd8cafe4dd27a029554b74f1bf543246a2752aac4afc8dd7559ee9b7f1adf13
|
|
BLAKE2b-256 checksum How to use checksums |
acc8d003b5571aec7deb5f626563730cb2bbb2ad5c1463972170fe5ce420e9e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 23, 2026.
Transparency logSecurity for pytest-mergify 2026.10.7
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.
Full provenance
All 7 files in this release have been uploaded with provenance metadata.
Attestation for pytest_mergify-2026.10.7-cp310-abi3-win_amd64.whl
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 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
