cmd ci

nself ci

Run the nself-ci gate suite and post a GitHub commit status.

Synopsis

nself ci [repo-root] <subcommand> [flags]

Description

Run the local CI gate suite for a repository.

Detects the repo stack (Go, Node/TS, Flutter) and runs the appropriate lint, test, and build checks plus a gitleaks secret scan. Posts a "nself-ci" GitHub commit status via gh OAuth so branch protection can require nself-ci instead of billing-blocked GitHub Actions checks.

Which directory is gated

[repo-root] is resolved against the directory you run the command from, and defaults to .. Unlike the stack lifecycle commands (start, stop, status, logs, build), nself ci is not redirected into a detected backend/ sub-directory.

That distinction matters in a monorepo. nself start from the repo root deliberately retargets backend/, because that is where the stack lives. nself ci must not: the gate belongs to the whole checkout, and the manifests it looks for (package.json, pnpm-workspace.yaml, go.mod) usually sit at the repo root while backend/ holds only .env.

Before this was fixed, nself ci --check . in such a repo announced "Detected monorepo layout. Using backend as project root" and gated backend/ instead, overriding the path you passed. If you relied on that behaviour, pass the sub-directory explicitly: nself ci ./backend.

Where the gate binary comes from

The gates themselves live in a separate binary, nself-ci, built from the free ci plugin. nself ci resolves it in this order:

1. nself-ci already on PATH.
2. Plugin source next to the CLI checkout (plugins/free/ci), built on demand. This is the developer path.
3. Otherwise fetched once with go install and cached at ~/.nself/bin/nself-ci.

Step 3 is what makes the command usable from a single-file install, where no plugin source is on disk. It requires a Go toolchain and runs only once per machine. Expect it to take a couple of minutes the first time: the gate module declares a newer Go than most machines have, so Go downloads a matching toolchain before building. Progress is printed, and the fetch is bounded at 10 minutes rather than left to stall.

To skip the fetch entirely, put a pre-built nself-ci on your PATH:

git clone https://github.com/nself-org/plugins
cd plugins/free/ci && go build -o ~/.nself/bin/nself-ci ./cmd/

Until this existed, an installed CLI failed with nself-ci binary not found on PATH and expected you to clone a second repo by hand. That manual step is why nself ci could not be used as a required status check.

Flags

Flag	Default	Description
--check	false	Run gates only; do not post a GitHub commit status
--filesystem	false	Force gitleaks filesystem scan (--no-git) even inside a git checkout; opt-in for non-checkout source trees such as an exported tarball
--no-gitleaks	false	Skip the gitleaks secret scan
--no-status	false	Alias for --check
--owner	""	GitHub owner (default: from git remote)
--repo	""	GitHub repo name (default: from git remote)
--sha	""	Commit SHA to report on (default: HEAD)
--verbose, -v	false	Print each gate command before running
--help, -h	—	Show help

Subcommands

Name	Description
build	Build a signed release artifact locally (Android only)
eval	Run eval-gate suite or validate an eval-set YAML
forgejo	Show Forgejo server + runner health (ops profile)
serve	Start the nself-ci webhook listener daemon (port 3845)

Examples

nself ci                        # gate current directory, post status
  nself ci --check                # gate only, no status posted
  nself ci --no-gitleaks .        # skip secret scan
  nself ci --sha abc1234 .        # override commit SHA
  nself ci --filesystem /tmp/x    # force filesystem scan (non-checkout source, e.g. a tarball)
  nself ci /path/to/repo          # gate a specific repo

See Also

• Commands — full command index
• Core-Services — what a stack is made of

← Commands | Home →