Documentation
¶
Overview ¶
Package ci — serve.go
Purpose: HTTP webhook server for nself ci serve. Listens for GitHub push and
pull_request events, verifies HMAC-SHA256 signatures, and dispatches gate jobs to a bounded worker pool. Each job runs in an ephemeral Docker container so a runaway build cannot starve the host.
Inputs: ServeConfig (addr, secret, concurrency, workdir, timeout) Outputs: HTTP server; /healthz 200 OK; / info page; GitHub commit status per job Constraints: stdlib only (no external HTTP frameworks); Docker + gh on PATH;
graceful shutdown on SIGINT/SIGTERM; SPORT CLI-CMD-CI-SERVE-001
Package ci — serve_job.go
Purpose: Run a single CI gate job in an ephemeral Docker container.
Clones the target repo ref into a temp workdir, mounts it into a container with CPU/memory limits and a per-job timeout, runs the nself-ci binary, then posts a GitHub commit status and emits a completion event to NSELF_CI_EVENT_SINK. Container is always cleaned up — leak-free even on timeout or panic.
Inputs: ciJob, binaryPath string, ServeConfig Outputs: GitHub commit status (pending → success/failure); optional event POST Constraints: Requires Docker daemon + gh CLI on PATH; uses exec (not Docker SDK)
to keep vendor tree clean; SPORT CLI-CMD-CI-SERVE-001
Package ci — serve_webhook.go
Purpose: GitHub webhook handler: signature verification, payload parsing,
ref/SHA extraction, and async job dispatch to the worker pool.
Inputs: HTTP POST with X-Hub-Signature-256 + X-GitHub-Event headers Outputs: 202 Accepted (async dispatch) or error status; gate job enqueued Constraints: HMAC-SHA256 with shared secret; supports push + pull_request
event types; ignores deleted-branch pushes; SPORT CLI-CMD-CI-SERVE-001
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewEvalCmd ¶
NewEvalCmd creates the `nself ci eval` cobra sub-command.
func NewEvalGateCmd ¶
NewEvalGateCmd creates the `nself ci eval gate` cobra sub-command.
func RunServe ¶ added in v1.1.11
func RunServe(cfg ServeConfig) error
RunServe starts the webhook listener and blocks until SIGINT/SIGTERM.
Types ¶
type ServeConfig ¶ added in v1.1.11
type ServeConfig struct {
Addr string // listen address, e.g. ":3845"
Secret string // HMAC secret; falls back to GITHUB_WEBHOOK_SECRET env
Concurrency int // max concurrent jobs
WorkDir string // base dir for ephemeral checkouts
JobTimeout int // per-job timeout in seconds
Verbose bool
// Insecure opts out of the fail-closed "refuse to start without a
// webhook secret" default (T32). When true and no secret is configured,
// RunServe starts anyway with signature verification disabled — the
// previous, unconditional behavior. Off by default.
Insecure bool
// AllowUnsandboxed opts out of the fail-closed "refuse to run a job
// when Docker is unavailable" default (T32). When false (default) and
// Docker is not on PATH, runGateInDocker refuses the job instead of
// silently executing the cloned repo's gate commands directly on the
// host. When true, the previous runGateDirect fallback behavior
// applies.
AllowUnsandboxed bool
// AllowedRepos is the set of "owner/repo" full names this server will
// dispatch jobs for. Fail-closed by design: an EMPTY list rejects every
// job (not "allow all") — an operator who configured zero repos almost
// certainly forgot to configure this, not intentionally wants an open
// relay that clones and executes whatever repository a validly-signed
// (or, if --insecure, any) webhook payload names.
AllowedRepos []string
}
ServeConfig holds all runtime parameters for the webhook server.
Source Files