Skip to main content

Wait for CI before Deploy

By default, auto-deploy ships every push the moment it lands. Wait for CI adds a gate in front of it: a push is held until GitHub reports that the commit's checks (GitHub Actions, or any CI that posts a check run) have passed. A commit whose tests fail never reaches your server.

Nothing ships silently either way — a held deploy is clearly shown in the dashboard, and you can always override it.

Requirements​

Wait for CI is driven by GitHub's check_suite events, so it needs:

  • The app connected to GitHub through the GitHub App integration (not a plain deploy key). See Connect GitHub.
  • Auto-deploy enabled — Wait for CI gates the automatic deploy; it does nothing for manual deploys.
  • Your GitHub installation to have granted Vessl the Checks (read) permission. If it hasn't yet, enabling the toggle tells you exactly what to do (see below).
Image-based apps

Wait for CI applies to apps built from source. Apps that deploy from a prebuilt container image don't build from a commit, so the toggle is unavailable for them.

Enabling Wait for CI​

  1. Open your app → Settings tab.
  2. Scroll to Auto-Deploy and make sure Deploy on Push is on.
  3. Turn on Wait for CI.

That's it — the next push to your watched branch will wait for its checks before deploying.

"Approve the Checks permission" — what it means​

If you see a message like "Wait for CI needs the Checks permission approved for your GitHub installation", GitHub hasn't yet granted Vessl permission to read your check results. This is a one-time approval:

  1. Go to github.com/settings/installations (for an organization, open its Settings → GitHub Apps).
  2. Click Configure on the Vessl app.
  3. Approve the pending Checks: Read-only permission request shown at the top.
  4. Return to Vessl and turn the toggle on again.

Vessl asks for the minimum — read-only access to check results. It never gets write access to your code from this.

What you'll see​

When a gated push arrives, the app's Overview shows a Waiting for CI banner naming the commit:

⏳ Waiting for CI — Commit abc1234 has not been deployed. Wait for CI is on, so Vessl is holding this release until GitHub reports your checks green.

From there, one of three things happens:

GitHub resultWhat Vessl does
Checks passThe held deploy is released and ships automatically.
Checks failThe deploy is marked CI failed and does not ship. Fix the commit and push again.
No result after 15 minutesVessl notifies you and keeps the deploy held — it never guesses "ship it".

Deploy anyway​

Sometimes CI itself is broken, not your code, and you need to ship regardless. Click Deploy anyway on the Waiting-for-CI banner to release that one held deploy immediately. Wait for CI stays on for future pushes — the override is per deploy, not a setting change.

Turning it off​

Turn the Wait for CI toggle off in Settings → Auto-Deploy. Any deploy currently held is released right away, so revoking the policy never leaves a push stuck behind it.

Troubleshooting​

A deploy is stuck on "Waiting for CI." Two common causes:

  • No CI runs on this branch. Wait for CI waits for a check that never comes. Either add a workflow that runs on your branch, or turn Wait for CI off. Use Deploy anyway to release the current one.
  • The Checks permission isn't approved. Vessl can't receive check results for that installation. Approve it as described under Enabling Wait for CI above, then push again or click Deploy anyway.

Checks passed on GitHub but the deploy didn't release. Vessl re-asks GitHub for every check suite on the commit before releasing — if one suite is still running or was re-run, it waits for the final result. Give it a moment; if it's genuinely green everywhere, use Deploy anyway.