Designing a Minimal, Secure GitHub Actions Pipeline with Self‑Hosted Runners

Requirements

When setting up a CI/CD pipeline on GitHub Actions the goal is to:

• Run build, test, and deploy stages in a predictable order.
• Keep runtime secrets (API keys, cloud credentials) out of the repository and away from workflow logs.
• Isolate the execution environment so that a compromised job cannot affect other workloads or the host machine.
• Provide observable health signals for the runner pool so that failures are detected early.
• Keep the workflow definition simple enough to be maintained by a small team.

Smallest Suitable Design

The design uses three separate workflow files, each representing a major stage:

1. build.yml – compiles artifacts and publishes them as a workflow artifact.
2. test.yml – downloads the build artifact, runs unit/integration tests, and publishes test results.
3. deploy.yml – downloads the tested artifact and pushes it to the target environment.

Each file contains a single job that uses needs: to enforce ordering:

# build.yml
name: Build
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Set up build tool
        run: ./setup-build.sh
      - name: Build artifact
        run: ./build.sh
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: app-build
          path: dist/

# test.yml
name: Test
on:
  workflow_run:
    workflows: [ "Build" ]
    types:
      - completed
jobs:
  test:
    needs: []  # implicit dependency via workflow_run trigger
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: app-build
          path: ./dist
      - name: Run tests
        run: ./run-tests.sh
      - name: Publish test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-output/

# deploy.yml
name: Deploy
on:
  workflow_run:
    workflows: [ "Test" ]
    types:
      - completed
jobs:
  deploy:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Download tested artifact
        uses: actions/download-artifact@v4
        with:
          name: app-build
          path: ./dist
      - name: Deploy to cloud
        env:
          CLOUD_KEY: ${{ secrets.CLOUD_KEY }}
          CLOUD_SECRET: ${{ secrets.CLOUD_SECRET }}
        run: ./deploy.sh

All secrets are referenced via the secrets context and never appear in plain text in the YAML.

Trust and Data Boundaries

GitHub Actions treats the workflow file as trusted code that runs in the context of the repository. Because the YAML is visible to anyone with read access (and public in public repositories), the design ensures:

• No secret values are hard‑coded; they are stored exclusively in GitHub Secrets.
• The self-hosted runner pool is dedicated to this repository (or a tightly scoped set of repositories) and is not shared with public or untrusted workflows.
• Artifacts are the only data that cross job boundaries; they are stored encrypted at rest and transmitted over TLS.

Operational Checks

To verify that the pipeline behaves as intended, perform the following checks:

1. Secret confidentiality – Add a step that echoes a secret (e.g., echo ${{ secrets.TEST_SECRET }}) to a temporary log, then run the workflow on a test branch. Confirm that the workflow run’s logs do not contain the secret value (GitHub masks it automatically).
2. Runner affinity – Label each self‑hosted runner with a custom tag, e.g., self-hosted,linux,prod. In the workflow set runs-on: [self-hosted, linux, prod]. After a run, inspect the runner’s hostname in the job’s debug logs or via the runner’s _diag endpoint to ensure the job executed on a machine bearing that label.
3. Dependency enforcement – Trigger a build, then manually cancel the test workflow run while leaving the build successful. The deploy workflow should not start because its workflow_run trigger requires the test workflow to conclude with success. Verify that the deploy job is skipped.
4. Runner health monitoring – Deploy a simple cron job on the runner host that writes a timestamp to a file every minute. Create a separate monitoring workflow that runs on a GitHub‑hosted runner, SSHs into the self‑hosted runner (using a stored SSH key secret), and checks the file’s age. If the file is older than two minutes, send an alert to a Slack channel via a webhook secret. Observe that stopping the runner agent causes the alert to fire.

Failure Modes

Understanding how the design reacts to common failures helps set appropriate expectations:

• Secret leakage via logs – If a step inadvertently prints a secret (e.g., echo $CLOUD_KEY), GitHub will mask the value in the UI, but the raw log sent to the runner’s stdout may still contain it before masking. Mitigation: avoid debugging commands that echo secrets; use ::add-mask:: only for values you know are safe.
• Runner compromise – Because the self‑hosted runner executes with the privileges of the service account running the agent, a compromised runner could read repository secrets or tamper with artifacts. Mitigation: keep the runner OS patched, run the agent under a non‑root user with limited permissions, and use network segmentation to prevent lateral movement.
• Mis‑labelled runner – A typo in the runs-on: list (e.g., self-hostted) causes the job to remain queued indefinitely. GitHub does not retry automatically; the workflow run will show a "Queued" status until manually cancelled or the label is corrected.
• Artifact expiry – Workflow artifacts are retained for 90 days by default. If a deploy job runs after that window, the download step will fail. Mitigation: either adjust the retention period via retention-days in the upload step or ensure the deploy workflow runs within the artifact lifetime.

Conditions That Would Change the Design

The current minimal architecture assumes a single repository, a modest release cadence, and the ability to dedicate a VM pool to self‑hosted runners. The design would be revisited if:

• Multiple teams need to share the same runner pool, requiring finer‑grained access controls (e.g., using runner groups and scoped secret visibility).
• Regulatory constraints demand that build artifacts never leave a specific network zone, prompting the use of GitHub’s OIDC token to authenticate directly to internal services without storing long‑lived credentials.
• The release frequency increases to dozens of pushes per day, making the three‑file approach harder to trace; a single workflow with conditional steps might become preferable for operational simplicity.
• Self‑hosted runner maintenance overhead becomes prohibitive, leading to a migration to GitHub‑hosted runners with larger instance types and reliance on GitHub Secrets for all credentials.

In each case, the core principles—secrets outside the YAML, explicit stage dependencies, and observable runner health—remain applicable, but the concrete implementation (runner labels, workflow grouping, secret scopes) would be adjusted.