From ad0c4072ce8591006faf3f4dafa46b7148400edc Mon Sep 17 00:00:00 2001 From: Mehdi ABAAKOUK Date: Tue, 1 Sep 2026 21:33:07 +0200 Subject: [PATCH] docs(conditions): document the qualified form for deployment conditions `deployment-success` / `deployment-failure` now accept the same `@/` form the `check-*` attributes already do, so a rule can require an environment be deployed by one particular app rather than by whoever posted a deployment status last. That matters because anyone with `deployments: write` on the repository can post a status for any environment name. The reference only covered checks, so the syntax existed with nowhere documenting it for deployments. Related to MRGFY-8824 Change-Id: I7ad4420d7b4c9fa95631b2f1303600180e94b65e --- src/content/docs/configuration/conditions.mdx | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/content/docs/configuration/conditions.mdx b/src/content/docs/configuration/conditions.mdx index c519aaadb8..2ecb9b2037 100644 --- a/src/content/docs/configuration/conditions.mdx +++ b/src/content/docs/configuration/conditions.mdx @@ -326,6 +326,37 @@ rejected at configuration validation time. Branch-protection-synthesised conditions and legacy GitHub commit statuses carry no GitHub App identity and remain reachable only via the bare form. +### Qualifying Deployments + +`deployment-success` and `deployment-failure` take the same qualified form, +with a deployment environment in place of the check name: + +`@/` + +Anyone with the `deployments: write` permission on the repository can post a +deployment status for any environment name, and two apps can deploy the same +environment. The bare form matches whichever one reported most recently, so pin +the app when who deployed is part of what the rule is about: + +```yaml +pull_request_rules: + - name: comment once staging is live + conditions: + # The staging deployment published by Netlify, not one posted by hand. + - deployment-success = @netlify/staging + actions: + comment: + message: Staging is live. +``` + +The bare form keeps matching a deployment from any source, so existing +configurations do not need to change. + +A deployment status carries an app identity only when a GitHub App posted it +with its own installation token. One created by a person is reachable only +through the bare form, and so is one recorded before Mergify started keeping +the identity. + ## Matching Cancelled Checks The `check-cancelled` attribute matches checks that report a `cancelled`