Skip to content

Contributor Architecture

PitCrew is a profile-driven control plane for isolated, ephemeral GitHub Actions runners. PowerShell prepares and reconciles profile configuration, one manager container owns Docker access for that profile, and disposable worker containers execute one job each.

Control-plane boundaries

Setup-Runner.ps1 is the operator entry point. It resolves one profile, prepares and verifies images, publishes static and mutable state, and performs compatible manager handoff. RunnerProfiles.Functions.ps1 owns manifest resolution, normalization, fingerprints, generated environment values, and rolling compatibility. runner-profile.schema.json is the public manifest contract.

docker-compose.yml defines the profile manager. Only that manager mounts the host Docker socket and host pressure source. Workers are sibling containers launched by the manager and receive neither mount.

The manager has two implementations:

  • manager/manage-runners.sh owns fixed-capacity reconciliation.
  • manager/autoscaler/ owns opt-in GitHub Runner Scale Set demand handling.

Both implementations consume the same generated state and publish the same credential-free observed-state contract. manager/reconciliation.sh provides shared desired-capacity validation and stable slot-key derivation.

Built-in worker profiles live under profiles/. External manifests remain operator-owned and are validated against the public schema before they can affect a live profile.

Lifecycle invariants

Every worker accepts one job and is destroyed with --rm. Fixed profiles replace workers to maintain desired capacity. Autoscaled profiles use GitHub's assigned-job signal to choose activation between their idle floor and configured maximum.

Profile identity is exact. Compose projects, state directories, labels, worker revisions, and cleanup selectors are isolated by profile. Cleanup and adoption use exact labels or exact container IDs rather than container-name matching.

Compatible capacity, manager, image, and resource-policy updates preserve active workers. Removed capacity drains after the current worker exits. Registration topology and routing changes require an explicit profile stop rather than an implicit destructive replacement.

See:

Observability boundary

Managers collect lifecycle, registration, resource, operation, capacity, hardware, and bounded job-context evidence. Unsupported or stale measurements remain explicit; they are not inferred from resource activity or converted to zero.

The projection contains no registration token, JIT configuration, environment values, raw runner identity, job output, or host-private identifiers. Connectors and dashboards are read-only consumers and never receive the Docker socket.

observed-state.schema.json, the two manager implementations, and their contract tests must advance together.

Operations plugin

plugins/pitcrew-operations/ is a published product surface, not contributor guidance. Its skills describe bounded operator procedures for capacity, rollout, updates, diagnostics, performance correlation, and manager recovery. Shared safety contracts live under the plugin's references/ directory.

Plugin manifest, marketplace metadata, documentation, scripts, and tests must remain consistent because users install the repository as a Copilot CLI marketplace.

Executable contracts

The complete validation and delivery definitions live in:

  • .github/workflows/ci.yml
  • .github/workflows/docs.yml
  • .github/genesis-delivery.json
  • tests/
  • manager/autoscaler/go.mod
  • docker-compose.yml
  • mkdocs.yml

Use Building from Source for local entry points. Hosted Docker integration and complete pull-request evidence remain owned by the configured CI workflows.