Integration
GitHub
Connect a GitHub account, install Ship Guard in a repository, and keep release readiness visible on every push.
PreFlight uses GitHub OAuth to install the Ship Guard workflow in repositories you choose. The workflow runs on GitHub Actions, then sends a bounded readiness report back to PreFlight for the project dashboard and pull request status.
Requirements
<IntegrationRequirements
items={[
"A PreFlight workspace and a project you can manage",
"A GitHub account with access to the repository and permission to create workflow files",
"Repository access approved during GitHub OAuth (the repo scope for private repositories, or public_repo for public repositories)",
"Repository secrets for PREFLIGHT_API_KEY and PREFLIGHT_SCHEMA_SYNC_SIGNING_SECRET before the workflow runs",
]}
/>
The Ship Guard workflow keeps source code in GitHub. It sends the check results needed for readiness analysis, including command outcomes, dependency severity counts, environment-key names, and file paths flagged by the secret-pattern scan. It does not send environment-secret values.
What PreFlight checks
| Probe | What it proves |
| --- | --- |
| GitHub OAuth | The selected GitHub identity and approved repository scope can be used by PreFlight. |
| Repository workflow | The Ship Guard workflow is present on the selected branch. |
| Build check | The repository build command completes in GitHub Actions. |
| Dependency audit | Known dependency vulnerability severity counts are reported. |
| Environment parity | Required environment-key names can be compared without exposing values. |
| Schema and secret-pattern checks | Migration output and potential secret-bearing file paths are surfaced for review. |
Dashboard setup
Open Ship Guard in the PreFlight dashboard and select Connect GitHub.
Approve the GitHub authorization request, then select the PreFlight project, repository, and branch.
Install the Ship Guard workflow. PreFlight commits .github/workflows/preflight-ship-guard.yml to the selected branch.
In the repository settings, add PREFLIGHT_API_KEY and PREFLIGHT_SCHEMA_SYNC_SIGNING_SECRET as Actions secrets.
Push a commit or open a pull request, then confirm the Ship Guard result appears in PreFlight.
Failure guidance
| Symptom | Fix |
| --- | --- |
| Authorization returns to PreFlight with an error | Confirm the GitHub OAuth app callback URL is `/api/github/callback`, then reconnect. |
| Workflow installation fails | Ensure the connected GitHub account can write to the selected branch and create files under `.github/workflows/`. |
| Workflow cannot submit results | Add both required repository secrets and make sure their values match the PreFlight project configuration. |
| Private repository is unavailable | Reconnect GitHub and approve the `repo` scope. |
| Launch Guard webhook cannot register | Ask a PreFlight administrator to configure `GITHUB_WEBHOOK_SECRET` on the PreFlight deployment, then retry from Ship Guard. |
<RelatedLinks
links={[
{ href: "/dashboard/ship-guard", title: "Ship Guard", description: "Connect GitHub, install the workflow, and review readiness results." },
{ href: "/docs/guides/deploy-gates", title: "Release Rules", description: "Use readiness results to enforce deployment gates." },
{ href: "https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps", title: "GitHub OAuth docs", description: "GitHub guidance for OAuth authorization and callback configuration." },
]}
/>
