Reference

CI reference

Every table on this page is read from the code of free/ci. Change the code, then regenerate the page. For the flags of one command, run nself ci <command> --help.

Commands

nself ci runs the plugin binary nself-ci. A v1.4 command runs without NSELF_V15; a v1.5 command needs NSELF_V15=1. Hidden commands are reachable but left out of --help.

Command	Surface	Side effect	Summary
nself ci	v1.4, v1.5	remote	Run the nself-ci gate suite and post a GitHub commit status
nself ci artifacts	v1.5	read	List, show, fetch and prune stored run artifacts
nself ci artifacts get	v1.5	-	-
nself ci artifacts key	v1.5	-	-
nself ci artifacts list	v1.5	-	-
nself ci artifacts prune	v1.5	-	-
nself ci artifacts release	v1.5	-	-
nself ci artifacts show	v1.5	-	-
nself ci artifacts sign	v1.5	-	-
nself ci artifacts signer	v1.5	-	-
nself ci artifacts tools	v1.5	-	-
nself ci artifacts verify	v1.5	-	-
nself ci build	v1.4, v1.5 (hidden)	remote	Build a signed release artifact locally (Android only)
nself ci config ignore add	v1.5	write	Append a reviewed fingerprint to .gitleaksignore (--reason required)
nself ci config migrate	v1.5	write	Migrate .nself/ci.yaml to the current schema (--write applies)
nself ci config show	v1.5	read	Show the resolved CI configuration
nself ci doctor	v1.5	read	Check the CI environment, nodes and providers (--selftest [--alert] for an unattended host)
nself ci evidence	v1.5	read	Show the evidence document of a revision
nself ci evidence verify	v1.5	read	Verify the evidence of a revision against the policy
nself ci explain	v1.5	read	Explain why a job was or was not planned
nself ci forgejo	v1.4, v1.5	read	Show Forgejo server health (ops profile)
nself ci logs	v1.5	read	Print the logs of a run attempt (-f follows)
nself ci netproxy	v1.5 (hidden)	remote	Internal egress proxy used by restricted jobs
nself ci nodes add	v1.5	remote	Add and provision a CI node
nself ci nodes discover	v1.5	read	Discover nodes on the local network
nself ci nodes drain	v1.5	remote	Stop placing new jobs on a node
nself ci nodes enable	v1.5	remote	Place jobs on a node again
nself ci nodes forget-project	v1.5	destructive	Forget a project's node records on this host (local, audited)
nself ci nodes label	v1.5	write	Set or remove node labels (key=value)
nself ci nodes list	v1.5	read	List nodes
nself ci nodes pair	v1.5	remote	Pair an agent node (foreground enrollment listener)
nself ci nodes pools explain	v1.5	read	Explain a project's effective pool set and every excluded runner
nself ci nodes pools list	v1.5	read	List runner pools and whether the project may use them
nself ci nodes pools show	v1.5	read	Show one runner pool
nself ci nodes projects add	v1.5	write	Authorize projects on a node
nself ci nodes projects list	v1.5	read	List the projects a node is authorized for
nself ci nodes projects remove	v1.5	write	Remove project authorizations from a node
nself ci nodes provision	v1.4	remote	Install runner dependencies, user, sudoers, and N runner instances
nself ci nodes remove	v1.5	destructive	Remove a node and its registration
nself ci nodes revoke	v1.5	destructive	Revoke a node credential
nself ci nodes rotate	v1.5	remote	Rotate a node host key, certificate or node key
nself ci nodes secrets grant	v1.5	remote	Grant a node access to a secret class
nself ci nodes secrets revoke	v1.5	remote	Revoke a node access to a secret class
nself ci nodes set	v1.5	remote	Set contention and persistence policy of a node
nself ci nodes show	v1.5	read	Show one node
nself ci nodes status	v1.5	read	Show readiness, watcher, queue and last results of every node
nself ci nodes sync	v1.5	write	Import an inventory/v1 file or command output over the node registry
nself ci nodes test	v1.5	remote	Probe a node and report its capabilities
nself ci nodes upgrade	v1.5	remote	Upgrade node agents
nself ci nodes verify	v1.4	read	Check host(s) against the dependency manifest and report drift
nself ci plan	v1.5	read	Plan a run without executing it
nself ci policy pin	v1.5	write	Pin or clear the trusted revision
nself ci policy protect	v1.5	remote	Show or apply branch protection that requires the nself-ci check
nself ci policy set	v1.5	write	Set an operator policy key
nself ci policy show	v1.5	read	Show the operator policy
nself ci policy unset	v1.5	write	Unset an operator policy key
nself ci policy usage	v1.5	read	Show spend and usage against the policy
nself ci providers	v1.5	read	Provider command group help
nself ci providers authorize	v1.5	remote	Authorize a project for hosted runners
nself ci providers github init	v1.5	write	Render the GitHub dispatch workflow
nself ci providers gitlab init	v1.5	write	Render the GitLab dispatch pipeline
nself ci providers list	v1.5	read	List providers
nself ci providers revoke	v1.5	destructive	Revoke a project authorization for hosted runners
nself ci providers show	v1.5	read	Show one provider
nself ci providers test	v1.5	remote	Probe a provider
nself ci providers usage import	v1.5	write	Import provider usage records
nself ci run	v1.4	remote	Discover .ci.yaml manifests and run their stages (pipeline)
nself ci runs	v1.5	read	Show a run, or the flaky checks (--flaky)
nself ci runs approve	v1.5	remote	Approve a run that waits for approval
nself ci runs cancel	v1.5	remote	Cancel a run
nself ci runs decisions	v1.5	read	Show the scheduling decisions of a run
nself ci runs follow	v1.5	read	Follow the events of a run as an NDJSON stream
nself ci runs list	v1.5	read	List recent runs
nself ci runs outbox	v1.5	read	Show queued status and event deliveries
nself ci runs pending	v1.5	read	List runs waiting for approval
nself ci runs prune	v1.5	destructive	Remove old runs and logs (--dry-run previews; --tidy [--apply] also tidies cache and job roots)
nself ci runs queue	v1.5	read	Show the run queue
nself ci runs reproduce	v1.5	remote	Reproduce a job at its recorded inputs
nself ci runs rerun	v1.5	remote	Run a recorded revision again on a chosen target
nself ci runs resolve	v1.5	write	Resolve a pending run decision
nself ci runs stats	v1.5	read	Show run statistics
nself ci runs wait	v1.5	read	Wait for a run to finish and print its result
nself ci serve	v1.4, v1.5	write	Start the nself-ci webhook listener daemon (port 3845)
nself ci serve admin	v1.5	read	Coordinator admin group help
nself ci serve admin audit	v1.5	read	Read or verify the audit log
nself ci serve admin audit checkpoint	v1.5	write	Write a signed audit checkpoint
nself ci serve admin cert	v1.5	write	Issue a user mTLS certificate (printed once)
nself ci serve admin roles	v1.5	destructive	Grant, revoke or list roles
nself ci serve admin token	v1.5	destructive	Issue, revoke or list scoped user tokens
nself ci serve backup	v1.5	read	Back up the coordinator data directory
nself ci serve install	v1.5	write	Install the watcher service and hourly selftest
nself ci serve restore	v1.5	destructive	Restore the coordinator data directory from a backup
nself ci serve uninstall	v1.5	destructive	Remove unchanged watcher service files
nself ci serve watch	v1.5	remote	Keep commit CI current by polling, without an inbound port

Flags

A flag is read from the source file that defines it. verb * means the flag is shared by the file that registers several sub-verbs of that verb, so it is not proven for every one of them. Run nself ci <command> --help for the exact set.

Flag	Commands
--accepts	nodes *
--addr	serve
--agent-addr	serve *
--agent-binary	nodes *
--agent-source	providers github init
--agent-url	nodes pair
--alert	doctor
--all	nodes *
--allow-deploy-host	nodes *
--allow-downgrade	nodes *
--allow-private	providers *
--allow-unsandboxed	serve
--allowed-repos	serve
--api-addr	serve *
--api-lock	serve *
--api-public-url	serve *
--api-socket	serve *
--api-submit-role	serve *
--app-id	policy protect
--apply	runs *
--artifact	build
--at-revision	evidence *
--attempt	artifacts *, logs
--audit	policy protect
--base	explain, plan
--binary	serve *
--branch	policy protect
--by	config ignore add
--cert	nodes *
--cert-ttl	nodes pair
--check	providers *, runs reproduce
--class	nodes *
--clear	policy *
--cmd	nodes sync
--concurrency	serve
--config	config *, explain, plan
--confirm-flaky	runs *
--container	-
--coordinator	artifacts *, nodes *, runs *
--coordinator-id	nodes pair
--data-dir	nodes pair, serve *
--dest	artifacts *
--detach	-
--dir	providers *
--drain-deadline	serve *
--dry-run	artifacts *, nodes sync, policy protect, runs *, serve *
--effective	policy *
--enroll-addr	nodes pair, serve *
--env	run
--env-file	serve *
--f	logs
--file	evidence *
--filesystem	-
--flaky	runs *
--force	serve
--from	nodes sync
--from-seq	runs follow
--gateway	run
--h	-
--help	-
--home	config *
--hook	policy protect
--host-key	nodes *
--image	-
--in	serve *
--init	artifacts signer
--inputs	providers gitlab init
--insecure	serve
--installer	nodes *
--interactive	nodes *
--interval	serve watch
--isolation	-
--job	runs rerun
--json	artifacts *, config *, doctor, evidence *, explain, forgejo, logs, nodes *, plan, policy *, providers *, runs *, serve *
--keep	runs *
--kek	serve *
--key-id	nodes *
--keys	artifacts verify
--kind	artifacts *
--label	nodes pair
--launchd	serve *
--limit	runs *
--local	nodes status
--max-age-days	runs *
--max-log-bytes	runs *
--max-queue	-
--mode	nodes *
--name	artifacts *, nodes *
--network	-
--no-gitleaks	-
--no-status	config *
--node-admin-routes	serve *
--node-key	nodes *
--nodes	doctor
--older-than	artifacts *
--on-battery	nodes *
--once	serve watch
--out	artifacts *, serve *
--owner	build
--ownership	nodes *
--persistence	nodes *
--pipeline	evidence *, explain, plan
--policy	evidence *
--post-status	-
--prefer	-
--privacy-zone	nodes *
--probe	netproxy
--project	artifacts *, nodes *, providers *, runs *, serve admin roles
--providers	doctor
--proxy	netproxy
--pubkey	serve admin audit checkpoint
--public	artifacts signer
--public-url	nodes pair, serve *
--reason	config ignore add
--release	artifacts *
--release-routes	serve *
--remove	nodes label
--repo	artifacts verify, build, config *, doctor, evidence *, explain, plan, policy *, providers *, runs *, serve *
--repos	serve watch
--reserve-cpu	nodes *
--reserve-mem	nodes *
--restore	policy protect
--role	serve admin roles
--rotate	artifacts signer
--run	artifacts *, logs, runs reproduce
--runner	-
--scope	policy *
--secret	serve
--secret-classes	nodes *
--self	serve *
--selftest	doctor
--service	-
--sha	runs *
--shell	runs reproduce
--since	serve admin audit
--slots	nodes *
--spend	runs *
--stdio	artifacts signer
--stdout	providers *
--stream	evidence *
--system	nodes *, serve *
--systemd	serve *
--tag	build
--team	policy *, serve *
--timeout	build, config *, nodes discover, run, runs wait, serve
--trigger	explain, plan
--trust	-
--ttl	serve *
--untrusted-dir	providers gitlab init
--upload	build
--url	forgejo
--user	serve *
--v	build, run, serve
--verbose	build, serve
--verify	serve admin audit
--version	nodes *
--where	-
--workdir	serve
--write	config *
--yes	artifacts key

Exit codes

Command	Outcome	Exit
ci	pass	0
ci	required check failed	1
ci	usage error	1
ci	infrastructure	2
ci	authorization	3
ci evidence verify	current bound pass	0
ci evidence verify	evidence fails	1
ci evidence verify	stale	10
ci evidence verify	invalid	11
ci evidence verify	unbound	12
ci evidence --pipeline	none overdue	0
ci evidence --pipeline	overdue	10
ci doctor	clean	0
ci doctor	check failed	10
ci doctor	warnings only	12

Error codes

Errors print as E<number>: <message>. The class says who fixes it: usage and code are yours, infra is the machine or the network.

Code	Class	Summary	Fix	Package
E600	infra	nself CLI is too old	Run nself update	internal/model
E601	usage	document is invalid against its schema	Fix the document and retry	internal/model
E602	usage	unsupported contract version	Use a supported contract version	internal/model
E603	infra	V15 engine not built yet	Install a newer nself-ci plugin	internal/model
E604	usage	illegal state transition	Use a legal state transition	internal/store
E605	infra	state changed concurrently	Refresh attempt state and retry	internal/store
E606	infra	database needs a newer reader	Upgrade nself-ci before opening this database	internal/store
E607	infra	store operation failed	Check local disk and retry	internal/store
E608	usage	idempotency key already used	Use the original attempt or a new key	internal/store
E609	usage	operator action required	Record an operator decision before proceeding	internal/store
E610	infra	local process execution unavailable	Use a supported local host	internal/exec
E611	infra	requested isolation unavailable	Choose process or baseline container isolation	internal/exec
E612	infra	job preparation failed	Check workspace and secret source	internal/exec
E613	infra	local container execution failed	Check Docker and the selected image	internal/exec
E614	infra	required check tool is unavailable	Install the named tool and retry	internal/gates
E615	code	check configuration or threshold is invalid	Correct the check configuration and retry	internal/gates
E616	usage	job dependencies form a cycle or name a job that does not exist	Remove the cycle or define the missing job in .nself/ci.yaml	internal/plan
E617	usage	a required job depends on an allow_failure job	Make the dependency required or the dependant optional	internal/plan
E618	infra	no runner can run this job	Install the missing tool or Docker, register a runner, or relax the job requirements	internal/plan
E619	usage	unknown pipeline, job or fail-fast scope	Use a name defined under pipelines or jobs in .nself/ci.yaml	internal/plan
E620	usage	.nself/ci.yaml is invalid or risky	Fix the named key at the reported file:line and retry	internal/config
E621	usage	a legacy .ci.yaml is present under V15	Run nself ci config migrate --write, then delete the old file	internal/config
E622	usage	a legacy .ci.yaml field cannot become a job	Remove or hand-convert the named field	internal/config
E623	usage	.nself/ci.yaml is git-ignored	Add .nself/* and !.nself/ci.yaml to .gitignore	internal/config
E624	usage	--sha is not supported in V15	Run nself ci evidence verify <rev> to check a revision	internal/run
E625	usage	--trust needs a registered trust classifier	Run without --trust, or install the trust component	internal/run
E626	usage	unknown or unusable run	List runs with nself ci runs and use a run id from the list	internal/run
E627	usage	run option not available	Check nself ci --help for the options this build supports	internal/run
E628	usage	evidence revision must be a full commit sha	Pass the 40 or 64 hex digits of the commit, for example $(git rev-parse HEAD)	internal/evidence
E629	usage	evidence document rejected	Run nself ci evidence verify <rev> on a clean checkout to produce fresh evidence	internal/evidence
E630	infra	evidence worktree or git facts unavailable	Check that git works in the repository and that the temporary directory is writable	internal/evidence
E631	usage	no evidence for that run or revision	List runs with nself ci runs, or run nself ci evidence verify <rev>	internal/evidence
E632	infra	stored job log unusable	Check that the CI state directory is writable and not full; nself ci runs prune frees space	internal/logs
E633	usage	no stored logs for that job or attempt	List runs with nself ci runs list; logs are kept per attempt until retention removes them	internal/logs
E634	usage	recorded platform differs from this host	Reproduce the job on a host of the recorded platform, or read the stored evidence with nself ci evidence <run>	internal/reproduce
E635	usage	the original run was not bound to its commit; only the recorded revision is reproduced	Commit the changes and run the job again to get bound evidence	internal/reproduce
E636	infra	service provisioning or teardown failed	Re-run the job; list leftovers with docker compose ls --all and remove any nselfci- project	internal/services
E637	infra	Docker is required for service dependencies	Start Docker (or Colima) and re-run, or run a job that declares no services	internal/services
E638	infra	the nself CLI does not offer the service commands	Run nself update	internal/services
E639	usage	unknown service or component	List the valid names with nself config services list --json	internal/services
E640	usage	a drill is invalid	Make the drill print one valid ci.evidence/v1 document on stdout (or none), and keep drills_dir entries to plain directories with an executable run	internal/drill
E641	usage	a drill job is overdue	Run the scheduled pipeline (nself-ci --pipeline <name>) and check why the schedule stopped	internal/drill
E642	usage	a pre-push hook already exists	Call the printed nself ci evidence verify line from your existing pre-push hook; nothing was overwritten	internal/protect
E643	usage	branch protection is not available for this repository	Use the pre-push hook (nself ci policy protect --hook) and the auditor (--audit <days>) instead	internal/protect
E644	code	truth rule file is invalid or unreadable	Correct the key named in the message in the rule file and retry	internal/gates/truth
E645	usage	the pinned toolchain image is not available	Pass --image ref@digest (set NSELF_CI_IMAGE=ref@digest until the flag exists), or run without --container; the first publish of the pinned image is a separate owner-named action	internal/toolchain
E646	infra	no isolation is available for the ad-hoc job	Start Docker (or Podman) to run the job in a container, or pass --isolation process to run it on this host with host networking	internal/adhoc
E647	infra	the trust class needs an isolation level this host cannot provide	Run the job on a host with the sandboxed-container level (gVisor), or drop --trust untrusted if the command is your own	internal/adhoc
E648	infra	detached run did not start (reason spawn, no_queued_event or child_exit)	Run the same command without --detach to see the error, then retry	internal/detach
E650	usage	node not found	List nodes and use a registered id	internal/nodes/registry
E651	usage	invalid node document or version	Refresh the capability and retry	internal/nodes/registry
E652	usage	runner protocol version incompatible	Upgrade the agent to min_agent_version	internal/protocol
E653	infra	runner protocol message invalid	Check the carrier and agent protocol stream	internal/protocol
E654	infra	node slots full	Wait for a running job to finish or raise the agent's slot count	internal/agent/slots
E655	usage	node host key unknown or changed	Verify the node, then run nself ci nodes rotate <node> --host-key SHA256:<fingerprint> (or nself ci nodes add for a new node)	internal/transport/ssh
E656	infra	ssh transport failure	Check that the node is reachable and the agent is installed (nself ci nodes test <node>); the attempt is retried if it is retryable	internal/transport/ssh
E657	usage	node revoked or not authorized for the project	Run nself ci nodes show ; add the node again or ask an admin to recover it	internal/nodes/lifecycle
E658	usage	invalid node label	Use lowercase keys, plain short values, at most 32 labels and no nself. prefix	internal/nodes/labels
E659	usage	pairing code invalid	Start a new pairing window with nself ci nodes pair and use the code it prints	internal/pairing
E660	usage	certificate invalid	Re-pair the node (nself ci nodes pair), check the clock, or issue a new certificate	internal/pki
E661	usage	job token rejected	The agent must present the token of its own lease from the session and certificate that first used it; restart the job if the token expired or the attempt ended	internal/transport/agent
E662	infra	stale lease epoch	Stop the job and clean its workspace before retrying	internal/lease
E663	usage	host is a deploy host and is CI-ineligible	Run CI on another machine; only an admin may pass --allow-deploy-host after confirming	internal/nodes/deployguard
E664	usage	coordinator user API refused the request or could not be used (reason key names why: node_kind, no_credential, token_*, role, project, server_identity, transport, ...)	Use a user certificate or a scoped token that holds the needed role for the project (nself ci serve admin roles list), and pin the coordinator root (ci.coordinator_ca)	internal/coordinator/clientapi
E665	auth	agent artifact verification failed (reason keys no_trusted_key, missing_signature, unknown_key, wrong_purpose, revoked, bad_signature, version_mismatch, target_mismatch, checksum_mismatch, provenance)	Install the agent from a signed release of the pinned version, or pass --agent-binary with a binary you trust	internal/agent/verify
E666	usage	agent upgrade refused (protocol ceiling, downgrade or running job)	Run nself ci nodes show ; wait for the job, pass --allow-downgrade, or upgrade the coordinator first	internal/agent/update
E667	usage	LAN discovery is disabled	Unset NSELF_CI_DISCOVERY=0 and remove ci.discovery: off from the user config.yaml to use discovery, or pair by address with nself ci nodes pair	internal/discovery
E668	infra	coordinator backup or restore refused	Check the reason: pass the KEK of the coordinator that made the backup (--kek), stop the coordinator before serve restore, or take a new backup	internal/coordinator/backup
E669	infra	node bootstrap or pinned runner download failed	Read the reason key in the message: no_root needs root or passwordless sudo for the ssh user; checksum means the downloaded runner does not match its pin	internal/nodes/bootstrap
E670	usage	policy scope loosens a parent	Tighten the lower scope or edit the operator policy	internal/trust
E671	usage	revision or branch policy field ignored	Move spend authorization to operator policy or tighten the revision	internal/trust
E672	usage	invalid policy key or value	Use a registered key with a valid value	internal/trust
E673	usage	value below the redaction minimum length	Register values of at least 6 bytes; shorter values cannot be masked	internal/redact
E674	usage	invalid secret reference or environment-name collision	Write refs as project/NAME, team/NAME, release/NAME, environment//NAME or deploy//NAME, and give each NAME once	internal/secrets
E675	infra	secret resolver unavailable	Install an nself CLI that has nself config secrets resolve, or remove the secrets from the job	internal/secrets
E676	infra	secret resolution failed	Check that the ref exists in the store file and that this node's age identity was granted the file; the attempt did not start	internal/secrets
E677	usage	secret class or node not eligible	Run the job on a node and trust class the policy allows for this secret class, or grant the node (nself ci nodes secrets grant) if it is eligible	internal/secrets
E678	infra	requested isolation level unavailable on this runner	Install or enable the runtime for the level, or run the job on a runner that has it	internal/isolation
E679	infra	network scope cannot be enforced by this isolation profile	Use the none or lan scope, or install the network scope profile	internal/isolation
E680	usage	value above the redaction maximum length	Register values of at most 128 KiB; a longer value cannot be found reliably in a scanned stream	internal/redact
E681	infra	workspace leak detected or cleanup incomplete; node drained	Run nself ci doctor, remove the reported leftovers, then undrain the node	internal/hygiene
E682	infra	no job UID is provisioned for this separation	Re-run nself ci nodes add --system, or enable unprivileged user namespaces for the agent user	internal/hygiene
E683	usage	artifact path rejected	Pack only regular files, directories and in-tree relative symlinks, or choose an empty destination outside .git	internal/authz
E684	usage	cache write denied	A cache is written only by a passing attempt in finalizing, into its own namespace, with the current epoch	internal/authz
E685	usage	evidence rejected	Run the gate again on the exact revision with a clean worktree, or fix the reason named in the error	internal/attest
E686	usage	evidence signature invalid, key unknown or signature replayed	Run the job again on a registered node whose evidence key is not revoked, or fix the reason named in the error	internal/attest
E687	usage	not authorized	Use an identity that holds the needed role (nself ci serve admin roles list), or ask an admin to grant it	internal/roles
E688	usage	run approval missing, void or refused	Ask a release or admin user other than the author to run nself ci runs approve <run> for the current head	internal/trust/source
E689	usage	placement refused at the production boundary	Run the job on a node that is not a deploy host, or on a deploy host the operator overrode with owner or internal work, isolation vm or stronger and no release or deploy secrets; a coordinator host needs vm for team mode and for collaborator or untrusted work	internal/trust
E690	usage	matrix entry is outside pipeline support	Declare the platform in support or remove the matrix entry	internal/sched
E691	usage	scheduling policy value is invalid	Use a registered sched key with a valid value: a positive whole number, a duration such as 10m, or a listed name	internal/schedpolicy
E692	usage	explain target not found or no decision record	Name a job of the current plan, or run nself ci runs decisions to list recorded placement decisions	internal/planview
E693	usage	job waited past max_queue	Raise --max-queue or free capacity, then run again	internal/dispatch
E694	usage	the project's job queue is full	Wait for queued jobs to finish (the error carries the expected wait), cancel runs you no longer need, or raise sched.queue.max_depth	internal/fairq
E695	usage	spend refused: no budget, paid placement disabled, or approval required	Set economics.paid_enabled and a day or month budget, raise the budget, or approve the spend with nself ci runs approve <run> --spend	internal/economics
E696	usage	burst provisioning refused or failed: cap, breaker, budget or provider error	Read the reason in nself ci explain; raise burst.max_concurrent, wait for the breaker to close, or fix the provider	internal/burst
E697	internal	burst teardown failed; it is alerted once and retried at every sweep until the resource is gone	Check the provider API and credentials; the sweeper keeps retrying and new provisioning on that provider stays blocked until the resource is gone	internal/burst
E698	infra	the ephemeral provider is unavailable: missing tool, adapter, token file or agent artifact	Install a container runtime (Linux) or Tart (Apple silicon), or read the reason in nself ci doctor; no slot is offered below container isolation	internal/providers/ephemeral/local
E699	infra	world snapshot unavailable	Check the store and contributor registrations	internal/world
E700	config	provider not configured or credential missing	Configure the provider and credential	internal/providers
E701	auth	credential lacks scope or permission	Grant the named permission	internal/providers
E702	config	provider rejected a misconfigured request	Correct the repository, workflow, ref or project	internal/providers
E703	quota	provider rate limited or quota exhausted	Retry after the indicated time	internal/providers
E704	transient	provider unavailable	Retry after recovery	internal/providers
E705	config	hosted evidence rejected	Inspect evidence binding	internal/providers
E706	auth	trigger rejected	Check signature, token, timestamp and source	internal/providers
E707	config	runner registration or teardown failed	Inspect runner registration	internal/providers
E708	config	job cannot be dispatched to provider	Reduce or change the job request	internal/providers
E709	config	usage import unavailable	Check billing access and endpoint	internal/providers
E710	infra	blob integrity failure	Discard the corrupt blob and retry transfer	internal/blob/cas
E711	usage	cache write refused	A cache entry is saved only by a passing attempt in finalizing, with the current epoch, into its own namespace and a planned key	internal/cache/entries
E712	infra	artifact commit refused	Declare outputs that exist inside the job workdir, stay under the size caps and the disk floor and hold no registered secret; nself ci artifacts prune frees space	internal/artifacts/records
E713	usage	artifact not found	Check the id with nself ci artifacts list; an artifact you may not see reads as not found	internal/artifacts/records
E714	infra	blob transfer failed	A remote attempt could not hand its artifact to the coordinator (stale lease, digest mismatch, interruption, protocol fault or size cap); run the job again, and raise NSELF_CI_ARTIFACT_MAX_FILE or free store space for a size_cap	internal/blob/transfer
E715	usage	release job not admitted	Run the release job's dependencies again on a clean, committed tree, then retry the release	internal/release/job
E716	usage	operator resolution refused	Use the attempt id from nself ci runs <run> and the NSELF_CI_IDEMPOTENCY_KEY the release job received (its publish step logs it), then run nself ci runs resolve again	internal/release/job
E717	infra	release signing failed	Run nself ci artifacts key init once to create the release key, make sure every attempt of the run is finished, and release only digests that are committed records of the run	internal/signing
E718	infra	SBOM failed	Run nself ci artifacts tools install to place the pinned syft, then retry; an invalid SBOM means syft's output failed the structural check, so rerun with the pinned version	internal/sbom
E719	usage	release verification failed	Read the reason key in the output; fetch the release again, or run nself ci artifacts verify <dir> --json for every check	internal/release/verify
E793	usage	runner inventory refused	Give a file or a command that prints one inventory/v1 document under 1 MiB within 10 seconds; run sync on the machine that owns the nodes, not on a TEAM coordinator	internal/nodes/inventory
E797	usage	--where value is unknown or not available	Use local, a node id, a pool id, hosted, auto or all (all needs a race hook); list targets with nself ci nodes pools list	internal/where
E799	infra	another watcher holds this host's run lock	Wait for the other watcher or stop it, then retry	internal/readiness
E800	infra	readiness.cmd gave no usable answer	Make the hook exit 0 (ready) or 3 (not ready, reason on its first output line) within 5 seconds; it runs with PATH and LANG only, so use absolute paths	internal/readiness
E804	usage	a watch.* setting is invalid	Fix the operator value (nself ci policy show names the key) and restart the watcher	internal/watch
E805	quota	the GitHub quota stopped the watch pass	Nothing to do: the watcher makes no request before the recorded reset time; raise providers.github.poll_interval if it recurs	internal/watch
E807	usage	a tracked file is secret-shaped or over the size cap	Untrack the file, or run the gate on a clean checkout	internal/offload
E809	policy	not_a_record_pool	Run commit CI on a pool listed in pools.record	internal/pools/record
E812	code	a .gitleaksignore entry has no review comment	Put # Reviewed YYYY-MM-DD [by <who>]: <reason> on the line before each entry, or add entries with nself ci config ignore add <fingerprint> --reason <text>	internal/gates
E813	infra	a notification sink did not take the message	Delivery counts are kept per sink (nself ci doctor --selftest shows them, P7-AUTO-20); a webhook needs https and a public address (notify.allow_private for a LAN one); a command sink must exit 0 within 10 seconds	internal/notify
E816	infra	the GitHub App check run was not published (the status was)	The commit status is the result of record and was posted; only the optional nself-ci/gates check run failed. Check providers.github.app.id, providers.github.app.installation_id and the PEM in the variable named by providers.github.app.key_env, and that the App has checks:write on the repository. Set the key variable only in the environment of the v1.5 runner service, never in a shell profile or a job	internal/providers/github/checks
E819	usage	per-run policy value ignored	A per-run flag can only tighten the policy (the preset is a preference); change the project or operator policy instead	internal/trust
E821	policy	skipped: needs isolated runner	A collaborator head runs only on an isolated runner; add one (the isolation section of nself ci doctor shows what this machine proved) or let the coordinator run it	internal/watch

Reason codes

A reason code says why a job was skipped, held or placed where it was. nself ci explain <job> prints the reasons of one job.

Job reasons (model.Reason)

• pipeline.excluded
• selection.no_base
• selection.full_required
• selection.affected
• when.branch
• when.paths
• when.trigger
• when.env_missing
• dep.failed
• fail_fast.cancelled
• unplaceable.platform
• unplaceable.docker
• unplaceable.tool
• unplaceable.service
• unplaceable.label
• unplaceable.resources
• admission.battery
• admission.reservation
• advisory.tool_missing
• advisory.data_offline

Typed reasons

Reason	Type	Package
evidence.adhoc	Reason	internal/attest
evidence.invalid	Reason	internal/attest
evidence.jobs_mismatch	Reason	internal/attest
evidence.not_passing	Reason	internal/attest
evidence.policy_mismatch	Reason	internal/attest
evidence.repo_mismatch	Reason	internal/attest
evidence.revision_mismatch	Reason	internal/attest
evidence.selection_partial	Reason	internal/attest
evidence.self_reported_not_admitted	Reason	internal/attest
evidence.signature_unverifiable	Reason	internal/attest
evidence.stale	Reason	internal/attest
evidence.trust_below_min	Reason	internal/attest
evidence.unbound	Reason	internal/attest
attempt_unknown	RemoteReason	internal/attest
context_mismatch	RemoteReason	internal/attest
key_malformed	RemoteReason	internal/attest
key_purpose	RemoteReason	internal/attest
key_revoked	RemoteReason	internal/attest
key_unknown	RemoteReason	internal/attest
lease_holder_mismatch	RemoteReason	internal/attest
ledger_unavailable	RemoteReason	internal/attest
node_not_eligible	RemoteReason	internal/attest
replay	RemoteReason	internal/attest
revision_mismatch	RemoteReason	internal/attest
signature_invalid	RemoteReason	internal/attest
signature_malformed	RemoteReason	internal/attest
signature_missing	RemoteReason	internal/attest
collision.duplicate	PathReason	internal/authz
collision.fold	PathReason	internal/authz
dest.cwd	PathReason	internal/authz
dest.empty	PathReason	internal/authz
dest.no_parent	PathReason	internal/authz
dest.not_dir	PathReason	internal/authz
dest.not_empty	PathReason	internal/authz
dest.symlink	PathReason	internal/authz
dest.under_git	PathReason	internal/authz
dest.unreachable	PathReason	internal/authz
entry.device	PathReason	internal/authz
entry.fifo	PathReason	internal/authz
entry.hardlink	PathReason	internal/authz
entry.irregular	PathReason	internal/authz
entry.setid	PathReason	internal/authz
entry.socket	PathReason	internal/authz
link.absolute	PathReason	internal/authz
link.empty	PathReason	internal/authz
link.escape	PathReason	internal/authz
link.invalid	PathReason	internal/authz
path.absolute	PathReason	internal/authz
path.backslash	PathReason	internal/authz
path.control	PathReason	internal/authz
path.dot_git	PathReason	internal/authz
path.dots	PathReason	internal/authz
path.drive	PathReason	internal/authz
path.empty	PathReason	internal/authz
path.empty_component	PathReason	internal/authz
path.parent_not_dir	PathReason	internal/authz
path.through_symlink	PathReason	internal/authz
path.too_deep	PathReason	internal/authz
path.too_long	PathReason	internal/authz
path.trailing_slash	PathReason	internal/authz
path.traversal	PathReason	internal/authz
path.unicode_with_symlink	PathReason	internal/authz
path.utf8	PathReason	internal/authz
size.entries	PathReason	internal/authz
size.file	PathReason	internal/authz
size.negative	PathReason	internal/authz
size.ratio	PathReason	internal/authz
size.total	PathReason	internal/authz
cache.attempt_state	Reason	internal/authz
cache.capability	Reason	internal/authz
cache.epoch	Reason	internal/authz
cache.mode	Reason	internal/authz
cache.namespace	Reason	internal/authz
cache.result	Reason	internal/authz
allowance.below_margin	PlacementReason	internal/model
allowance.unknown	PlacementReason	internal/model
approval.pending	PlacementReason	internal/model
approval.required	PlacementReason	internal/model
background.contention	PlacementReason	internal/model
background.interactive_queued	PlacementReason	internal/model
backpressure.queue_full	PlacementReason	internal/model
budget.exceeded	PlacementReason	internal/model
budget.unset	PlacementReason	internal/model
burst.team_only	PlacementReason	internal/model
capacity.busy	PlacementReason	internal/model
cost.unbounded	PlacementReason	internal/model
cost.unknown_rate	PlacementReason	internal/model
ephemeral.used	PlacementReason	internal/model
labels.mismatch	PlacementReason	internal/model
limit.global	PlacementReason	internal/model
limit.job	PlacementReason	internal/model
limit.pipeline	PlacementReason	internal/model
limit.project	PlacementReason	internal/model
limit.provider	PlacementReason	internal/model
limit.runner	PlacementReason	internal/model
limit.team	PlacementReason	internal/model
limit.user	PlacementReason	internal/model
node.deploy_host	PlacementReason	internal/model
node.discovered	PlacementReason	internal/model
node.draining	PlacementReason	internal/model
node.interactive	PlacementReason	internal/model
node.maintenance	PlacementReason	internal/model
node.not_ready	PlacementReason	internal/model
node.offline	PlacementReason	internal/model
node.on_battery	PlacementReason	internal/model
node.protocol	PlacementReason	internal/model
node.reservation	PlacementReason	internal/model
node.revoked	PlacementReason	internal/model
override.excluded	PlacementReason	internal/model
override.max_cost	PlacementReason	internal/model
override.max_queue	PlacementReason	internal/model
override.min_isolation	PlacementReason	internal/model
paid.disabled	PlacementReason	internal/model
platform.mismatch	PlacementReason	internal/model
platform.none_available	PlacementReason	internal/model
pool.excluded	PlacementReason	internal/model
provider.down	PlacementReason	internal/model
provider.owned_elsewhere	PlacementReason	internal/model
queue.timeout	PlacementReason	internal/model
resources.insufficient	PlacementReason	internal/model
retry.anti_affinity	PlacementReason	internal/model
runner.remote_only	PlacementReason	internal/model
tier.waiting	PlacementReason	internal/model
tools.missing	PlacementReason	internal/model
cleanup_failed	Reason	internal/netscope
deploy_exclusion	Reason	internal/netscope
dial_failed	Reason	internal/netscope
events_dropped	Reason	internal/netscope
host_address	Reason	internal/netscope
host_not_allowed	Reason	internal/netscope
invalid_address	Reason	internal/netscope
log_unreadable	Reason	internal/netscope
on_link	Reason	internal/netscope
port_not_allowed	Reason	internal/netscope
resolve_failed	Reason	internal/netscope
scope	Reason	internal/netscope
special_purpose	Reason	internal/netscope
approval.required	Reason	internal/trust
boundary.coordinator_host	Reason	internal/trust
boundary.deploy_host	Reason	internal/trust
boundary.override_minimum	Reason	internal/trust
isolation.below_minimum	Reason	internal/trust
isolation.cotenancy	Reason	internal/trust
isolation.rootful_runtime	Reason	internal/trust
isolation.runtime_flag_denied	Reason	internal/trust
isolation.slot_uid_shared	Reason	internal/trust
isolation.uid_separation	Reason	internal/trust
isolation.unavailable	Reason	internal/trust
network.lan_for_untrusted	Reason	internal/trust
network.scope_not_offered	Reason	internal/trust
network.scope_unenforceable	Reason	internal/trust
privacy.hosted_not_authorized	Reason	internal/trust
privacy.local_only	Reason	internal/trust
privacy.provider_not_allowlisted	Reason	internal/trust
secrets.class_not_declared	Reason	internal/trust
secrets.not_in_policy	Reason	internal/trust
secrets.untrusted	Reason	internal/trust
trust.not_accepted	Reason	internal/trust
trust.release_needs_dedicated	Reason	internal/trust

Doctor checks

nself ci doctor reports each check under its id. --nodes and --providers add their sections.

Id	Name	Package
CI-D001	toolchain	internal/doctor
CI-D002	docker	internal/doctor
CI-D003	status posting	internal/doctor
CI-D004	store opens	internal/doctor
CI-D005	store version	internal/doctor
CI-D006	config valid	internal/doctor
CI-D007	no leftover .ci.yaml	internal/doctor
CI-D008	config not git-ignored	internal/doctor
CI-D090	nodes section	internal/doctor
CI-D091	providers section	internal/doctor
CI-D092	selftest section	internal/doctor
CI-D096	-	internal/doctor
CI-D097	-	internal/doctor
CI-D098	-	internal/doctor
CI-DI01	toolchain pins	internal/toolchain
CI-DI02	toolchain image	internal/toolchain
CI-DI03	toolchain version	internal/toolchain
CI-DN001	-	internal/nodes/doctor
CI-DN002	-	internal/nodes/doctor
CI-DN003	-	internal/nodes/doctor
CI-DN004	-	internal/nodes/doctor
CI-DN005	-	internal/nodes/doctor
CI-DN006	-	internal/nodes/doctor
CI-DN007	-	internal/nodes/doctor
CI-DN008	-	internal/nodes/doctor
CI-DN009	-	internal/nodes/doctor
CI-DN010	-	internal/nodes/doctor
CI-DN011	-	internal/nodes/doctor
CI-DN012	-	internal/nodes/doctor
CI-DN013	-	internal/nodes/doctor
CI-DN014	-	internal/nodes/doctor
CI-DN015	-	internal/nodes/doctor
CI-DP001	-	internal/providers/doctor
CI-DP002	-	internal/providers/doctor
CI-DP003	-	internal/providers/doctor
CI-DP004	-	internal/providers/doctor
CI-DP005	-	internal/providers/doctor
CI-DP006	-	internal/providers/doctor
CI-DP007	-	internal/providers/doctor
CI-DP008	-	internal/providers/doctor
CI-DP009	-	internal/providers/doctor
CI-DP010	-	internal/providers/doctor
CI-DP011	-	internal/providers/doctor
CI-DP012	-	internal/providers/doctor
CI-DP013	-	internal/providers/doctor
CI-DP014	-	internal/providers/doctor
CI-DS001	-	internal/selftest
CI-DS002	-	internal/selftest
CI-DS003	-	internal/selftest
CI-DS004	-	internal/selftest
CI-DS005	-	internal/selftest
CI-DS006	-	internal/selftest
CI-DS007	-	internal/selftest
CI-DS008	-	internal/selftest
CI-DS009	-	internal/selftest
CI-DT001	isolation level	internal/isolation

Pinned versions

Pin	Value
plugin version	1.2.13
requires nself	>=1.4.12

The toolchain pins, from free/ci/toolchain/versions.yaml:

Name	Kind	Version	Owner
actions-runner-image	image	ghcr.io/actions/actions-runner@sha256:4ffadc0002b2581327e06101fc8c06cd189232baf79fe561fac9caeb76f5e807	internal/providers/runnerjob
binfmt	base-image	qemu-v10.2.3	.github/workflows/ci-toolchain-image.yml
buildkit	base-image	v0.34.0	.github/workflows/ci-toolchain-image.yml
debian	base-image	trixie-slim	free/ci/toolchain
github-actions-runner	tool	2.338.0	internal/nodes/provision
gitlab-runner-image	image	docker.io/gitlab/gitlab-runner@sha256:77d03a5c881ff8f97381de4f96a66c080733eeab9c9cf502bd19916a18969113	internal/providers/gitlab/runners
gitleaks	tool	8.30.1	internal/gates
go	tool	1.27.2	internal/gates
govulncheck	tool	1.9.0	internal/gates
hadolint	tool	2.15.1	internal/gates
node	tool	24.22.0	internal/gates
pnpm	tool	12.14.0	internal/gates
python3	tool	3.13.16	internal/gates
ruff	tool	0.17.1	internal/gates
rust	tool	1.99.1	internal/gates
syft	tool	1.54.1	internal/sbom
toolchain-image	image	docker.io/nself/ci-toolchain@sha256:98f00724dbbc1b1ea03f3b1a83c057ba715ec614689e159867f94d72950c44b9	internal/toolchain
trivy	tool	0.76.0	internal/gates
uv	tool	0.13.1	internal/gates