GitHub Integration for Product Journeys

The GitHub Integration for Product Journeys connects repository-owned source and CI identity to Reshot Journey activation, verification status, pull-request checks, comments, and release consequences. It preserves the distinction between historical delivery and current posting readiness.

Reachable setup

The application exposes GitHub App installation and authentication routes, project integration settings, webhook handling, repository selection, and delivery status. The Journey activation workbench uses a configured development integration to discover and run native Playwright source server-side.

A configured repository alone does not prove current posting access. The status model distinguishes stored/historical delivery from whether the installation and permissions can post now.

Source activation

Register repository, branch, test root, Playwright config, and CI provider. Reshot reads the authorized checkout, hashes source identity, and executes the native workflow. Unsupported constructs remain protected.

Only an exact native-run-passed contract can proceed to canonical Journey binding. A repository name or test filename is not Journey evidence.

Pull-request delivery

The integration delivery outbox models GitHub check and comment payloads. Delivery uses idempotent external identity and tracks attempts, current posting readiness, success/failure state, and historical evidence.

Release policy can produce a GitHub Checks result with Run and Decision identity, outcome, rationale, and stable external ID. The check summarizes signed Reshot policy; GitHub does not become the authority for the underlying Journey evidence.

Webhook ingestion

GitHub webhook events require signature verification, tenant/project resolution, idempotency, and bounded processing. Treat repository metadata and event payloads according to workspace privacy and retention policies.

Do not accept an unsigned request or reuse delivery events across tenants. Failed delivery must remain retryable without creating duplicate comments or check runs.

Evidence boundary

GitHub contains commits, pull requests, checks, comments, Actions, and source. Reshot contains Journey Versions, State Capsules, Runs, Observations, Decisions, Renditions, Publications, and Release Books. Link them with exact IDs and hashes.

A green GitHub check cannot override expired risk, missing context, stale documentation, failed Publication, or privacy evidence. Conversely, a Reshot Release Book does not merge or deploy code.

Permissions

Request only permissions needed for repository discovery, source access, checks, comments, and webhooks used by the configured workflow. Display whether each capability is currently available. Reauthorization, installation removal, repository restriction, or permission change must update readiness.

Never expose private repository source, access tokens, webhook secrets, or storage-state contents in public marketing or Release Book artifacts.

Installation procedure

1. install the GitHub App for the intended organization or repositories;
2. return through the signed OAuth/install callback;
3. bind the installation to the authorized Reshot workspace/project;
4. verify repository selection and current permissions;
5. configure native Playwright source activation;
6. execute and bind the source contract;
7. configure check/comment policy;
8. trigger a controlled Run;
9. verify the GitHub check/comment external ID and Reshot delivery state;
10. revoke and verify the integration fails closed when appropriate.

Delivery reliability

Use an outbox so the database consequence commits before external delivery. Retry transient GitHub errors with idempotency. Record terminal permission or installation failures separately from transient infrastructure failure. Keep payload hashes and receipts where the API supplies stable identifiers.

Monitor queue age, attempt count, rate-limit responses, installation suspension, missing repositories, and duplicate external IDs. A delayed check should not be presented as current release approval, and a redelivered webhook should not create a second Journey or delivery.

Retain the last verified posting time and permission snapshot.

Security and privacy

Validate webhook signatures before parsing trusted fields. Keep installation tokens server-side and short-lived. Scope repository checkout and command execution. Do not persist storage-state secrets. Sanitize logs. Apply workspace authorization to integration status and control paths.

Validation evidence

Repository tests cover installation status, current posting readiness versus historical delivery, check/comment payload state, and integration behavior. Recovery-lab contracts exercise idempotent check-run updates. These support the real path; they are not a substitute for a production installation receipt.

First proof

Install the App on one test repository. Register one native Playwright Journey. Trigger a Run from a controlled change. Confirm source hash, check status, comment/check delivery ID, Decision linkage, and an affected Publication or Release Book consequence. Remove permission and verify the UI reports not-ready instead of relying on historical success.

Continue with the Playwright integration, Reshot CLI, and Release Evidence for Product Journeys.