Supported sources
For a source that cannot be read, saving
wait_for_ci is refused with a 422.
If the setting is already on and the source turns out to be unreadable, the
deploy is skipped with the reason cannot read provider status. The gate never
lets an unreadable source deploy. The provider token is only sent over
https://.
What it does
Whenwait_for_ci is on, an automatic git deploy polls the provider for the
checks of the exact pushed commit:
- All gated checks pass: the deploy starts.
- A gated check fails: the deploy does not start. The failing check names are recorded.
- The wait times out: the deploy does not start.
skipped by CI gate: ...) and fires the app’s deploy notification
channels like any failed deploy.
The commit is always read from the provider API for the stored repository. The
webhook body is never used to decide which checks count. An annotated tag push
is gated on the commit the tag points at, and that same commit is deployed.
Which deploys are gated
Gated, whenwait_for_ci is on:
- Webhook push.
- GitHub release event.
- The missed-webhook poller.
- Scheduled git deploys.
- Build hooks.
- PR comment redeploys.
- Retry build. It rebuilds the connected branch head through the same path as a scheduled deploy.
- Rollback.
- Preview deploys.
- Branch deploys.
- The built-in git push remote.
Request flow
The webhook answers202 at once with accepted: waiting for CI before deploying .... The gate and the deploy then run in the background, so the
provider’s short delivery timeout cannot disable the hook. The delivery row
shows accepted: waiting for CI. The real outcome is in the deploy history,
not on the delivery.
- One wait per app and ref. A newer push for the same ref supersedes the waiting one. The replaced wait is recorded as a superseded info row and does not notify. A push that is the same commit, or provably older than the waiting one, is ignored with a note.
- At most
deploy.ci_gate_max_waits_per_apprefs of one app wait at the same time (default 4, range 1 to 50, changes apply live, see Runtime settings). Past the cap the request is refused with a 429 and can be retried. - A gate that passes after a newer push took over the app does not deploy. It is recorded as superseded.
- Freeze and approval checks that begin during the wait still apply when the gate passes.
Check states
Check names are trimmed. The platform’s own deploy check is ignored so the gate never waits on itself. If the same name is reported more than once, the worst state is used.- No required checks set: every check on the commit counts. If the commit
reports no checks at all, the gate passes after
APP_CI_GATE_NO_CHECKS_WAIT. - Required checks set: only those names are waited for. A required check that has not appeared yet counts as pending.
success,neutralandskippedcount as passed.- A completed check run with any other conclusion fails.
- A run that is not completed is pending.
- A commit status of
failureorerrorfails,successpasses, anything else is pending.
A skipped GitLab job usually means an earlier stage failed, which is why it
cannot satisfy a required name. GitHub is different: a skipped GitHub check
counts as passed even when it is required. This difference is known and not
changed.
On GitLab, a branch push reads statuses for that branch and a tag push for
that tag, so other pipelines on the same commit are ignored. A release-mode
source with no tag reads every ref on the commit.
Timing
The wait is tuned with environment variables on the server. There are no runtime settings for these three.
A value that is missing, not a duration or not above zero uses the default.
Provider rate limits are respected: a
Retry-After or X-RateLimit-Reset
header delays the next poll. Read errors are retried until the timeout, so a
flaky provider never counts as a pass.
When the gate is red
The commit is skipped and recorded in the deploy history. The poller notes the head, so it does not queue the same commit again. A commit whose CI later turns green is not deployed automatically. To recover, use Retry build, which rebuilds the current head of the connected branch, or push a new commit.Restarts
When the server shuts down, waiting gates end and are recorded asinterrupted by shutdown. A webhook that arrives during shutdown gets a 503 so the provider
can redeliver it.
- For a wait started by the poller, the head is left unnoted, so the next poll gates it again.
- For a push to the connected branch, the poller’s previous head is restored when the poller covers the source, so the next poll gates the push again. The poller does not cover sources in release mode.
- Otherwise the row says
and nothing retries it automatically. Push again or use Retry build.
Configure
Dashboard: app, Source tab, “Wait for CI before deploying”. CLI:PUT /api/v1/apps/{name}/git-source/deploy-settings with wait_for_ci
(bool, default false) and ci_required_checks (list of names, at most 50, each
1 to 200 characters). Both are also returned on
GET /api/v1/apps/{name}/git-source.
Troubleshooting
not deployed: cannot read provider status: the source has no connection that can read CI, or its URL is nothttps://. Connect the GitHub App or a GitLab connection for that repository.not deployed: the release tag cannot be resolved for the CI gateorthe release tag could not be resolved in time: the release tag could not be turned into a commit. Check the repository access and that the tag exists.not deployed: commit id is not a full SHA: the trigger gave a short or empty commit id, so nothing can be read.- 422 on save:
wait_for_ci needs a GitHub App or GitLab connection that can read this repository's CI status. The source can never be read. - 503 on save:
could not confirm CI access right now. The connection or token was unavailable. Try again. - 429 on a push:
too many refs of this app are waiting for CI, retry later. Raisedeploy.ci_gate_max_waits_per_appor retry after a wait ends. - 503 on a webhook during shutdown:
shutting down: redeliver this later. For a push to the tracked branch the poller gates the commit on its next pass after the restart. For a tag, which the poller does not cover, redeliver it from the provider or push again. CI checks failed: <names>ortimed out waiting for CI checks: <names>: a check failed, or the named checks were still pending at the timeout.
Known limits
- A build hook on a protected environment parks its request for approval before the gate runs. Approving it does not run the gate again.
- In release mode every tag gets its own wait. Someone with the webhook secret or tag push rights can fill the wait cap with tags that never finish, and a real release is then refused with a 429 until a wait ends. Nothing deploys without passing the gate.
- A tag push and a release event for the same tag can both start a deploy if they pass the gate in the same instant.
- The gate timing values are read from the environment at start and are not runtime settings. Only the wait cap is a runtime setting.
- Requests held for approval or a freeze before an upgrade replay without the gate.