GitHub Actions Foundations: Workflows, Events, YAML, Permissions, and Execution Model: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: preserve evidence before you “fix” the YAML

Use the same sequence every time: preserve evidence → identify repository/account/event/ref/workflow/run/job scope → inspect settings/permissions/logs/API → choose the least destructive correction → verify independently.

2. Failure mode: invalid YAML or wrong workflow location

GitHub discovers workflow files only in .github/workflows with YAML extensions. A file at .github/ci.yml may be valid YAML but is not a workflow. Conversely, a file in the correct directory can fail validation because its YAML or Actions schema is invalid.

REPO="OWNER/DISPOSABLE"

gh workflow list -R "$REPO" --all \
  --json id,name,path,state

# Inspect the committed path; this is Git evidence, not Actions evidence.
gh api \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "repos/$REPO/contents/.github/workflows" \
  --jq '.[] | {name,path,sha}'

If a new file does not appear in gh workflow list, verify location and branch first. If GitHub reports “Invalid workflow file,” preserve the exact annotation/line before editing. Do not hide the original cause by replacing the whole file.

3. Failure mode: the run is real, but it ran on the wrong event/ref

A workflow can succeed perfectly on the wrong source. Filter and dispatch mistakes are operational failures even when every step is green. Inspect event, headBranch, headSha, and the workflow’s own logged workflow_ref/workflow_sha.

RUN_ID="123456789"
REPO="OWNER/DISPOSABLE"

gh run view "$RUN_ID" -R "$REPO" \
  --json event,headBranch,headSha,attempt,status,conclusion,url

gh run view "$RUN_ID" -R "$REPO" --log

Do not repair a wrong-ref run by force-pushing a branch to “make the SHA match.” Correct the trigger/ref selection and create new evidence.

4. Intentionally broken example: least privilege blocks an unnecessary write

Suppose a CI workflow declares only contents: read but a new step tries to create an Issue. That write should fail. This is a useful controlled failure because it proves the token is not overprivileged.

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Intentionally forbidden write
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api --method POST \
            -H "X-GitHub-Api-Version: 2026-03-10" \
            "repos/$GITHUB_REPOSITORY/issues" \
            -f title='Chapter 13 permission probe' \
            -f body='This request should be rejected by least privilege.'

Expected evidence: the step exits non-zero and GitHub responds with a permission/forbidden error; no Issue is created. Interpret the cause: the token authenticated, but its effective authorization did not include Issues write.

5. Security failure: untrusted context becomes shell syntax

GitHub explicitly documents script-injection risk when attacker-controlled context values are embedded directly in inline scripts. A malicious PR title can contain characters that become executable shell syntax after expression substitution.

Unsafe pattern — do not run:

# DO NOT USE: PR title is untrusted and is inserted into shell source code.
- run: |
    title="${{ github.event.pull_request.title }}"
    echo "$title"

Safer pattern: copy the value into an environment variable and let the shell read it as data.

- name: Handle PR title as data
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: |
    printf '%s\n' "$PR_TITLE"

Quoting still matters. For complex structured data, prefer an action or script that parses a file/JSON input without constructing shell source code from attacker input.

6. Security failure: logs expose secrets or excessive context

Do not dump toJSON(github), env, secrets, or entire event payloads merely for convenience. The github context includes github.token during job steps; secret redaction is not guaranteed for every transformed value. Log only the fields needed to diagnose the run.

7. Runner and action failures: preserve the infrastructure boundary

A job that stays queued can mean no eligible runner is available. A step that fails before your code runs can mean an action dependency was blocked by policy or unavailable. For GitHub-hosted runners, inspect the selected label and setup log. For self-hosted runners, later chapters add runner status, group policy, network, and persistent-machine diagnostics.

If repository policy requires full-SHA pinning and the workflow uses third-party/action@v1, the correct fix is not to disable policy. Pin a reviewed full SHA or choose an allowed component.

8. Reliability, rate limits, and billing only where they cause failure

Trigger loops and overly broad path/event definitions can create many runs. Public standard hosted runners are currently free, but runaway automation still consumes concurrency, API rate limit, reviewer attention, and log retention. In private repositories, hosted-runner usage also interacts with included quota/billing. Design filters and cancellation/concurrency intentionally in later chapters rather than using “free” as a reason to ignore execution volume.

9. Lesson summary

A missing workflow, a missing run, a 403, a queued job, a dependency-policy rejection, and a failing test are different failure classes. Preserve repository/event/ref/workflow/job evidence first. Least privilege, safe input handling, selective logs, and runner/dependency policy are part of correctness, not optional security decoration.

Knowledge check

Further reading — current official GitHub sources

• GitHub Docs — Understanding GitHub Actions
• GitHub Docs — Workflow syntax
• GitHub Docs — Events that trigger workflows
• GitHub Docs — Contexts reference
• GitHub Docs — GITHUB_TOKEN
• GitHub Docs — Secure use reference
• GitHub CLI — gh run list
• GitHub CLI — gh run view
• GitHub REST API — workflow runs (2026-03-10)
• GitHub Docs — Script injections
• GitHub Docs — Secure use reference
• GitHub Docs — Actions settings and allowed actions
• GitHub Docs — Actions billing