This public repository holds the files that GitHub can apply across the
seankoji-com organization.
Repositories use these defaults when they do not define their own version:
CODE_OF_CONDUCT.mdCONTRIBUTING.mdSECURITY.mdSUPPORT.md.github/ISSUE_TEMPLATE/.github/PULL_REQUEST_TEMPLATE.md
A repository should keep a local override only when its project needs different instructions or fields. GitHub does not copy inherited files into a repository, its clones, or release archives.
The workflows under .github/workflows/ provide shared implementations for CI,
static analysis, pull-request gating, dependency automation, link checking, and
release markers. GitHub Actions workflows are not inherited automatically.
Each repository still needs a small local caller for every shared workflow it
wants to run.
Available reusable workflows include:
-
reusable-node-ci.yml -
reusable-shellspec.yml -
reusable-docker-build-push.yml -
reusable-static-analysis.yml -
reusable-agent-readiness.yml -
reusable-pr-gatekeeper.yml -
reusable-ci-result.yml -
reusable-dependabot-automerge.yml -
reusable-issue-triage.yml -
reusable-link-check.yml -
reusable-review-event.yml -
reusable-persona-recovery-request.yml -
released.yml -
Node CI accepts
pnpm,npm, oryarn. An existing.nvmrctakes precedence over thenode-versioninput. -
Docker builds require
image-name. Cache scope defaults to that image name; usecache-scopefor multiple variants. Scope must be nonempty and contain only letters, digits, dot, underscore, slash, colon,@or hyphen. -
ShellSpec uses a pinned version on a runner with zsh available; private repositories should select the
mintpool, whose runner image includes zsh. The caller's.shellspecselects the shell, for example--shell /bin/zsh. The workflow needscontents: read. -
Issue triage and release markers use
actions/github-script. Callers selecting self-hosted runners must use Actions runner v2.327.1 or newer. Issue triage needsissues: write(andpull-requests: readfor the PR-sync job).
Set the organization Actions variable PRIVATE_REPO_SELF_HOSTED to true
with repository access Private repositories before relying on omitted
runner-json inputs. Do not expose it to public repositories or create
repository-level overrides. No organization settings are changed by this repo.
Every reusable with runner-json selects runners in this order:
- A nonempty explicit
runner-jsonvalue, unchanged. - When
vars.PRIVATE_REPO_SELF_HOSTED == 'true', the workflow's labels below. - Otherwise
["ubuntu-latest"], for public callers and during provisioning.
| Workflow | Private default labels | Capability |
|---|---|---|
reusable-docker-build-push.yml |
["self-hosted","Linux","X64","has-docker"] |
Docker daemon and x64 builds |
reusable-link-check.yml |
["self-hosted","Linux","X64"] |
Linux x64 Lychee binaries |
reusable-shellspec.yml |
["self-hosted","Linux","X64","mint"] |
zsh in the runner image |
All other runner-json reusables |
["self-hosted","Linux"] |
Architecture-independent scripts or setup actions |
GitHub makes vars available in jobs.<job_id>.runs-on
and uses the caller repository's variables for reusable workflows.
This routes push, pull_request, pull_request_target, schedule, workflow_dispatch,
workflow_run and merge_group without reading github.event.repository.
The private-only access policy
keeps public callers, including public fork PRs, on hosted runners. GitHub sends
fork PR events to the base repository,
so its caller policy applies, not the head fork's visibility. Do not use this
variable as an approval boundary for untrusted code in private repos.
GitHub's Dependabot restrictions
describe tokens and secrets, but do not establish configuration-variable
availability. Verify omitted-input routing on a Dependabot-triggered run after
provisioning. If the variable is unavailable, that run falls back to hosted;
explicit self-hosted runner-json values avoid that residual. Unset variables
also leave private omissions on hosted until the operator provisions them.
Agent Readiness uses a fresh checkout directory for each job and removes it
during cleanup. When it encounters partial-clone metadata at the workspace root
from an older run, it deletes the workspace root's .git directory so the next
root checkout can start fresh. See Agent Readiness.
Persona recovery handles the CI App private key, so it never uses the shared
pool. Per-head request jobs are disabled by default to avoid hosted charges on
every PR head. Normal webhook review dispatch and the private controller's
externally monitored sweep provide recovery. Set
PERSONA_RECOVERY_REQUEST_ENABLED=true only to opt back into per-head requests;
verify the sweep and its freshness alarm before adopting this default.
This Actions configuration variable is resolved in the calling repository's
context. An organization variable applies only where that repository can access
it; a repository variable overrides it. Setting it only in this .github
repository does not enable other callers. An absent value or anything other
than the exact string true silently skips the job, without allocating a runner
or producing step logs. Set a caller override with
gh variable set PERSONA_RECOVERY_REQUEST_ENABLED --repo OWNER/REPO --body true,
or an organization value with the intended repository visibility. Inspect both
scopes when diagnosing an override.
Required persona-review and gatekeeper contexts are unchanged.
Gate summaries still warn when an exact-head review has not been dispatched;
disabling this optional request job does not suppress missing-review warnings.
When explicitly enabled, it accepts only PERSONA_RECOVERY_RUNS_ON equal to the
contracted JSON string ["self-hosted","persona-recovery"]: ephemeral,
single-use JIT runners in the persona-recovery group, restricted to
seankoji-com/.github/.github/workflows/reusable-persona-recovery-request.yml@refs/heads/main.
The group must allow all repositories, including private ones, and run no other
workloads. Its runners need bash, curl, jq, gh and the runner's bundled Node.
Repository variables override organization variables, so any unset or different
value falls back to ubuntu-latest rather than selecting the shared pool.
For example, a deployment workflow can publish the standard release marker:
jobs:
mark-released:
permissions:
deployments: write
uses: seankoji-com/.github/.github/workflows/released.yml@mainreusable-ci-result.yml checks native
job results within one workflow. It uses installed Python 3.10 or newer, makes
no API requests, checks out no code and needs no token permissions. A caller
named gatekeeper produces the required context gatekeeper / all-checks-passed.
List every retained validation job directly in both needs and expected_jobs,
including upstream jobs, rather than only the final jobs in a chain. An
intermediate job with if: always() can succeed after an upstream failure.
Use lowercase job IDs and pin the reusable to an approved immutable commit:
jobs:
# Define lint and test in THIS workflow.
gatekeeper:
needs: [lint, test]
if: always()
permissions: {}
uses: seankoji-com/.github/.github/workflows/reusable-ci-result.yml@<approved-40-hex-commit>
with:
needs_json: ${{ toJSON(needs) }}
expected_jobs: '["lint", "test"]'
runner-json: '["ubuntu-latest"]' # Public callers only; private callers omit this override.Keep the gatekeeper job ID and omit its name override. Its if: always()
is required. Every declared job must report success; failed, cancelled,
unknown or missing results fail the final job, and so does skipped unless
skippable_jobs lists the job and skip_authority confirms the skip. The
expected_jobs IDs must match the needs IDs exactly, with no empty list or
duplicates. A superseded
run whose dependencies are cancelled also fails, and can consume a final-job
runner on the old head. This is expected; cancellation must not produce a
passing gate.
The gate is only as trustworthy as the caller workflow. On pull_request
events GitHub runs the workflow from the pull request's head commit, so a pull
request that edits the caller can change expected_jobs, skippable_jobs or
the changes outputs and still turn the context green. Before relying on this
helper as a merge gate, require review of .github/workflows/ changes, for
example with CODEOWNERS and a ruleset that requires code-owner review.
| Input | Required | Default | Meaning |
|---|---|---|---|
needs_json |
yes | ${{ toJSON(needs) }} from the caller. |
|
expected_jobs |
yes | Literal JSON array of every direct dependency ID. | |
skippable_jobs |
no | '[]' |
Literal JSON array of expected_jobs IDs whose skipped result may pass when skip_authority confirms it. |
skip_authority |
when skippable_jobs is nonempty |
'' |
ID of the job that decides which checks apply. It must be in expected_jobs and not in skippable_jobs. |
runner-json |
no | '' |
Runner labels; see runner selection. |
For path-scoped checks, prefer a job-level filter: a changes job computes
which checks apply, and each filtered job runs only when its flag is set. The
changes job must expose one output per filtered job, named exactly as that
job's ID, with the value 'true' or 'false'. List the filtered jobs in
skippable_jobs, name changes as skip_authority, and list changes in
expected_jobs but not in skippable_jobs. Pin a revision that declares
skippable_jobs and skip_authority; passing them to an older pin makes the
caller workflow fail to start with an undefined-input error:
jobs:
changes:
outputs:
docs: ${{ steps.filter.outputs.docs }} # 'true' or 'false'
# Steps omitted: always runs; step `filter` sets docs.
docs:
needs: changes
if: needs.changes.outputs.docs == 'true'
# Steps omitted.
test:
# Steps omitted: always runs.
gatekeeper:
needs: [changes, docs, test]
if: always()
permissions: {}
uses: seankoji-com/.github/.github/workflows/reusable-ci-result.yml@<approved-40-hex-commit>
with:
needs_json: ${{ toJSON(needs) }}
expected_jobs: '["changes", "docs", "test"]'
skippable_jobs: '["docs"]'
skip_authority: changesA declared job's skipped result passes only when skip_authority reported
success and its output named after that job is exactly the string 'false'.
GitHub also reports skipped for a job whose upstream dependency failed or was
cancelled, so the declaration alone does not prove the skip was intended. Any
other case fails the job: the authority failed, was cancelled or skipped, or
its output is missing, 'true' or any other value. The final job reads only
those outputs, compares them with 'false' and never logs them. Every
skippable_jobs ID must appear in expected_jobs, and the list must hold
distinct lowercase IDs. A declared job that fails or is cancelled still fails
the final job. Without a changes job, return a successful explicit no-op
inside the validation job when nothing applies.
Make each filtered job depend only on changes and other jobs that always run,
and list every one of those upstream jobs in expected_jobs. The authority's
'false' confirms only that the filter did not require the job; it does not
cover a different upstream job left out of needs that also failed.
Avoid workflow-level paths or paths-ignore filters that suppress the
required producer. Do not conditionally skip the final job. Retained
validations must propagate failures, without masking them
through continue-on-error. The helper cannot detect a job omitted from both
lists, masked failures, or checks in another workflow. Move those checks into
the same dependency graph or require their contexts separately in effective rules.
toJSON(needs) includes job outputs. The helper reads only
skip_authority's output for each declared skippable job, compares it with
'false', and ignores every other output. The helper never prints outputs,
though the runner may still show step environment values in its own logs. Large
outputs can exceed the runner's environment-variable limit, roughly
128 KiB for one string on Linux, before the helper starts. Keep large data in
artifacts rather than dependency outputs.
This reusable is additive. Existing callers of reusable-pr-gatekeeper.yml
keep their behavior. Before migrating a repository, verify its complete native
producer, immutable pin and separately required persona producer/rule. Drain
legacy publishers and use a fresh head before retiring that repository's old
gatekeeper caller. Do not leave a REST evaluator or another Actions job posting
the same required CI context. Keep the legacy template for unmigrated callers,
and ensure distribution/audit knows which producer each repository uses.
The native helper alone does not prove the five-minute CI target. Measure the complete retained dependency path, runner setup and final-job execution with queues reported separately. Persona review remains a separate required gate. The existing advisory scanner runtime needs its own bounded, blocking migration.
The additive persona status action publishes a separate review context from authoritative GitHub reviews. It is inactive until a trusted controller calls an immutable revision and a verified per-repository rollout establishes its App source binding, event delivery and required-ref behavior. Adding it does not change the legacy combined gate described below.
Use the local gatekeeper caller
as the trigger and permissions reference. Its head_sha input identifies the
commit to evaluate; retain the PR seed, workflow completion and review-event
triggers when adapting it.
Pass sweep: event with that caller's per-head admission group. Each job then
evaluates only its own head, that head's merge refs and every PR sharing it.
event always requires CI registration and ignores reconcile_open. The
default, sweep: open, keeps the older behaviour: reconcile_open (default
false) decides whether to require CI registration and re-evaluate every open
PR on every event. Use event only with
per-head admission. A repo-wide admission group can replace one PR's pending
refresh with another PR's, and nothing would then re-evaluate the first PR. In
event mode the job fails before evaluation without a 40-hex head_sha.
The gate also waits for the latest Actions runs on the evaluated commit, including queued workflows that have not created job checks yet. It cannot detect a test workflow that was never triggered; keep required test callers and their trigger coverage under repository review.
The retired OpenCode greenkeeper signal is the one exception. Its reusable
workflow and callers were removed in November 2026; the exception remains so
pull-request heads that still carry a signal run from before the retirement do
not turn red. The signal checked no code, and its caller kept only the newest
signal per pull request and cancelled the rest. Runs of
.github/workflows/call-reusable-opencode-greenkeeper.yml from the events that
caller declared (pull_request_target, pull_request_review and
workflow_run) are left out of the gate, with their job check runs and any
check suite that no gated run shares. They never hold or fail the gate, in any
state. A run of that path from any other event is gated: a cancelled run
passes as superseded, any other unsuccessful conclusion blocks and it holds the
gate while running. A cancelled GitHub Actions check run named exactly
OpenCode greenkeeper signal / signal also passes.
required_workflows cannot declare those three events, so the exception cannot
hide a declared requirement.
When the Actions variable PERSONA_REVIEW_REQUIRED is true, the gate also
requires an approval from Grumpy Engineer on the current PR head. Missing,
stale, dismissed, and unreadable reviews block merging. Requested changes
remain blocking. Review execution is managed by the private control plane;
this public workflow reads only reviews in its calling repository. Submitted,
edited, and dismissed reviews trigger a read-only signal, followed by a gate
evaluation from the default branch. The private reconciler recovers missed events.
This repository is intentionally public. It must not contain credentials, secret-manager item identifiers, private service addresses, private hostnames, personal data, or incident logs. Store private operator records in the private control-plane archive instead.
Report vulnerabilities using the instructions in SECURITY.md.
With Python 3, Node.js and Bash installed and the test dependency set up
(python3 -m pip install -r requirements-test.txt), run from the repository
root:
python3 -m unittest discover -s tests -p 'test_*.py'Pinned tool versions are refreshed automatically; see docs/tool-pins.md.