Configuration¶

Setup-Runner.ps1 is the operator entry point. Each invocation converges one profile without changing other profiles on the same host.

Setup parameters¶

Parameter	Required	Description	Default
`-Token`	No	Fine-grained PAT used only to register runners. When omitted, PitCrew uses `gh auth token`.	Authenticated `gh` token
`-Profile`	No	Built-in profile name.	`default`
`-ProfilePath`	No	Path to an external profile manifest. Relative image-build paths resolve from the manifest directory.	None
`-Scope`	No	GitHub runner scope: `repo`, `org`, or `ent`.	`repo`
`-Repos`	Repository scope	Repository URLs, optionally followed by `=workers`.	None
`-AddRepos`	No	Adds repositories to the selected profile's generated state.	None
`-RemoveRepos`	No	Removes repositories from the selected profile's generated state.	None
`-OrgName`	Organization scope	GitHub organization name.	None
`-EnterpriseName`	Enterprise scope	GitHub enterprise name.	None
`-Replicas`	No	Default workers per repository, or total workers for organization/enterprise scope. `0` auto-sizes to half the host processors with a minimum of two.	Profile value
`-Labels`	No	Comma-separated custom labels. The mandatory profile label remains.	Profile value
`-NamePrefix`	No	Prefix shown for runner registrations in GitHub.	Host name plus profile
`-Image`	No	Overrides the profile's worker image.	Profile value
`-PullImage`	No	Controls whether setup pulls a prebuilt image before verification.	Profile value
`-RunnerGroup`	No	Organization or enterprise runner group.	Profile value
`-Down`	No	Stops only the selected profile and removes its managed workers.	Off

Repository worker counts¶

Repository scope supports a different count for every target:

.\Setup-Runner.ps1 -Repos `
    https://github.com/you/light-project=1,`
    https://github.com/you/heavy-project=6

These workers are dedicated to their repositories. Use organization or enterprise scope when several repositories should share one capacity pool.

Profile manifest¶

Named profiles conform to runner-profile.schema.json.

Field	Required	Description
`schemaVersion`	Yes	Manifest contract version. Version `1` is currently supported.
`name`	Yes	Lowercase profile identifier and mandatory routing label.
`description`	Yes	Human-readable purpose.
`image`	Yes	Worker image tag.
`labels`	Yes	Additional capability labels.
`replicas`	Yes	Default positive worker count.
`pullImage`	No	Pull a prebuilt image before verification.
`disableDefaultLabels`	No	Omit GitHub's broad default labels. Named profiles default to `true`.
`runnerGroup`	No	Organization or enterprise runner group.
`verificationCommands`	No	Shell commands executed in the prepared image before profile replacement.
`build`	No	Local Docker build context, Dockerfile, and non-secret build arguments.

Generated state¶

The default profile writes .env; named profiles write .env.<profile>. PitCrew generates these files and Git ignores them because they contain the runner-registration token. Do not edit or commit them.