TilloTech Docs Harbourmaster GitHub Action
The composite action at TilloTech/eos/apps/harbourmaster runs a Harbourmaster
review for one GitHub pull request. It has no declared outputs.
Runtime
The action uses Bash steps, installs the repository-declared pnpm version with
Corepack, and runs on Node.js 24. It also installs Bun 1.4.2 to run the
built CLI. Every pnpm command starts from the downloaded EOS action workspace so
Corepack cannot select a consuming repository's package manager version. It
restores the pnpm store using the EOS lockfile, installs only Harbourmaster's
workspace dependency graph with a frozen lockfile, exposes its pinned OpenCode
CLI, builds @eos/harbourmaster, configures AWS, and starts the built runner
with the bundled .opencode configuration.
Consumer repositories use TilloTech/eos/apps/harbourmaster@main so they run
the latest Harbourmaster version merged to EOS. Package version 0.5.0 first
supported organization-shared use from the EOS source workspace.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
repo | No | github.repository | Repository in owner/name form. |
pull_number | Yes | none | Pull request number. |
head_sha | Yes | none | Expected pull request head SHA. It must equal the checked-out workspace HEAD. |
mode | No | comment | Run mode: silent, check-only, comment, or blocking. |
debug | No | false | Enables runner debug details. |
strict_runtime | No | false | Fails when degradation prevents real model execution. |
auth_mode | No | github_token | GitHub authentication mode: github_token or github_app. |
github_token | No | github.token | Token for github_token mode. |
github_app_id | No | none | App ID for github_app mode. |
github_app_private_key | No | none | PEM private key for github_app mode. |
github_app_installation_id | No | none | Installation ID for github_app mode. |
workspace_root | No | . | Absolute path or path relative to GITHUB_WORKSPACE for the reviewed checkout. |
aws_role_to_assume | No | none | IAM role ARN assumed through GitHub OIDC. |
aws_profile | No | none | AWS profile for self-hosted runners. |
aws_bearer_token_bedrock | No | none | Bedrock bearer token. |
aws_access_key_id | No | none | AWS access key ID. |
aws_secret_access_key | No | none | AWS secret access key. |
aws_session_token | No | none | AWS session token. |
bedrock_model | No | none | Override for all model tiers. |
bedrock_fast_review_model | No | none | Fast-review tier override. |
bedrock_deep_review_model | No | none | Deep-review tier override. |
bedrock_editor_model | No | none | Editor tier override. |
bedrock_fallback_model | No | none | Fallback tier override. |
artifact_retention_days | No | 1 | Number of days to retain the downloadable OpenCode JSON event-log artifact. |
Supported workflow boundary
The supported setup uses one native pull request workflow. Its
Harbourmaster review job excludes forks and drafts, applies the
harbourmaster-review label, checks out the exact pull request head, and runs
the reviewer. GitHub therefore attaches the job to the pull request without a
custom check run.
Automatic pull request events run the job only when the label is absent. The job
adds the label to record that review cycle. Later commits fail the native check
with a warning before review execution. A human removes and re-adds
harbourmaster-review to review the latest head and satisfy a required check;
automation must not request the re-review.
Consumer repositories invoke TilloTech/eos/apps/harbourmaster@main. EOS itself
invokes its local action from the exact pull request head so Harbourmaster can
test changes to itself before merge. The
self-review invariant
defines this repository-specific boundary; consumer repositories must not copy
the exception.
The repository setup guide contains the complete workflow definition and its validation procedure. See How to request a Harbourmaster review for the operator path after setup. See How to diagnose a Harbourmaster review failure when a job is skipped or fails.
Permissions
| Permission | Purpose |
|---|---|
contents: read | Load repository and pull request file context. |
pull-requests: write | Apply the review label and publish review feedback. |
issues: write | Create the harbourmaster-review label when missing and read issue comments. |
id-token: write | Obtain an AWS OIDC token when aws_role_to_assume is set. |
GitHub owns the native Harbourmaster review job check. The action itself does
not create GitHub checks, and check-only mode controls review publication
rather than the job status.
Authentication behavior
github_token mode uses the explicit github_token input or the workflow
token. github_app mode exchanges the app ID, private key, and installation ID
for an installation token before constructing Octokit.
If the selected mode lacks its required credentials, the action prints
GitHub token unavailable; skipping safely. or
GitHub App credentials unavailable; skipping safely., sets
HARBOURMASTER_SKIP=true, and leaves the job successful. Credential values are
masked before validation. Resolved GitHub credentials are removed from the
ambient runner environment. The runner passes the resolved token only to the
coordinator process; specialists receive neither the token nor GitHub tools.
GitHub App installations need contents read, pull requests read and write, and
issues read so the action can load issue comments. The supported workflow still
uses GITHUB_TOKEN with issues: write to create the harbourmaster-review
label. That label step does not use the App token.
Fork and draft behavior
The runner skips drafts and pull requests whose source is a fork. The runner fork skip message is:
Fork pull request skipped by policy.
The supported workflow also skips both cases in the job if condition. That
guard runs before checkout, dependency installation, OIDC, or action execution.
GitHub then shows the job as skipped. The job does not print a skip message.
Do not run this action with pull_request_target against untrusted head code.
Dependabot pull requests from the same repository are not forks. They can start
a review unless a separate workflow guard excludes them. Fork pull requests need
a separate trusted rerun or an artifact-based workflow that does not expose
credentials to the pull request checkout.
Workspace verification
workspace_root is resolved relative to GITHUB_WORKSPACE when it is not
absolute. The action requires the directory to exist, contain a readable Git
checkout, and have a HEAD exactly equal to head_sha. A missing value or
mismatch fails before OpenCode starts.
The CLI also receives GITHUB_WORKSPACE as its workspace boundary. Canonical
path checks prevent a workspace symlink from redirecting read tools outside the
selected checkout.
OpenCode and model behavior
The action always uses Harbourmaster's bundled OpenCode agents and plugin. A
consumer repository's .opencode directory is inert review context. Model
inputs become HARBOURMASTER_*_MODEL environment variables; the
configuration reference defines their precedence and
defaults.
The action supports GitHub OIDC, named profiles, Bedrock bearer tokens, and the standard AWS access-key variables. OIDC is the expected GitHub-hosted runner configuration. Provider credentials are only appropriate for trusted same-repository runs.
Review result
The default asks the coordinator to publish one COMMENT pull request review.
When no issues are found, the coordinator still publishes a concise no-issues
review. Harbourmaster then verifies that a new marked review was submitted for
the exact reviewed SHA. OpenCode logfmt diagnostics are streamed to the job log.
Its raw JSON event stream is captured unchanged in the
harbourmaster-opencode-<run-id>-<run-attempt> artifact as
harbourmaster-opencode-events.jsonl; it is not used as a publication payload.
The artifact is uploaded even when the reviewer fails and is retained for
artifact_retention_days.
The action never approves or requests changes on a pull request and does not replace normal CI checks.