# CI runners

Open Orchestra currently runs primary CI on GitHub-hosted Ubuntu runners. The
project previously targeted a Linux self-hosted runner, but the available local
runner is macOS/Sonar-focused and must not be labeled as Linux.

## Current runner policy

Primary CI jobs use `ubuntu-latest`:

- `CI / Quality gate`
- `CI / Init dogfood (ubuntu)`
- `CI / Cross-platform dogfood plan`

The Sonar workflow keeps its specialized self-hosted runner labels separately:

- `self-hosted`
- `sonar`
- `local-sonar`

Do not add a `linux` label to a macOS runner. GitHub labels are arbitrary, but
mislabeling the host can hide OS-specific failures and break Linux-only setup
steps.

## Push policy

On push and pull request runs, the default CI workflow keeps fast feedback on a
GitHub-hosted Ubuntu runner:

- `CI / Quality gate` runs on `ubuntu-latest`.
- `CI / Init dogfood (ubuntu)` runs on `ubuntu-latest`.
- Local `precommit` and `prepush` hooks only run the lightweight package
  precheck: build the package and generate the command manifest. Heavy tests
  stay in the explicit `ci:quality` gate.

macOS and Windows dogfood no longer run on every push. They run through the
nightly cross-platform path, or by manual `workflow_dispatch`.

## Nightly cross-platform dogfood

The CI workflow has a nightly schedule that first runs
`Cross-platform dogfood plan` on `ubuntu-latest`. That planning job checks
whether `main` has an unreleased package version by comparing `package.json` to
the corresponding `vX.Y.Z` tag.

If the tag is missing, nightly dogfood runs:

- `Init dogfood (macos-latest)`
- `Init dogfood (windows-latest)`

Manual `workflow_dispatch` also runs the cross-platform dogfood matrix so release
operators can request portability evidence on demand.

## Release tag policy

`Create release tag` no longer runs on every push. It runs automatically only
when release/version inputs change:

- `package.json`
- `package-lock.json`
- `.agent-workflow/releases/**`
- `.github/workflows/create-release-tag.yml`

On push, that workflow does not run the full `npm run ci:quality` gate. The CI
quality workflow owns push validation before release tagging. Manual
`workflow_dispatch` can still request `run_precommit=true` for a release
operator-controlled validation path.

## Security and operations

- Do not run secret-bearing jobs for forks, Dependabot, or untrusted PRs.
- Revisit issue #537 only when a real Linux self-hosted runner is available for
  the `self-hosted`, `linux`, `open-orchestra` label set.
- Use a dedicated runner host or isolated runner environment for future
  self-hosted CI.
- Clean any future self-hosted runner workspace between jobs according to the
  runner service policy.
- Keep release and npm publish workflows constrained because they have elevated
  permissions and secrets.
- After a merge lands, run `git pull` on the local `main` branch before creating
  or resuming feature branches. Stale base branches can miss current CI, secrets,
  release, or redaction policy.