Runners & advanced pipelines

Every runs-on: ubuntu-latest you have typed summoned a fresh virtual machine from GitHub's fleet: booted for your job, preloaded with an enormous toolbox — Git, Docker, the Azure CLI, half a dozen language runtimes — used once, and destroyed. You never patched it, never paid its idle hours, and never inherited anything from the previous job, because there was no previous job. That disposability is the quiet security feature of everything you built in the last two classes: a fresh machine has no leftover credentials, no poisoned cache, no drift. For most teams, most of the time, hosted runners are simply the correct answer, and the interesting question is only what they cannot do.

They cannot reach your private network — a standard hosted runner lives in GitHub's cloud, so the Class Fourteen private endpoint or an internal-only service is invisible to it. (One middle rung exists before self-hosting: GitHub's larger hosted runners can be joined to an Azure VNet, buying private reach while GitHub still owns the patching — at larger-runner prices. Name it in the design conversation before anyone builds a server.) They come in fixed shapes, so a build that wants serious cores, unusual memory, or a GPU is out of luck at the standard sizes. They start from a blank slate every time, so a gigantic toolchain must be fetched on every run — that is a speed tax §3 will address. And they are metered: public repositories run free, private ones burn a minutes allowance and then a credit card, with Windows and macOS minutes billed at a multiple of Linux.¹ Those four limits — network, hardware, startup state, and money — are the complete list of reasons to consider the alternative. Everything else is a reason not to.

Self-hosted runner

A machine you own — a VM, a server, a container — running GitHub's runner agent, picking up jobs from your repository. You gain its network position, its hardware, and its persistence; you take on its patching, its scaling, and everything a malicious job could do to it.

A self-hosted runner solves all four limits at once. Put the agent on a VM inside the Campux VNet and the pipeline can reach the private endpoints of Class Fourteen. Choose the hardware and the build gets whatever cores or GPU it needs. The machine persists between jobs, so the toolchain is already there. And your own compute may be cheaper than metered minutes at scale. Teams reach for it for exactly these reasons, and sometimes they are right to.

Now read the bill. That machine is yours: you patch it, monitor it, scale it, and rebuild it when it fills up with the residue of a thousand builds — because unlike a hosted runner, it remembers. Persistence is the feature and the flaw in one property: whatever job ran at nine o'clock leaves files, processes, and possibly credentials on the machine that runs the ten o'clock job. And the sharpest edge has a name in GitHub's own documentation: never attach a self-hosted runner to a public repository. A public repository accepts pull requests from anyone on the internet, a pull request can modify a workflow, and a workflow is a program your runner executes — which chains into "any stranger can run code on a machine inside your network". The hosted runner absorbs that risk by being disposable and GitHub's problem; the self-hosted runner hands it to you whole.²

One runner rarely stays one runner. The moment two jobs want it at once the second waits, so self-hosted machines are pooled — and a runner group decides which repositories and workflows may draw from a given pool, so the finance team's runner is not quietly borrowed by an experiment in someone's fork. Scaling that pool by hand is a losing game, which is why serious self-hosted setups autoscale: ephemeral, single-use runners registered just in time, torn down after one job, spun up again on demand. GitHub's Actions Runner Controller does exactly this on Kubernetes. Read the shape of that answer twice — the mature fix for self-hosting's persistence problem is to rebuild the statelessness you gave up in §1. When the sophisticated version of a thing reinvents the default you left, the default was usually right for anyone who did not have to leave it.

The decision rule is short: hosted until a named requirement — private network, specific hardware, or minutes-at-scale economics — forces the question, and then self-hosted with the discipline of a production system, because that is what it is. "It would be a bit faster" is not a named requirement; it is how teams acquire an unpatched Linux box with production network access and a job queue anyone in the org can feed.

Two Actions features move files around, and confusing them costs real debugging time. A cache makes the next run faster: dependencies that take minutes to download get stored against a key and restored on the following run. An artifact carries results — within a run between jobs (which, as Drill 02 of Class Twenty-Two taught, are strangers on separate machines), or out of the run to a human who downloads them.

# cache: speed across runs — keyed on the lockfile
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('package-lock.json') }}

# artifact: truth within and beyond a run
- uses: actions/upload-artifact@v4
  with:
    name: whatif-report
    path: whatif-output.txt
# ...and in a later job:
- uses: actions/download-artifact@v4
  with:
    name: whatif-report

The key line deserves the attention. hashFiles('package-lock.json') means the cache is valid exactly as long as the dependency list is unchanged — edit the lockfile and the key changes, the old cache misses, and a fresh download rebuilds it. Get the key wrong in the other direction — too static — and you serve stale dependencies forever while wondering why the pipeline disagrees with your laptop. The rule of thumb: cache things you can afford to lose (it is a speed optimisation, and caches are evicted after a week unused), artifact things you need to trust — a compiled template, a what-if report for an approver, test results an auditor might ask for. Cache is speed; artifact is evidence.

The moment Campux has two repositories, the deploy workflow wants to exist twice — and Class Nineteen already taught you what copies do: they drift. The fix is a reusable workflow: a workflow whose trigger is workflow_call, which other workflows invoke like a function, passing inputs and secrets explicitly.

# platform repo: .github/workflows/deploy-bicep.yml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v7
      - uses: azure/login@v2
        with: { client-id: '${{ vars.AZURE_CLIENT_ID }}', tenant-id: '${{ vars.AZURE_TENANT_ID }}', subscription-id: '${{ vars.AZURE_SUBSCRIPTION_ID }}' }
      - run: az deployment group create --resource-group rg-campux-${{ inputs.environment }} --template-file infra/main.bicep

# any other repo calls it in three lines:
jobs:
  deploy-nonprod:
    uses: campux/campux-platform/.github/workflows/deploy-bicep.yml@main
    with: { environment: nonprod }

Its smaller sibling is the composite action — a bundle of steps (an action.yml in its own folder or repository) for sequences that repeat inside jobs, like "log in to Azure and select the subscription". The division of labour: composite action for a reusable step sequence, reusable workflow for a whole job with its runner, environment, and gates. Extraction has the same discipline as Bicep modules — do it when the third copy appears, version the shared thing with tags rather than @main once others depend on it, and remember that a shared workflow is now an interface: changing its inputs breaks every caller at once, which is exactly the power and exactly the risk.

The storefront has to pass its tests on the Node version running in production today and the one the platform team is about to move everyone to. Writing the test job twice is the copy-paste sin again in miniature: two blocks that must be kept in step by hand, drifting the first time someone edits only one. A matrix writes the job once and tells GitHub to fan it out — one definition, a job per combination, all running in parallel on separate machines the way Class Twenty-Two established jobs always do.

# one job definition, six actual jobs
strategy:
  fail-fast: false
  max-parallel: 4
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]

Three Node versions times two operating systems is six jobs from nine lines, and the two knobs above are the ones that bite. fail-fast defaults to true, which cancels every sibling the instant one fails — efficient when you only need to know whether anything is broken, actively unhelpful when you need to know which combinations broke, because it hides five answers to save a minute. max-parallel caps how many run at once, which matters most on self-hosted pools with a finite number of machines — an uncapped matrix can swallow the whole fleet and starve every other pipeline. Two refinements earn their place: include adds a single extra combination without multiplying the grid (test one exotic edge, not all of it), and exclude removes a combination that makes no sense. The cost to watch is the obvious one — a matrix multiplies, so a careless third dimension turns six jobs into fifty and your minutes bill with them.

The reusable workflow in §4 already carries the word: environment: ${{ inputs.environment }}. That line is not decoration. A GitHub environment is a named target — nonprod, prod — that you can wrap in protection rules, and a job that references one stops at its gate before the first step runs. The most valuable rule is required reviewers: name one or two people, and a deploy to prod pauses, waits, and does nothing until one of them clicks approve. The Class Twenty-Three point lands here with force — the federated credential is handed to the job only after the yes, so "who can deploy to production" stops being a question about who can push code and becomes a question about who can approve, which is the separation an auditor is actually asking for.³

Two more rules pay their way. A wait timer holds the deploy for a set number of minutes — a deliberately boring pause that lets a bad release be caught before it lands. A deployment branch policy restricts which branches may deploy to the environment at all, so prod can refuse anything that is not main no matter how the workflow is triggered. And environment-scoped secrets mean the production credential physically cannot be read by a job targeting nonprod — the blast radius of a leaked secret shrinks to the one environment that holds it. This is the machinery behind the promise the "On the job" box made two screens up: the risky step waits for a human, and the waiting is configuration, not a convention someone has to remember. Azure Pipelines calls the same idea Environments with approvals and checks (Class Thirty-Nine); the vocabulary differs, the gate is identical, and AZ-400 expects you to recognise it in either dialect.

Reuse has two halves. §4 shared pipeline logic; the other half is sharing code. When the storefront and the platform both need the same validation helpers, the wrong answer is a copied file — Class Nineteen's drift, again — and the right answer is to publish the helpers once as a versioned package that both repositories install like any other dependency. GitHub Packages is the registry sitting next to your repository: it hosts npm, NuGet, Maven, and RubyGems packages, and container images through ghcr.io. A workflow publishes to it with the same GITHUB_TOKEN you have been granting scopes to, this time with permissions: packages: write — least privilege, per Class Eight, applied to the act of publishing.

# publish job — the token needs one added scope
permissions:
  contents: read
  packages: write
steps:
  - uses: actions/checkout@v7
  - run: npm version patch          # bump the SemVer number
  - run: npm publish                # to GitHub Packages

The version number is the whole discipline, and it has rules. Semantic versioning — MAJOR.MINOR.PATCH — is a promise to the people who install your package: bump the patch for a bug fix that changes nothing they rely on, the minor for a feature that adds without breaking, and the major only when you break something they will have to react to. Consumers pin a range in return — "the current 2.x, and pick up minors and patches automatically" — so a disciplined publisher can ship a fix to forty repositories without a single one editing a file, and an undisciplined one who slips a breaking change into a patch has just detonated all forty at three in the morning. This is the same interface contract §4 drew for reusable workflows, now applied to code: the number is the API, and breaking it quietly is the cardinal sin.

The Azure sibling is Azure Artifacts — feeds that host npm, NuGet, Maven, Python, and universal packages for Azure DevOps pipelines, with upstream sources that proxy the public registries so an outage upstream does not stop your build. GitHub Packages and Azure Artifacts are the same idea in two houses; SemVer is the language both speak, and the reason AZ-400 keeps a section for it. Publishing is where a great many candidates go blank in the interview — they can write a pipeline that deploys, but not one that ships a versioned thing other teams depend on, and the second is the more senior sentence to be able to say.

Three settings separate pipelines built by professionals from pipelines that merely work. None takes more than two lines, and all three exist because of a failure somebody paid for.

timeout-minutes

The default job timeout is measured in hours. A hung job — a prompt waiting for input that never comes, a network call that never returns — burns paid minutes and blocks the queue the whole time. timeout-minutes: 15 on every job converts a silent all-nighter into a fast, visible failure.

concurrency

Two merges in quick succession mean two deploys running at once — the Terraform lock fight from Class Twenty-One, recreated inside your own pipeline. concurrency: { group: deploy-prod, cancel-in-progress: false } queues them one at a time; for PR validation, cancel-in-progress: true stops wasting minutes checking commits already superseded.

permissions

Every job gets an automatic GITHUB_TOKEN. Newer repositories default it to read-only; older ones still hand out write-everything — and either way, an unstated default is a decision someone else made. Declare permissions: contents: read at the top and grant more only where a job earns it — Class Eight's least privilege, applied to the pipeline's own credential.

Boring pipelines are the achievement.

Notice what all three have in common: they cost nothing when things go well and everything happens the day they are missing. That is the character of this whole class — runners, matrices, caches, reuse, gates, packages, hygiene — none of it demos well, all of it decides whether the twentieth repository is as safe as the first. A pipeline that is fast, quiet, and identical every time is not a lack of ambition. It is the ambition.⁴