GitHub Actions Foundations: Workflows, Events, YAML, Permissions, and Execution Model: Concepts, Architecture, and Mental Model

1. The problem: repository events can become code execution

Chapters 1–12 treated GitHub mostly as hosted state: repositories, Issues, Projects, pull requests, rules, releases, and APIs. GitHub Actions changes the risk model because a repository event can cause code to execute on a machine. That execution may receive a repository-scoped credential, read repository contents, write logs, call APIs, download dependencies, or—if you grant it—mutate GitHub state.

A green check therefore means more than “some YAML parsed.” It means GitHub selected a workflow definition, created a run from an event, scheduled one or more jobs, acquired runners, issued credentials according to policy, executed steps, and recorded conclusions. A reliable operator can reconstruct each link in that chain.

2. Mental model: event → run → jobs → runners → evidence

              flowchart TD
                E["GitHub event"] --> W["Workflow definition"]
                W --> R["Workflow run"]
                R --> J1["Job: validate"]
                R --> J2["Job: other"]
                J1 --> H["GitHub-hosted runner"]
                J2 --> S["Self-hosted runner optional"]
                H --> L["Steps + logs + conclusion"]
                S --> L
                T["GITHUB_TOKEN per job"] --> J1
                T2["GITHUB_TOKEN per job"] --> J2
            

The nodes are different resource types. The workflow definition is a YAML file committed in Git. A workflow run, job, step status, annotation, and log are GitHub Actions objects. A runner is execution infrastructure. GITHUB_TOKEN is a credential minted for a job. The arrows are scheduling and authorization relationships, not Git history edges.

3. Run identity: event, ref, source SHA, and workflow-file SHA

Do not reduce a run to “the commit that ran.” GitHub exposes several related identities because event semantics differ. For example, github.sha is event-dependent; on pull-request workflows it is not safe to assume it always means the contributor branch tip. The github.workflow_ref and github.workflow_sha identify the workflow definition itself.

A production incident report should record at least the run ID, event, headSha reported by GitHub, workflow path, attempt number, and exact repository. For a critical build, also record the commit that supplied the workflow definition and the immutable versions of external actions.

4. Three languages in one file: YAML, Actions expressions, and the runner shell

Workflow YAML is parsed as configuration. GitHub expressions such as ${{ github.ref }} are evaluated by the Actions system in supported fields. Shell syntax inside run: is processed on the runner. Mixing these layers is a common source of both bugs and security problems.

name: Layered example
on: workflow_dispatch

permissions:
  contents: read

jobs:
  explain:
    if: ${{ github.repository_owner != '' }}
    runs-on: ubuntu-latest
    steps:
      - name: Print a value safely
        env:
          EVENT_NAME: ${{ github.event_name }}
        run: |
          printf 'event=%s\n' "$EVENT_NAME"

Here YAML establishes structure. The if expression is evaluated as an Actions condition. The event value is copied into an environment variable, and Bash expands $EVENT_NAME at runtime. This environment-variable pattern is also safer than embedding attacker-controlled context strings directly into a shell program.

5. Execution identity: GITHUB_TOKEN is job-scoped authorization

When Actions starts a job, GitHub creates a unique GITHUB_TOKEN. GitHub documents it as a GitHub App installation access token whose permissions are limited to the workflow repository. It expires when the job ends (subject to the documented maximum lifetime). The token is available as secrets.GITHUB_TOKEN and through github.token.

The security rule for this course is simple: declare permissions explicitly. Do not depend on repository/org defaults when a workflow’s intended access is known. A validation-only workflow normally begins with:

permissions:
  contents: read

When you specify permissions, omitted permission categories are treated as no access. That property makes the workflow file itself an authorization contract. Repository or organization policy can further reduce what is actually granted; YAML cannot override a stronger platform restriction.

6. Trust boundaries: code, payload, secrets, dependencies, and runners

Anything an external contributor can influence should be treated as untrusted. That includes pull-request titles/bodies, branch names, commit messages, repository content checked out from a fork, and artifacts produced by an untrusted run. GitHub explicitly warns that strings from the github context can become script-injection vectors if interpolated directly into shell code.

7. GitHub-hosted versus self-hosted runners

A GitHub-hosted job normally receives a fresh VM for that job. A self-hosted runner is infrastructure you deploy and maintain; it can retain state and network reachability between jobs. That is not merely a cost or performance choice—it is a trust decision.

Later chapters cover runners deeply. For now remember the rule: execution environment is part of the security boundary. “The workflow file is safe” does not mean “the machine is safe.”

8. Read-only inspection before you create any workflow

Chapters 1–12 established an inspect-before-mutate habit. Keep it. On a repository that may or may not have Actions enabled, start with read-only CLI/API state.

REPO="OWNER/REPO"

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

gh run list -R "$REPO" --limit 10 \
  --json databaseId,workflowName,event,status,conclusion,headBranch,headSha,url

gh api --paginate \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "repos/$REPO/actions/runs?per_page=10" \
  --jq '.workflow_runs[] | {id,event,status,conclusion,head_sha,html_url}'

An empty list can mean “no workflow/run exists”; an authorization failure is different; an absent Actions tab can reflect policy. Keep those states distinct rather than treating every empty screen as a workflow bug.

9. DevOps operating model

In a production GitHub operating model, a workflow run is evidence only when you can bind it to the repository, event, exact source identity, workflow definition, runner class, permissions, dependency versions, and logs. Those dimensions are the bridge from Chapters 7–12 (change control) into Chapters 13–20 (execution and delivery control).

10. Lesson summary

GitHub Actions is an event-driven execution system layered on repository state. Workflow YAML is versioned in Git, but runs/jobs/logs are hosted Actions objects. Event/ref/SHA semantics are event-specific; workflow-file identity is separately observable. Each job receives a repository-scoped GitHub App installation token whose access should be declared explicitly. Runner trust and untrusted input matter as much as YAML correctness.

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 — GitHub-hosted runners
• GitHub Docs — Self-hosted runners
• GitHub Docs — Actions billing