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.
CUSTOMER GUIDE / FIRST REVIEW
From installation to your first Passport
Use this guide with your Ocean pilot contact. You need a GitHub account with access to the agreed repository, permission to install Apps or request administrator approval, and a small representative pull request.
Installation availability — checked 20 October 2026. GitHub currently lists Ocean Assurance Pilot as a private App. External customers cannot self-install it yet. Ocean must make a customer-installable App available and confirm your repository is enrolled before you proceed. An installation request alone does not activate review.
The installation link may be unavailable to your account while the App is private. View the App’s GitHub page. If access is unavailable, contact your Ocean pilot contact; do not create a replacement App.
Confirm the pilot scope with Ocean.
Customer: share the repository name and technical contact, and agree which PR and specifications to use. Ocean: confirm installation availability, repository enrollment and service readiness. Wait for that confirmation before triggering the first review.
Install the App on the agreed repository.
Once Ocean confirms access, open the installation link and sign in to GitHub. Choose the account or organization that owns the repository. Select Only select repositories, choose the single agreed repository, review the permissions and finish installation. If GitHub offers a request instead of installation, ask your organization administrator to approve it.
Verify: the App appears in your account or organization’s installed GitHub Apps and the selected repository is included. Tell Ocean installation is complete; never send App keys or secrets.
Open a small, representative pull request.
After Ocean confirms enrollment, open a new PR in the pilot repository, or push a small agreed update to an existing PR. Describe the expected behavior and reference the relevant specification or acceptance criteria. Record the latest commit SHA from GitHub.
Verify: your PR targets the enrolled repository and contains the commit you want reviewed. You do not need to merge it to run the pilot review.
Find the Ocean Check in GitHub.
Open the PR’s Checks tab or its checks summary and locate the Check published by Ocean Assurance Pilot. Allow the review to finish, then read the decision and reasons. Ocean handles signed delivery, queuing and publication; no customer terminal command is required for an Ocean-operated pilot.
Verify: the completed Check is for the latest commit and has a neutral conclusion. A neutral conclusion means the integration completed without acting as a merge gate; it does not mean the change passed assurance.
Open the linked Passport and sign in.
Follow the Passport or details link supplied with the Ocean Check. Use GitHub sign-in when prompted, review any authorization request, and use the account that has access to the pilot repository. Return to the Passport after sign-in.
Verify: the evidence page loads and identifies the expected repository, PR and commit. Read the decision, reasons, source citations and missing evidence. An INCONCLUSIVE result can be a valid integration outcome when evidence is insufficient.
Confirm the first review with Ocean.
Send your pilot contact the PR link, Check link, Passport link and any observed issue. Ocean confirms the delivery and publication path; your team confirms that the evidence is understandable and relevant. Keep repository information within the agreed support channel and omit credentials.
Done when: a Check exists for the expected commit, your authorized reviewer can open its matching Passport, and both teams understand any remaining evidence gaps. Your team retains the merge decision.
If a step does not work
What you see
Customer action
Ocean action
Private App or installation unavailable
Stop and share the App URL with your pilot contact.
Provide a customer-installable App and confirm the agreed access model.
Administrator approval pending
Ask the organization administrator to review the installation request.
Explain the required permissions and wait for approval before enrollment verification.
No Check or Check remains queued
Share the PR link and latest SHA; confirm the App includes the repository.
Inspect signed delivery, enrollment, queue and worker status; recover or redeliver as appropriate.
Passport denies access or sign-in loops
Use the GitHub account with repository access and share the error without tokens.
Check reader authorization, OAuth callback and session configuration.
Report refers to an older commit
Compare the SHA and avoid treating that report as evidence for the latest change.
Check new-commit ingestion and publish the corresponding review.
Decision is INCONCLUSIVE
Read the reasons and supply agreed missing evidence or context.
Explain the gap and determine whether the review should be repeated.
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