🔄 GitHub Actions Workflows

HyperShift uses GitHub Actions for lightweight CI checks that run on every pull request. These workflows complement the heavier Prow-based e2e tests by providing fast feedback on code quality, formatting, and documentation.

🏗️ Reusable Workflow Architecture

All GHA workflows follow a caller + reusable pattern:

• Caller workflow (e.g., lint.yaml) — defines triggers (pull_request, branch filters) and delegates to a reusable workflow pinned at @main.
• Reusable workflow (e.g., lint-reusable.yaml) — contains the actual job steps. Triggered via workflow_call and optionally on push to main for post-merge runs.

flowchart LR
    subgraph "Caller (lint.yaml)"
        A["on: pull_request"] --> B["uses: ...lint-reusable.yaml@main"]
    end

    subgraph "Reusable (lint-reusable.yaml)"
        B --> C["on: workflow_call"]
        C --> D["Checkout + Run lint"]
    end

This pattern provides:

• ✅ Consistency — all PR and push workflows share the same job definitions.
• 🔧 Maintainability — job logic is defined once in the reusable workflow and updated in a single place.
• 🔒 Security — callers pin reusable workflows to @main, reducing the risk of PRs altering reusable job logic. Caller workflows are protected by branch protection rules and CODEOWNERS.

📋 Workflows

The PR validation workflows run on self-hosted ARC runners. Most target main and release-4.22; only the OCP and vanilla Kubernetes envtest workflows also target release-5.0.

Pull request callers resolve their reusable workflows from main, while post-merge runs use the reusable workflow stored on the pushed branch. Keep branch-local matrices synchronized with main; release-5.0 envtests must include Kubernetes 1.36 for consistent pull request and post-merge coverage.

🧹 Code Quality

🧪 Testing

📖 Documentation

🔧 Other

➕ Adding a New Workflow

To add a new GHA workflow:

1. Create the reusable workflow (e.g., my-check-reusable.yaml) with on: workflow_call. This is where all the job logic lives.
2. Create the caller workflow (e.g., my-check.yaml) that uses the reusable workflow pinned at @main.
3. Add branch filters for main and each release branch where the workflow is intended to run. Do not assume every workflow should target every release branch.
4. Use arc-runner-set as the runner.

Post-merge runs

If your workflow should also run after PRs merge to main (e.g., for Codecov baseline uploads or post-merge validation), add on: push triggers to the reusable workflow, not the caller. This lets the reusable workflow run directly on push events without needing a separate caller.

Why callers pin to @main

Callers reference the reusable workflow at @main (e.g., uses: openshift/hypershift/.github/workflows/my-check-reusable.yaml@main). This means a PR cannot modify the reusable workflow logic that runs against itself — it always executes the version from main. This is a deliberate security measure: it prevents a PR from weakening checks to make itself pass.

name: My Check

on:
  pull_request:
    branches:
      - main
      - release-4.22

jobs:
  my-check:
    uses: openshift/hypershift/.github/workflows/my-check-reusable.yaml@main
    permissions:
      contents: read

name: My Check (Reusable)

on:
  workflow_call:
  push:
    branches:
      - main
      - release-4.22

permissions:
  contents: read

jobs:
  my-check:
    name: My Check
    runs-on: arc-runner-set
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
      - run: echo "Run your check here"