Ocean Assurance connects a pull request to a neutral GitHub Check and a Change Passport: a reviewable account of the change, its evidence and what remains uncertain.
Evidence for your review. The pilot observes changes and reports findings. Its neutral Check does not approve a pull request or block a merge.
A pull-request or check event reaches the receiver through the configured HTTPS endpoint.
The receiver validates and saves it.
The service checks the signature, expected host and enrolled repository. It acknowledges a delivery only after durable storage.
A worker reviews the source.
The worker fetches and reads the relevant pull-request source. Pull-request code is never checked out or executed as part of this review.
Results return to the review.
A neutral GitHub Check presents the decision and reasons, with a link to the authenticated Passport evidence page.
02 / GITHUB
A Check alongside your existing CI
The GitHub App pilot is scoped to one enrolled repository. Your repository administrator approves the installation on that repository. For an Ocean-operated pilot, Ocean configures the webhook endpoint and authentication settings.
The Check brings the review summary into GitHub. Open its details to inspect the Passport, and compare the report's commit identity with the change you are reviewing. A result for an older commit is not evidence for a newer change.
Keep the two results distinct. GitHub's neutral conclusion describes the Check's behavior. The assurance decision describes the evidence assessment. A completed neutral Check can still report INCONCLUSIVE.
03 / CHANGE PASSPORT
Read beyond the headline
A Passport is the evidence page behind the Check. Use it to understand the review and decide where human investigation is needed.
Look for
What to check
Change identity
Confirm the repository, pull request and commit match your review.
Decision & reasons
Read the explanation and any missing inputs before interpreting the outcome.
Findings & citations
Follow the supporting source references and assess them in context.
Controls & evidence
Check which claims have evidence and which remain unverified.
Uncertainty
Treat incomplete evidence as an explicit gap requiring follow-up.
Passport access uses GitHub sign-in and the service's authorization checks. A link to a Passport does not itself grant access to its contents.
04 / INTERPRETATION
Uncertainty is part of the result
INCONCLUSIVE means the review cannot establish a conclusive assessment from the available inputs. It is not an approval. Read the reasons to identify the missing evidence or unresolved question.
Intent and acceptance criteria help frame a review, but proposed criteria are not proof of conformance. Optional extraction and explicit specification inputs depend on the deployment's configuration; the pilot does not implicitly discover every external conversation or ticket.
Use the report as a starting point for engineering review. The prototype's findings and control mappings do not constitute regulatory certification.
05 / PILOT SETUP
Who does what
For an Ocean-operated pilot, your team owns repository access, business context and the merge decision. Ocean owns App configuration, service operation and delivery verification.
CUSTOMER ACTIONS
Your team
Choose the pilot repository. Nominate one repository and a technical contact with authority to approve the installation.
Approve repository access. Review the requested GitHub App permissions and install the App on the selected repository only. An organization administrator may need to approve it.
Provide review context. Identify the relevant specifications, acceptance criteria and financial controls. Share only the inputs agreed for the pilot.
Provide a representative PR. Open or update a pull request for the agreed validation, then sign in with GitHub to confirm you can read its Passport.
Act on the result. Review findings, resolve evidence gaps and decide whether to merge using your existing engineering process.
OCEAN ACTIONS
The Ocean team
Prepare the GitHub App. Configure permissions, event subscriptions, webhook URL and OAuth callback for the deployed service.
Operate the service. Manage App credentials securely, enroll the selected repository and run the guarded receiver, durable queue and review worker.
Configure secure access. Set up HTTPS and restricted routes, validate webhook signatures and enforce Passport authentication and authorization.
Verify delivery end to end. Confirm a signed GitHub event produces a neutral Check and an accessible Passport for the expected commit.
Investigate service failures. Diagnose ingestion, queue, authentication and publication problems; communicate any evidence limitations that affect the review.
Handoffs during the pilot
Stage
Customer provides
Ocean confirms
Before installation
Repository choice, technical contact and approved scope.
Required permissions, data inputs and installation instructions.
First review
Installed App, representative PR and reviewer sign-in.
Signed delivery, matching commit, neutral Check and authorized Passport access.
Evidence gap
Missing specifications or evidence, or clarification of expected behavior.
What is missing, why the result is inconclusive and whether another review is needed.
Service issue
PR or Check link and a description of the problem, without credentials.
Diagnosis, recovery action and the status of the affected review.
Pilot closeout
Feedback and a decision on continued access.
Validation results, remaining limitations and agreed next steps.
Ocean verifies the integration; your team owns the merge decision. A neutral Check is not approval. Before expanding a pilot, jointly review recovery, duplicate-delivery handling, new-commit behavior and access-boundary results.
What changes if the customer operates the service?
Agree the operating model before setup. In a customer-operated deployment, your nominated operator also owns infrastructure, DNS, service credentials, process startup and recovery. Ocean supplies configuration guidance and helps validate the integration. Keep secrets in the approved credential store; do not send them through chat or support messages.
06 / BOUNDARIES
Keep the pilot's scope explicit
Signed ingress: the webhook signature authenticates the delivery payload.
Repository enrollment: deliveries for other repositories are refused.
Durable acknowledgement: accepted work is saved before the receiver acknowledges it.
Source isolation: pull-request source is read, never run.
Authenticated evidence: Passport pages require sign-in and authorization.
Restricted routing: expose only the service's required public paths.
These are pilot boundaries, not a claim that every deployment has passed a production security assessment. Keep credentials out of repositories, documentation, screenshots and chat.
07 / QUESTIONS
Common questions
Does a neutral Check mean the change is safe?
No. Read the assurance decision, reasons, evidence and uncertainty, alongside your tests and human review.
Why does the Passport ask me to sign in?
Evidence can contain repository information. The reader authenticates you through GitHub and checks access before displaying it.
Why did GitHub report an invalid signature?
The receiver could not verify the payload. Customer: share the affected PR or delivery reference with Ocean, without secrets. Ocean (or your nominated service operator): check that the webhook secret matches on both sides, reload the service configuration and retry a genuine GitHub delivery. Keep signature validation enabled.
Is this documentation the live Assurance service?
No. This site explains the product. Webhook delivery and authenticated Passport pages are served by the separately configured Assurance deployment.
Can I use it across all my repositories?
The documented pilot is intentionally limited to one enrolled repository. Broader operation requires separate configuration and validation.
ocean