cmd ci

nself ci

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

Synopsis

nself ci [repo-root] [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.

In v1.5 (NSELF_V15=1)

nself ci is the free ci plugin. The first run installs it, prints one warning, and runs it. The CI fabric guides (getting started, architecture, configuration and policy, evidence and machine output, migration, troubleshooting, reference) live with the plugin (published with the CI fabric release): plugins .github/wiki/guides/ci/.

nself ci eval is now nself eval, from the nself-eval-gate plugin. The old spelling still runs it, auto-adds the plugin the first time, and prints a deprecation line. With NSELF_NO_AUTO_ADD=1 and the plugin missing, it fails with E404 and tells you to run nself add nself-eval-gate.

nself doctor --deep no longer runs CI-VAULT-SYNC-01 in v1.5. That check read the operator's private secret store, so product code must not depend on it. CI-TOKEN-01 still runs. v1.4 is unchanged.

Flags

Name	Shorthand	Type	Default	Env	Escalates to	JSON override	Description
--check		bool	false				Run gates only; do not post a GitHub commit status
--filesystem		bool	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		bool	false				Skip the gitleaks secret scan
--no-status		bool	false				Alias for --check
--owner		string	""				GitHub owner (default: from git remote)
--repo		string	""				GitHub repo name (default: from git remote)
--sha		string	""				Commit SHA to report on (default: HEAD)
--verbose	-v	bool	false				Print each gate command before running
--help	-h	bool	false				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)

Contract

• Side effect: remote
• Output: document
• JSON: none
• Exit codes: none declared

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 →