Connect GitHub

Once GitHub is connected, PostShip publishes a Check Run on the deployed commit after every check triggered by a deploy webhook: green if everything passes, red otherwise, with the Ship Score in the title and the detail per URL in the summary. You see the verdict in the pull request without leaving GitHub — and you can make it a merge condition (block a merge).

Prerequisites

The Check attaches to the deploy's commit. So a webhook that brings that commit must be connected:

Install the GitHub app (recommended)

Nothing to create, nothing to run, and revocation is one click on GitHub's side. No secret is stored at PostShip: the app gets a one-hour token on every Check Run.

1. On Project → Deployments → Settings, GitHub Check section, click Connect GitHub.
2. On the GitHub screen, choose the account or organisation, then Only select repositories and the monitored site's repository. The permissions requested are Checks: Read and write and Pull requests: Read and write — the second is used only for the preview comment on the pull request (plus Metadata: Read-only, which GitHub adds by itself). PostShip never reads your code.
3. Authorise: GitHub brings you back to PostShip. The card shows “App installed — choose the repository to monitor”: select it in the list and save. The card switches to Connected.

If the repository belongs to an organisation

GitHub may require an owner's approval. The installation then goes out as an approval request and PostShip tells you so; the connection completes once the request is accepted, by running Connect GitHub again.

With a token, instead

The old path remains supported, folded under Use a token instead, for whoever prefers a token they control.

1. On GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens, limited to the repository concerned, with the Checks permission in Read and write — no other.
2. On the card, fill in the repository in owner/repo format and paste the token (github_pat_…), then Save. It's encrypted and never shown again.

What the Check contains

• Name: PostShip. It's that name the branch protection looks for.
• Title: PostShip · 92, the Ship Score. Followed by the reason when the Check is red: (threshold 80), (payment pages), (deployed during the freeze: …).
• Summary: one line per checked URL, the failures described as in an alert, and the home page's links line.
• On a preview: Preview checked, or Preview: 2 pages failing — without a score, because half of what makes it up makes no sense on a *.vercel.app host.

What turns the Check red is adjustable on the card: Require a green deploy to merge (the default) or Only block on the payment pages. The detail is on Block a merge.

Disconnect

Disconnect GitHub removes the repository and the installation id from the project. To remove the app itself from your GitHub account: Settings → Applications → Installed GitHub Apps.

Limits and plans

The Check is included in every plan: it follows the deploy webhooks, which Discover receives too. The minimum score is reserved to Pro Plus. See the plans.

Troubleshooting

Why does no Check appear on my commits?

3 causes, in order: the deploy carried no commit (deploy launched from a terminal, Cloudflare, generic webhook); the registered repository isn't the one the deploy comes from; the app no longer has access to the repository (removed from the installation). The card doesn't flag it: a Check that couldn't be posted never fails the webhook.

Why “GitHub attachment unavailable”?

PostShip can't, on this site, verify that the installation belongs to you (the GitHub app isn't fully configured server-side). Already attached projects keep receiving their Check Runs; use the token in the meantime.

Why “This GitHub installation is already attached to another PostShip account”?

An installation attaches to a single account — a colleague from the same organisation took it, most often. Ask them to detach it (Disconnect GitHub on their project), to invite you to their project, or install the app on another GitHub account. “This GitHub installation isn't yours” means your GitHub account has no access to the chosen installation.

Block a merge on PostShip

Make the PostShip Check a merge condition, choose what turns it red, and set a minimum score.

PostShip publishes a Check named PostShip on the commit of every checked deploy (Connect GitHub). GitHub can use it as a merge condition: it's the same mechanism as your tests. This page says how to require it, what turns it red, and how to harden the rule with a minimum score.

Require the Check on GitHub

1. Open the repository on GitHub, Settings tab.
2. Branches → Add branch protection rule (or edit the existing rule).
3. Branch name pattern: main, or your default branch.
4. Tick Require status checks to pass before merging.
5. In the list, look for PostShip and select it. The Check must have appeared at least once to be in the list: deploy once if needed.
6. Save. A pull request whose Check is red can no longer be merged.

For the Check to land on the pull request before the merge, previews must be checked (Previews): it's the preview's Check that blocks the merge. The production Check, for its part, arrives after the fact and serves as a trace.

What turns the Check red

The setting lives on the GitHub Check section of Project → Deployments → Settings, as a toggle:

The second setting exists because a broken social card doesn't deserve to stop a team; a broken checkout does. It also applies to previews: without that, a missing Open Graph image on a preview turned every pull request's Check red.

The Check's title names what turned it red, and nothing else — a reason shown on every green run is no longer a reason:

• PostShip · 92 — green, or red in “green ship” mode with at least one failure.
• PostShip · 92 (payment pages) — red, “payment pages” mode, a payment page went down.
• PostShip · 71 (threshold 80) — red, Pro Plus, score under the minimum.
• PostShip · 100 (deployed during the freeze: no prod on weekends) — red, the deploy arrived during a freeze. The freeze takes precedence over everything: a perfect ship deployed during the freeze is exactly what the rule wanted to prevent.

The minimum score

The setting is in Project → Deployments → Settings, GitHub Check minimum score card: a Threshold (0–100) field, at 80 by default. Under this score, the Check fails even if no URL returns an error, whatever the mode chosen above. The minimum is only compared with the production score; a preview has no score.

On the host's side

• Vercel can hold back promotion to production as long as an external check isn't green (Deployment Checks, https://vercel.com/docs/deployment-checks). If your Vercel project is linked to the GitHub repository, the branch protection above is already enough: a red pull request can't be merged, so nothing goes to production.

The Ship Gate: production waits for the money

Without a GitHub repository, or for a deploy started by hand, what remains is what Vercel calls a blocking check. Project → Deployments → Settings → Ship Gate → Don't publish if the payment journey breaks: as soon as a production deployment is created, PostShip registers a blocking check on Vercel; once the deployment is built, it checks the home and the payment pages pages (pricing, login, checkout, Stripe.js) on the deployment's unique address — not on your domain, which still serves the previous version — and concludes. All green: Vercel assigns the domain. A payment page failing: the previous site stays online, and the project log says why. It's the opposite of pinging the home: the ship is held.

It needs the Vercel integration (not the hand-pasted webhook) and, on Vercel's side, the Checks capability enabled on the integration. A broken social card or secondary form doesn't hold a ship. If PostShip itself can't check, the promotion is released, and the log says so: our outage must not hold your site. Vercel only — Netlify and Cloudflare Pages have no equivalent API. Pro and above.

• Netlify posts the same Check, on previews as in production.
• Cloudflare Pages and the generic webhook publish no Check: nothing to require on GitHub's side for them.

Limits and plans

Troubleshooting

Why doesn't PostShip appear in the list of status checks?

GitHub only offers checks already seen on the repository. Deploy once with GitHub connected, then come back to the protection rule. If the Check still doesn't appear, the repository registered on the card isn't this one.

Why is the Check green when a page failed?

You're in Only block on the payment pages mode and the page that went down isn't a payment page. The title then says, on a preview, “… failing, outside the payment pages”. Switch to Require a green deploy to merge if everything must block.

Why does the Check block the pull request when production is healthy?

It's the preview's Check that blocks, and it's posted on the pull request's commit. Open it: the summary names the failing page on the preview host. A route that moved breaks on the preview before breaking in production — that's the preview's reason for being.

Why isn't the minimum applied?

It only is on Pro Plus. Below Pro Plus, the card says so: “Without a Pro Plus plan, the Check stays purely informative”.