Files

T

Chris Farhood 2706245b03 docs: add workflow documentation and best practices

Documents available tools on runners and common patterns for GitHub Actions.
Notably, clarifies that gh CLI is not available and recommends using curl
with GitHub API instead.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-05-11 12:44:56 +00:00

2.2 KiB

Raw Blame History

GitHub Actions Workflows

This directory contains reusable and repo-specific GitHub Actions workflows for the privilegedescalation organization.

Available Tools on Runners

Always Available

curl - HTTP client (use this instead of gh CLI for API calls)
jq - JSON processor
bash - Shell
git - Version control
docker / podman - Container runtime (depending on runner)

NOT Available (must install if needed)

gh CLI - GitHub CLI is not pre-installed on runners. Use curl with the GitHub API instead.

Best Practices

GitHub API Calls

Instead of using gh CLI (which is not installed), use curl with the GitHub API:

- name: Set PR label
  env:
    GH_TOKEN: ${{ github.token }}
    REPO: ${{ github.repository }}
    PR_NUMBER: ${{ github.event.pull_request.number }}
  run: |
    curl -sf \
      -X POST \
      -H "Authorization: Bearer ${GH_TOKEN}" \
      -H "Accept: application/vnd.github.v3+json" \
      "https://api.github.com/repos/${REPO}/issues/${PR_NUMBER}/labels" \
      -d '{"labels":["label-name"]}'

Workflow Validation

Run actionlint locally before pushing:

actionlint -color .github/workflows/*.yaml

Reusable Workflows

plugin-ci.yaml - Standard CI for Headlamp plugins
plugin-e2e.yaml - E2E testing for Headlamp plugins
dual-approval-check.yaml - Checks for CTO and QA approval
detect-pr-pipeline.yaml - Detects Pipeline A vs Pipeline B based on changed files

Workflow Naming Convention

Use kebab-case: my-workflow.yaml
Be descriptive: plugin-ci.yaml not ci.yaml
For reusable workflows, keep the name clear about its purpose

Required Gates

All PRs must pass:

actionlint validation (workflow YAML syntax)
Shell script validation (if scripts are used)
Any repo-specific CI checks

Common Patterns

Getting Changed Files

Use tj-actions/changed-files:

- name: Get changed files
  id: changed-files
  uses: tj-actions/changed-files@v44
  with:
    files_separator: '\n'

Setting Job Outputs

- name: Set output
  id: detect
  run: |
    echo "pipeline-type=pipeline-a" >> $GITHUB_OUTPUT

Access in downstream jobs: ${{ jobs.job-name.outputs.pipeline-type }}

2.2 KiB Raw Blame History