Security
Mergify's security posture: compliance, data handling, access control, application key permissions, leaked application keys, SBOMs, and the GitHub App permissions we request.
Mergify runs in front of GitHub to evaluate merge conditions and orchestrate your pipeline. This page documents our compliance posture, how we handle your data, the access controls in place, what an application key can be limited to and what happens to one that leaks, where to find the software bill of materials of each package we publish, and the GitHub App permissions we request.
Compliance
Section titled ComplianceMergify is SOC 2 Type II attested. Reports, audit details, and our sub-processor list are available in the Trust Center.
A Data Processing Addendum (DPA) is available on request. Contact security@mergify.com.
Data handling
Section titled Data handling-
Encryption in transit: TLS 1.2 or higher.
-
Encryption at rest: persisted service data, such as configuration and metadata, is encrypted with AES-256.
-
Service status: real-time availability and incident history at status.mergify.com.
Access control
Section titled Access controlMergify has no login of its own. Users sign in through GitHub, and their access
to a repository is inherited directly from GitHub
roles:
a user with the Read role on a repository in GitHub also has the Read role
in Mergify.
Some operations also require the GitHub organization Owner role.
See the Features Permissions table below for the
full mapping between GitHub roles and Mergify capabilities.
Single Sign-On (SSO)
Section titled Single Sign-On (SSO)GitHub is the only way to sign in to Mergify. There is no native Mergify login (no email/password) and no way to connect your identity provider directly to Mergify. Sign-in goes through GitHub OAuth, so whatever authentication policy you enforce on your GitHub organization (including SAML SSO with Okta, Azure AD, Google Workspace, or any other identity provider) applies automatically to Mergify.
To enforce SSO for your team’s Mergify access, configure SAML SSO on your GitHub organization. GitHub’s documentation covers the steps for each identity provider: About identity and access management with SAML single sign-on.
If your organization also restricts GitHub access by IP, see Managing IP Addresses. Mergify’s IPs must be allowlisted for OAuth sign-in to succeed.
Delegated roles
Section titled Delegated rolesSome Mergify operations (such as managing the subscription, managing CI
Insights self-hosted runners, or configuring third-party integrations)
require the GitHub organization Owner role by default. To avoid granting
full GitHub Owner rights to a teammate who only needs one of these
capabilities, GitHub Owners can delegate scoped Mergify admin powers to any
organization member or collaborator from the Mergify dashboard.
Only GitHub Owners and users holding the Delegation Admin role grant and
revoke delegated roles, under Settings → Security & Access → Roles on the
Mergify dashboard.
Granting a delegated role requires the Enterprise plan; see Mergify’s pricing page. Listing the roles and revoking one do not, so a role granted earlier keeps working and can still be revoked after a plan change.
Each user can hold any combination of the following roles:
| Role | Grants |
|---|---|
| Billing Admin | Manage the Mergify subscription and billing details: invoices, plan changes, and the Stripe customer portal. |
| CI Admin | Configure CI Insights at the organization level (self-hosted runner fleet), manage the application keys limited to CI Reporting (see Application keys), and write the trust policies that let GitHub Actions jobs authenticate with their ID token. |
| Integrations Admin | Configure the default products for new repositories and the Slack and Datadog notification integrations at the organization level. |
| Delegation Admin | Manage the delegated-role roster itself: grant or revoke any of the roles above (including this one) to other users. |
Application keys
Section titled Application keysAn application key is the credential a script, an agent or a CI job uses to call the Mergify API without anyone signing in. It belongs to the organization it was created in, not to the person who created it, and holds no GitHub role. What it may do is set on the key itself:
-
Permissions per resource. A key holds a level on each resource of the API (No access, Read or Read & write) and calls nothing beyond them. A key created with the
adminscope, before permissions existed, holds Every resource at Read & write. CI Reporting, which uploads CI results, is a permission of its own that a key granted Every resource does not hold: a CI key holds it alone. See Application key permissions. -
Every repository of the organization. A key reaches every repository of its organization, within its permissions. It cannot be limited to some repositories.
-
Who manages keys. The GitHub organization
Owners manage every key. A user holding the CI Admin role creates, renames and deletes only the CI keys. -
Permissions can change, the secret does not. An
Ownercan narrow or widen the permissions of any key but a CI key. The key keeps its secret, and its next request is decided by the new permissions. -
Optional expiry. A key can be given an expiry date when it is created, and a CI key made instead of OIDC must be. The date cannot move afterwards. Past it, every request made with the key is refused with
401. -
Refusals give nothing away. Mergify checks the key’s expiry and permission before it looks up anything the request names. A request the key lacks the permission for, one naming another organization, and one naming a repository that does not exist all get the same
403with the same message, so a key cannot be used to find out what exists outside its organization.
Every change to a key is recorded in the organization’s activity log, with who
made it, under Settings → Security & Access → Activity Log on the
dashboard. GitHub Owners and CI Admins can
read it.
| Event | What it records |
|---|---|
| Application Key Created | The key’s name, permissions and expiry date, and where a CI key runs and why. |
| Application Key Permissions Changed | The key’s permissions before and after. |
| Application Key Renamed | The key’s previous name and its new one. |
| Application Key Deleted | The permissions the key had. |
| Application Key Revoked | A key Mergify deleted because GitHub found it published, and where it was found. |
GitHub secret scanning
Section titled GitHub secret scanningMergify application keys are among the secrets GitHub scans for. When GitHub finds a Mergify application key in a public repository (its code, issues, pull requests, discussions or wiki), in a secret gist or in a public npm package, it reports the key to Mergify, and Mergify deletes it at once. From then on, every request made with that key is refused.
Mergify does not notify anyone when it deletes a key. The key disappears from Settings → Security & Access → API Keys on the dashboard, or from CI Authentication for a CI key. The activity log records it as revoked, and whatever used it starts failing. Create a new API key or CI key and put it everywhere the deleted one was used: your CI provider’s secrets and any webhook that sends it, such as the Buildkite webhook for CI Insights. Keep it in a secret store rather than in the repository.
GitHub reports to Mergify only the keys it finds in public repositories, secret gists and public npm packages. A key committed to a private repository keeps working: GitHub secret scanning, if enabled on that repository, alerts you instead, and you revoke the key yourself. The same goes for a key issued by an on-premise installation of Mergify, since GitHub reports to Mergify’s hosted service, which does not hold that key.
Software bill of materials
Section titled Software bill of materialsThe Mergify CLI and the test framework plugins ship compiled Rust code. For every package file that holds some, each release publishes a CycloneDX 1.5 software bill of materials (SBOM): the Rust crates compiled into that file and their versions, with the license and SHA-256 checksum of each crate that comes from crates.io. Crates that only run while the package is built are left out, so the list matches what you install. Load it into Dependency-Track, Grype or Trivy to see whether a vulnerability in a bundled crate reaches your CI.
The SBOMs are attached to the Mergify CLI
releases on GitHub. Each
release there carries the files of every package published at that version,
the test framework plugins included. An SBOM sits beside the file it
describes and takes that file’s name followed by .cdx.json, and the
release’s SHA256SUMS lists it with the other files.
| You install | The SBOM is beside |
|---|---|
The |
|
mergify-cli from PyPI | mergify_cli-<version>-py3-none-<platform>.whl |
pytest-mergify | pytest_mergify-<version>-cp310-abi3-<platform>.whl |
| mergifyio-ci-native-<platform>-<version>.tgz |
rspec-mergify or minitest-mergify | mergify-ci-core-<version>-<platform>.gem |
The JavaScript plugins and the RSpec and Minitest gems hold no compiled code
themselves. Their compiled code comes in the package they install for your
platform, @mergifyio/ci-native-<platform> from npm or the mergify-ci-core
platform gem, so that package’s SBOM covers them.
For example, to scan the SBOM of the latest pytest-mergify wheel for Linux
x86_64 with Trivy:
gh release download --repo Mergifyio/mergify-cli \ --pattern 'pytest_mergify-*-manylinux_2_28_x86_64.whl.cdx.json'trivy sbom pytest_mergify-*-manylinux_2_28_x86_64.whl.cdx.jsonGive gh release download the version you install as its first argument to
fetch that release’s file instead. Grype reads the same file as
grype sbom:<file>.
You can also skip the download. Each compiled binary carries its own crate
list, embedded with
cargo auditable, and
Trivy, Grype, Syft and cargo audit bin read it from the binary in an
installed package or a container image. Trivy reads only executable files,
though, and npm installs the @mergifyio/ci-native-<platform> addon without
the executable bit: scan that one with Grype, Syft or its SBOM.
The pytest-mergify and mergify-cli wheels hold a second SBOM, in their
.dist-info/sboms/ directory. That one lists the crates that only run while
the package is built too.
Vulnerability disclosure
Section titled Vulnerability disclosureMergify hosts a public Bug Bounty program with HackerOne. If you believe you’ve found a security issue on our platform, please disclose it responsibly.
For other security questions or concerns, contact our security team at security@mergify.com.
Reference
Section titled ReferenceMergify requests a fixed set of GitHub App permissions required for the product to operate. Some permissions are only exercised by specific features.
GitHub App required permissions
Section titled GitHub App required permissionsBelow is the list of the required permissions on GitHub for Mergify to function properly.
| Permission | Access | Usage |
|---|---|---|
| Repository: Actions | Read and write | Used to read workflow runs and job logs, and to re-run workflow runs
and failed jobs for CI Insights Auto-Retry.
Write access also lets the deprecated
|
| Repository: Administration | Read-only | Used to read branch protection settings and repository rulesets. |
| Repository: Checks | Read and write | Used to read and post checks. |
| Repository: Commit statuses | Read-only | Used to read the commit statuses your CI reports.
Conditions such as
|
| Repository: Contents | Read and write | Used to read repository content and write (merge). |
| Repository: Deployments | Read and write | Used to read deployment statuses for the |
| Repository: Issues | Read and write | Used to read and write the parts of a pull request that GitHub serves under its Issues API: labels, assignees, comments, and reactions on comments. |
| Repository: Metadata | Read-only | Access repository metadata. |
| Repository: Merge queues | Read-only | Used to receive GitHub merge queue events. |
| Repository: Pages | Read and write | Used so that GitHub publishes your Pages site after a merge Mergify performs: without write access, GitHub does not start the Pages workflow for that merge and the site does not update. Mergify makes no Pages API call itself. |
| Repository: Pull requests | Read and write | Used to read and edit pull requests. |
| Repository: Workflows | Read and write | Used to read workflows and to write a pull request’s changes under
|
| Organization: Administration | Read-only | Used to receive organization-level ruleset events and read the organization’s default repository permission. |
| Organization: Members | Read-only | Used to list organization owners and the members of each team, so that a
team named in a condition or an action, such as
|
| Account: Email addresses | Read-only | Used to read the email addresses of users who sign in to the Mergify dashboard. |
Features permissions
Section titled Features permissionsTo perform any action on Mergify (such as adding a pull request to a merge queue or triggering a command), a user must have sufficient access to the relevant account or resource. Permissions are inherited from GitHub roles.
| Feature | Repository role | Organization role | ||||
|---|---|---|---|---|---|---|
| Read | Triage | Write | Maintain | Admin | Owner | |
| Merge Queue | ||||||
| View the merge queue | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Pause the merge queue | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Merge Protections | ||||||
| View merge protection status | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Edit merge protection rules in .mergify.yml | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Schedule a queue freeze | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| CI Insights | ||||||
| View CI Insights data | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Activate CI Insights on a repository | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Manage CI Insights Auto-Retry rules | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Configure CI Insights self-hosted runners | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Test Engine | ||||||
| View Test Engine data | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Quarantine or unquarantine tests | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Configure Test Engine Auto-Quarantine | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Account | ||||||
| Manage application keys | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Manage Mergify subscription | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Products & Integrations | ||||||
| GitHub integration: Enable or disable Mergify products | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| GitHub integration: Configure default products for new repositories | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Third-party integrations: Configure Slack and Datadog notification integrations | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
Command permissions
Section titled Command permissionsMergify commands are restricted by default and have their own mechanism that can be modified. See Commands Restrictions for changing the default.
Action permissions
Section titled Action permissionsActions in pull_request_rules have no equivalent
default restriction. They run whenever a pull request matches the rule’s
conditions, whoever opened it, and Mergify runs them with its own permissions or
with those of the bot_account you configure. The conditions are what scopes a
rule.
This matters for actions writing to the pull request’s head branch, such as
update, because its author picks that branch. On a
same-repository pull request it is one of your branches, and opening a pull
request from a branch that already exists takes only read permission, so a rule
whose conditions describe only the state of a pull request acts on whichever
branch that person named as the head. Conditions on the
author or on a label, or a
pattern on head, keep the rule off the branches you care about. The same
reasoning drives the default restrictions on the
update, rebase and squash commands.
Managing IP addresses allowed for the GitHub App
Section titled Managing IP addresses allowed for the GitHub AppGitHub allows you to configure the list of IP addresses that a GitHub App is allowed to use to access GitHub.
Mergify services use the following IP addresses:
- 34.121.26.35/32
- 34.45.103.142/32
- 34.69.118.185/32
- 34.63.9.219/32
- 136.119.26.243/32
Was this page helpful?
Thanks for your feedback!