PitCrew

PitCrew orchestrates containerized GitHub Actions runners that are destroyed after one job and replaced when fixed capacity or current demand requires another. It is designed for teams and individual developers who want self-hosted capacity without carrying workspace state or partially installed tools between jobs.

Installation

Clone the public repository onto a dedicated Docker host:

git clone https://github.com/ncosentino/pitcrew.git
Set-Location pitcrew

PitCrew requires PowerShell 7 and Docker with Linux-container support.

Quick example

Start two general-purpose workers for one repository:

.\Setup-Runner.ps1 `
    -Repos https://github.com/you/project=2

Route a workflow job to that pool:

jobs:
  build:
    runs-on: [self-hosted, linux, x64, general-purpose]

Why it exists

Long-lived self-hosted workers accumulate state: interrupted package installs, modified global tools, cached credentials, and stale workspaces can affect later jobs. PitCrew keeps lightweight manager containers alive while replacing the actual workers after every job.

Named profiles also let one host provide separate capacity for routine builds and specialized workloads without allowing broad self-hosted jobs to consume the specialized pool.

Optional demand-driven profiles retain only a configured idle floor and use GitHub runner scale-set demand to return toward their operator-defined maximum.

Documentation map

• Getting Started installs the first profile and routes a workflow.
• Configuration defines setup parameters, profile manifests, generated state, and manager contracts.
• Host-Local Admission Operations explains policy calibration, rollout, diagnostics, and rollback.
• Troubleshooting diagnoses registration, routing, capacity, image, and Docker failures.
• Building from Source identifies local validation entry points.
• Documentation Deployment defines the canonical site and Pages indexing boundary.
• Guides cover profiles, routing, autoscaling, updates, security, services, external data, and Copilot operations.
• Isolated Image Builder publishes OCI images through an mTLS BuildKit service without exposing Docker control.
• Android Emulator Runners run a fresh hardware-accelerated Android emulator inside each disposable worker.
• Contributor Architecture maps implementation boundaries and executable contracts.
• Agent Guidance explains guidance ownership, review, and context budgets.
• Architecture Decision Records preserve significant decisions.

About

PitCrew is built by Nick Cosentino. Follow Dev Leader for software engineering articles and videos, and BrandGhost for social-first updates.