Deterministic merge checks

Run Hyperoru's architecture change gate for the exact pull-request commit without granting repository write authority to an agent.

The Hyperoru architecture-check command turns the workspace change policy into a native GitHub, GitLab, or Bitbucket job result. It audits the full pull-request or merge-request commit, waits for the durable scanner and architecture workflow, then retrieves the persisted architecture comparison for that repository. The installer vendors a reviewed copy into your repository, so a registry outage or unpublished package cannot change the gate that protects a merge.

Deterministic policy protects the merge

Install from the Hyperoru platform repository

./actions/install-architecture-check.sh github /path/to/repository
./actions/install-architecture-check.sh gitlab /path/to/repository
./actions/install-architecture-check.sh bitbucket /path/to/repository

The action fails closed if the returned gate belongs to another concurrent audit. It never asks an agent whether a pull request should merge.

GitHub

Create a workspace API token with audits:read and audits:write, save it as HYPERORU_API_TOKEN, and add the workspace and repository UUIDs as GitHub variables.

.github/workflows/hyperoru-architecture.yml

name: Hyperoru architecture gate

on:
  pull_request:

permissions:
  contents: read

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the pull-request commit
        uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Evaluate the Hyperoru architecture gate
        uses: ./.github/actions/hyperoru-architecture-check
        with:
          api-token: ${{ secrets.HYPERORU_API_TOKEN }}
          workspace-id: ${{ vars.HYPERORU_WORKSPACE_ID }}
          repository-id: ${{ vars.HYPERORU_REPOSITORY_ID }}
          commit-sha: ${{ github.event.pull_request.head.sha }}

Gate outcomes

Outcome	Meaning	Default job result
`pass`	No architecture regression matched the active policy	pass
`review`	Comparable architecture changed and requires a person	fail
`blocked`	A relationship or removal matched a blocking rule	fail
`insufficient_evidence`	Coverage or baseline requirements were not met	fail

The job summary includes source coverage, the policy reasons, change consequences, and owner hints. Configure the required check in the repository's branch protection after its first run.

No ambient write authority

The workflow declares only contents: read. GitHub publishes the job status itself. Hyperoru receives a workspace-scoped API token, and neither a specialist agent nor the audit process receives permission to modify code, checks, pull requests, or branch protection.

GitLab

Connect the GitLab account, explicitly add the project to audit scope, and save a token with audits:read and audits:write as a masked, protected HYPERORU_API_TOKEN CI/CD variable. Add the workspace and Hyperoru repository UUIDs as HYPERORU_WORKSPACE_ID and HYPERORU_REPOSITORY_ID.

.gitlab-ci.yml

hyperoru:architecture:
  image: node:22-alpine
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    HYPERORU_COMMIT_SHA: $CI_COMMIT_SHA
  script:
    - node .hyperoru/architecture-check.cjs
  allow_failure: false

GitLab turns the job exit code into merge-request pipeline status. The Hyperoru token can start and read audits; it cannot push commits, approve a merge request, or change branch rules.

Bitbucket

Connect the Bitbucket workspace, explicitly select the repository, and add the three HYPERORU_* values as secured repository variables.

bitbucket-pipelines.yml

image: node:22-alpine

pipelines:
  pull-requests:
    "**":
      - step:
          name: Hyperoru architecture gate
          script:
            - export HYPERORU_COMMIT_SHA="$BITBUCKET_COMMIT"
            - node .hyperoru/architecture-check.cjs

Bitbucket publishes the step result to the pull request. As with GitHub and GitLab, the command compares the persisted audit ID before enforcing the gate, so a concurrent run cannot silently substitute another result.

CLI inputs

The provider-neutral command accepts HYPERORU_API_TOKEN, HYPERORU_WORKSPACE_ID, HYPERORU_REPOSITORY_ID, and the CI provider's full commit SHA. Optional variables are HYPERORU_API_URL, HYPERORU_DEEP_REVIEW, HYPERORU_TIMEOUT_SECONDS, HYPERORU_POLL_INTERVAL_SECONDS, and HYPERORU_FAIL_ON.