Appendix A: Cheat Sheet
Everything important from Days 0–15 on a few pages. The number in
parentheses is the day on which you practiced it. When in doubt,
gh <command> --help and the documentation at
docs.github.com/actions are authoritative.
gh for workflows
| Command | What it does | Day |
|---|---|---|
gh run list --limit 3 |
latest runs with ID | 1 |
gh run list --workflow ci.yml |
one workflow only | 2 |
gh run watch --exit-status <ID> |
follow a run, exit code = result | 1 |
gh run view <ID> / -v |
jobs / jobs with steps | 1, 2 |
gh run view <ID> --log /
--log-failed |
whole log / red steps only | 1 |
gh run view <ID> --json jobs --jq … |
machine-readable | 3 |
gh run rerun <ID> /
gh run cancel <ID> |
restart / cancel | 3, 5 |
gh run download <ID> -n <name> -D <dir> |
download an artifact | 3 |
gh workflow run x.yml -f name=wert |
workflow_dispatch with input |
2 |
gh workflow list |
workflows in the repository | 2 |
gh cache list |
caches | 3 |
gh pr create --fill / checks --watch /
merge --squash --delete-branch |
pull request | 2 |
gh release create/view/list/download |
releases | 7 |
gh secret set X --env produktion --body … |
secret in the environment | 10 |
gh ruleset list / check main |
rulesets | 4 |
gh attestation verify oci://… -R <du>/<repo> |
verify an attestation | 8 |
gh api repos/{owner}/{repo}/… |
REST API, gh fills in {owner}/{repo} |
3 |
Structure of a workflow
name: ci
on:
push:
branches: [main]
tags: ['v*']
paths-ignore: ['**.md']
pull_request:
workflow_dispatch:
inputs:
version: {required: true}
permissions:
contents: read
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
env:
IMAGE: ghcr.io/${{ github.repository_owner }}/notes-api
jobs:
test:
strategy:
matrix:
os: [ubuntu-24.04, ubuntu-24.04-arm]
runs-on: ${{ matrix.os }}
outputs:
kurz: ${{ steps.sha.outputs.kurz }}
steps:
- uses: actions/checkout@<sha> # v7.0.1
with:
persist-credentials: false
- id: sha
run: echo "kurz=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
weiter:
needs: test
if: github.event_name != 'pull_request'
environment: produktion
runs-on: [self-hosted, lab]
permissions:
contents: read
id-token: write
steps:
- env:
KURZ: ${{ needs.test.outputs.kurz }}
run: echo "$KURZ"Expressions and contexts
| Expression | Meaning | Day |
|---|---|---|
${{ github.sha }}, github.ref_name,
github.actor |
commit, branch/tag, initiator | 2 |
${{ inputs.x }} |
input of
workflow_dispatch/workflow_call |
2, 12 |
${{ steps.<id>.outputs.<n> }} |
output of a step | 2 |
${{ needs.<job>.outputs.<n> }} |
output of a job | 2 |
${{ matrix.<n> }} |
matrix value | 3 |
${{ secrets.X }}, github.token |
secret, token of the run | 6, 10 |
if: success() / failure() /
always() |
step after green / red / always | 2 |
if: inputs.laut |
boolean – comparison inside the expression | 15 |
contains(github.ref_name, '-') |
text contains | 7 |
Never put foreign text (titles, branch names, inputs) directly into
run:; pass it via env: (9).
Runner files
| File / variable | Purpose | Day |
|---|---|---|
$GITHUB_OUTPUT |
name=wert → step output |
2 |
$GITHUB_STEP_SUMMARY |
Markdown on the run’s page | 2 |
$GITHUB_SHA, $GITHUB_REF_NAME,
$GITHUB_REPOSITORY |
set by the runner | 2, 7 |
::error title=…::Text |
annotation | 13 |
shell: bash |
bash -e -o pipefail instead of
bash -e |
15 |
Permissions of the GITHUB_TOKEN
| Permission | What for | Day |
|---|---|---|
contents: read |
checkout – the default for every workflow | 9 |
contents: write |
releases, tags | 7 |
packages: write |
push to GHCR | 6 |
id-token: write |
OIDC token (Sigstore, clouds) | 8, 10 |
attestations: write |
store attestations | 8 |
security-events: write |
SARIF to code scanning | 8 |
issues: write |
issues, labels | 15 |
actions: write |
start other workflows | 11 |
Actions in the book
| Action | Purpose | Day |
|---|---|---|
actions/checkout@v7 |
fetch code | 1 |
actions/setup-go@v7 |
Go from go.mod, with cache |
1, 3 |
actions/upload-artifact@v7 /
download-artifact@v8 |
artifacts | 3 |
golangci/golangci-lint-action@v9 |
lint | 4 |
docker/setup-buildx-action@v4 |
Buildx | 6 |
docker/login-action@v4 |
registry login | 6 |
docker/metadata-action@v6 |
tags and labels from Git | 6, 7 |
docker/build-push-action@v7 |
build, push, cache-from/to: type=gha |
6 |
aquasecurity/[email protected] |
vulnerabilities | 8 |
anchore/[email protected] |
SBOM | 8 |
actions/attest@v4 |
provenance, with sbom-path SBOM attestation |
8 |
sigstore/[email protected] |
cosign | 8 |
github/codeql-action/upload-sarif@v4 |
findings to code scanning | 8 |
Runners
| What | Command | Day |
|---|---|---|
| Registration token | gh api -X POST repos/<du>/<repo>/actions/runners/registration-token |
5 |
| Register | ./config.sh --unattended --url … --token … --labels lab |
5 |
| As a service | sudo ./svc.sh install ubuntu / start /
stop |
5 |
| Variables for jobs | .env in the runner folder, then restart |
11 |
| ARC controller | helm install arc … gha-runner-scale-set-controller |
14 |
| Scale set | helm install arc-notes -f arc-notes.yaml … gha-runner-scale-set |
14 |
| Runner pods | kubectl -n arc-runners get pods /
get ephemeralrunners |
14 |
Security in five lines
permissions: contents: readat the top, more only in the job (9).- Pin actions by SHA, version as a comment, Dependabot keeps them up to date (9, 10).
- Foreign text only via
env:(9). checkoutwithpersist-credentials: false(9).- No self-hosted runner for fork pull requests; approval for all external contributors (5).
Failure patterns
| Symptom | Cause | Day |
|---|---|---|
| No run after the push | paths-ignore, wrong branch, invalid
YAML |
2, 9, 15 |
does not have 'workflow_dispatch' trigger |
file invalid or not on main |
15 |
Resource not accessible by integration |
permissions: missing |
15 |
Job stays queued |
no runner with all labels / maxRunners reached |
5, 14 |
| Value is empty | typo in output/secret, secret in the environment | 15 |
| Step green despite an error | pipe without pipefail |
15 |
Permission denied at startup |
download-artifact without chmod +x |
3 |
Conflict: an artifact with this name … |
same artifact name in the matrix | 15 |
base branch policy prohibits the merge |
ruleset, check red | 4 |
permission denied from kubectl |
KUBECONFIG not set (k3s) |
11 |