GitHub Runner Labels

This document explains the mechanics of GitHub Runner labels (baseLabel and extraLabels) used within the GitHubRunnerClaim. Labels determine how GitHub workflows identify suitable runners for job execution.

Label Mechanics

Each runner in Puzl Cloud has two types of labels:

1. Base Label (Required)

The baseLabel defines the fundamental OS or environment for the runner. It must be one of the predefined values provided by Puzl:

Value	Description
`puzl-any` (default)	Runner will take any job if it contains label starting with `puzl-` in the `runs-on` section
`puzl-ubuntu-20.04`	Ubuntu 20.04 environment runner
`puzl-ubuntu-22.04`	Ubuntu 22.04 environment runner
`puzl-ubuntu-24.04`	Ubuntu 24.04 environment runner
`puzl-ubuntu-latest`	Ubuntu latest stable environment runner (currently 24.04)
`puzl-custom`	Custom runner image provided by the user. Must be used with `customImage` setting.

2. Extra Labels (Optional)

The extraLabels property allows additional, custom-defined tags that further refine runner selection criteria, which might be useful if you want to route different workflows to different GitHubActionsIntegrations.

You can define multiple extra labels to precisely match the capabilities required by your GitHub workflows.

How to Use Labels in GitHub Actions Workflows (`runs-on`)

To select the appropriate runners from GitHub Actions workflows, specify the labels in the runs-on configuration.

Example 1: Simple Base Label Usage

Run a job explicitly on Ubuntu 22.04 provided by Puzl Cloud:

jobs:
  build:
    runs-on: puzl-ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
      - run: echo "Running on Ubuntu 22.04"

Example 2: Using Extra Labels to Match Specific Runner

Runner Claim:

apiVersion: github-actions.svcs.puzl.cloud/v1
kind: GitHubRunnerClaim
metadata:
  name: my-isolated-runner
spec:
  jobProvider:
    baseLabel: puzl-ubuntu-24.04
    extraLabels:
      - isolated-runner
  jobs:
    waitForDockerOnStart: true

GitHub Actions Workflow:

jobs:
  isolated-job:
    runs-on: [puzl-ubuntu-24.04, isolated-runner]
    steps:
      - uses: actions/checkout@v3
      - run: |
          echo "Running job on the runner from another Integration"

Example 3: Using `puzl-any` Label in the Job Config

Select any available Puzl runner provided, irrespective of the OS version:

jobs:
  generic-job:
    runs-on: puzl-any
    steps:
      - uses: actions/checkout@v3
      - run: echo "Running on any available Puzl runner"

Example 4: Custom Image Runner Selection

Define a custom Docker image runner and explicitly target it in your workflow:

Runner Claim:

apiVersion: github-actions.svcs.puzl.cloud/v1
kind: GitHubRunnerClaim
metadata:
  name: custom-runner
spec:
  jobProvider:
    baseLabel: puzl-custom
    extraLabels:
      - my-custom-runner
  jobs:
    customImage: registry.example.com/my-custom-runner:latest

GitHub Actions Workflow:

jobs:
  custom-app-job:
    runs-on: [puzl-custom, my-custom-runner]
    steps:
      - uses: actions/checkout@v3
      - run: ./run-custom-app.sh

Label Matching Logic in Workflows

GitHub workflows match runners based on logical AND when multiple labels are specified in runs-on. This means that runner must match all listed labels (baseLabel and each extraLabel) to be selected.

For more details on using labels in GitHub Actions, see the official GitHub documentation.