Skip to content

GH-200 syntax primer ​

About half the questions that trip people up come down to "which key goes where" or "does this name even exist?" Read the annotated workflow below slowly, once. After that, a syntax question is just checking each option against it.

How to use it on the exam: before judging what an option means, check that every key, command and function in it appears on this page. If one doesn't, that option is almost certainly the distractor. To practise, use the syntax drill.

0. Seven principles that generate the syntax ​

  1. Each layer has its own casing, and a mismatch is a fake. Events snake_case (pull_request, check_run) · YAML keys kebab-case (runs-on, fail-fast, cancel-in-progress, paths-ignore) · context properties lower.dot.snake (github.ref_name, github.run_number) · default env vars UPPER_SNAKE (GITHUB_REF, RUNNER_OS) · functions/toolkit camelCase (startsWith(), fromJSON(), core.setFailed()).
  2. Every key has one home level. Workflow: on, permissions, env, defaults, concurrency. Job: runs-on, needs, strategy, services, environment, outputs, reusable-workflow uses. Step: action uses, run, with, shell, id. (if, env, timeout-minutes, continue-on-error appear at more than one level.)
  3. Settings nest under what they configure. strategy › matrix/fail-fast/max-parallel; concurrency › group/cancel-in-progress; defaults › run › shell/working-directory; on › event › types/branches/paths; workflow_call › inputs/secrets/outputs.
  4. Write via files, read via noun.id.outputs.name. >> $GITHUB_ENV / OUTPUT / PATH / STEP_SUMMARY; read steps.<id>.outputs.x, needs.<job>.outputs.x. ::verb:: survives only for logging (debug, notice, warning, error, group, add-mask). ::set-*:: is dead.
  5. Two evaluation worlds. ${{ }} is evaluated by Actions before the runner; $VAR by the shell on the runner. if: is always an expression; secrets aren't allowed directly in it.
  6. Plural vs singular is fixed. Plural: secrets, vars, steps, needs, inputs, outputs, jobs. Singular: github, env, runner, matrix, strategy, job.
  7. Admin/security decisions live in Settings; YAML only names them. Reviewers, allowed actions, debug logging, retention defaults, runner groups → Settings/secrets. YAML: environment: prod, runs-on: group: x.

Real names are boring and literal (repository_dispatch, check_run). Fakes sound invented (webhook_dispatch, workflow_exec, pull_request_label, "Bash script action").

1. One workflow with every key that matters ​

yaml
name: CI                                  # optional display name
on:                                       # WHEN. Events only, nothing else lives here
  push:
    branches: [main, 'releases/**']       # branch names/globs. A branch named releases = 'releases'
    tags: ['v*']                          # only tags: → branch pushes won't trigger (and vice versa)
    paths-ignore: ['**.md']               # never paths + paths-ignore on the same event
  pull_request:
    types: [opened, synchronize, labeled] # default types = opened, synchronize, reopened
    paths: ['apps/**']                    # globs must match FILES: 'apps/**', not 'apps'
  schedule:
    - cron: '45 7 * * 3,6'                # list item under schedule; UTC; min hour dom month dow
  workflow_dispatch:                      # manual: UI button only once the file is on the default branch
    inputs:
      target:
        type: choice                      # string | boolean | number | choice | environment
        options: [dev, prod]
        required: true
  repository_dispatch:                    # external system: POST /repos/{o}/{r}/dispatches {event_type}
    types: [deploy]
  workflow_run:                           # after ANOTHER workflow
    workflows: [Build]
    types: [completed]
  check_run:                              # third-party tool via the Checks API
    types: [completed]
  workflow_call:                          # makes THIS file a reusable workflow
    inputs:
      env-name: { type: string, required: true }
    secrets:
      token: { required: true }
    outputs:
      version:
        value: ${{ jobs.build.outputs.version }}

permissions:                              # GITHUB_TOKEN scopes; anything unlisted → none
  contents: read
  id-token: write                         # OIDC to a cloud provider

env:                                      # workflow-level env (a MAP, never a name/value list)
  NODE_ENV: production

defaults:
  run:
    shell: bash                           # default shell; also working-directory
    working-directory: ./app

concurrency:                              # one running + one pending per group
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest                # self-hosted: [self-hosted, linux, x64, gpu] (ALL labels)
    timeout-minutes: 30                   # default 360
    env:                                  # job-level env
      LOG_LEVEL: debug
    services:                             # throwaway Redis/Postgres for this job (Linux runners)
      redis:
        image: redis
        ports: ['6379:6379']              # job on runner → localhost:6379
        options: --health-cmd "redis-cli ping"
    strategy:                             # strategy is the PARENT
      fail-fast: false                    # default true
      max-parallel: 2
      matrix:
        node: [18, 20]
        os: [ubuntu-latest, windows-latest]
        exclude:
          - { os: windows-latest, node: 18 }
    outputs:                              # job outputs → needs.build.outputs.version
      version: ${{ steps.ver.outputs.version }}
    steps:
      - uses: actions/checkout@v4         # action: owner/repo@ref (pin a full SHA for security)
      - uses: actions/setup-node@v4
        with:                             # `with:` = inputs to an action
          node-version: ${{ matrix.node }}   # read the matrix via the matrix context
          cache: npm
      - id: ver
        run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"   # OUTPUT → steps.ver.outputs.version
      - run: echo "BUILD_ID=42" >> "$GITHUB_ENV"         # ENV VAR → available from the NEXT step
      - run: echo "$BUILD_ID run $GITHUB_RUN_NUMBER"     # shell reads $VARS
      - name: Multi-line script
        run: |                            # literal block for several commands
          npm ci
          npm run build
      - shell: python                     # different interpreter for one step
        run: print("hi")
      - uses: actions/upload-artifact@v4  # files for later jobs / after the run (90 days)
        with:
          name: dist
          path: dist/
          retention-days: 5
      - run: echo "### Done ✅" >> "$GITHUB_STEP_SUMMARY"  # Markdown on the run summary page

  deploy:
    needs: build                          # jobs are parallel unless `needs:`
    if: github.ref_name == 'main'         # branch name = github.ref_name (NOT branch_name)
    runs-on: ubuntu-latest
    environment: production               # approval gate: repo Settings › Environments › reviewers
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist }
      - run: echo "Deploying ${{ needs.build.outputs.version }}"
        env:                              # step-level env (smallest scope)
          TITLE: ${{ github.event.pull_request.title }}   # untrusted input → env, then "$TITLE"

  call-shared:
    uses: octo-org/ci/.github/workflows/deploy.yml@v1   # reusable workflow = JOB-level uses
    with: { env-name: prod }
    secrets: inherit                      # or map: secrets: { token: ${{ secrets.X }} }

2. Three action types, three runs: blocks (all in action.yml / action.yaml) ​

yaml
# Required keys: name, description, runs.   Optional: author, inputs, outputs, branding
name: Greet
description: Says hello
inputs:
  who: { description: Who to greet, required: false, default: world }   # code reads INPUT_WHO / core.getInput('who')
outputs:
  time: { description: When, value: ${{ steps.t.outputs.time }} }    # value: only for composite
runs:
  using: composite            # SIMPLEST: bundles run steps + other actions
  steps:
    - id: t
      run: echo "time=$(date)" >> "$GITHUB_OUTPUT"
      shell: bash              # REQUIRED on every composite run step
yaml
runs:
  using: node20                # JavaScript: runs on Linux, Windows, macOS
  main: dist/index.js          # bundle deps with ncc (or commit node_modules)
  post: dist/cleanup.js        # optional pre:/post:
yaml
runs:
  using: docker                # Docker container: LINUX runners only, slowest start
  image: Dockerfile            # or docker://alpine:3.20
  args: [ "${{ inputs.who }}" ]

There are only these three types. "Bash script action", "Actionfile", metadata.yml and runs.using: container don't exist.

JavaScript toolkit (@actions/core): getInput, setOutput, setFailed, info, warning, error, setSecret, exportVariable, addPath. @actions/github: context, getOctokit. No setException, no core.action.*.

3. Workflow commands: echo "::name params::message" ​

GoalReal syntax
Debug message (shows only with debug logging)echo "::debug::text"
Error/warning/notice annotation on a file lineecho "::error file=app.js,line=10,col=5::text"
Mask a derived secretecho "::add-mask::$VALUE"
Collapsible log groupecho "::group::Title" … echo "::endgroup::"
Env var for later stepsecho "NAME=value" >> "$GITHUB_ENV"
Step outputecho "name=value" >> "$GITHUB_OUTPUT"
Add to PATHecho "/opt/tool/bin" >> "$GITHUB_PATH"
Job summaryecho "markdown" >> "$GITHUB_STEP_SUMMARY"

Two colons on each side of the name. No message= key. ::set-env, ::set-output and ::add-path are deprecated/disabled, so they're always the wrong answer.

4. Env vars vs contexts ​

You seeWhere it's validExample
$UPPER_CASEin the shell (run:)$GITHUB_RUN_NUMBER, $GITHUB_REF, $GITHUB_ACTOR, $GITHUB_REPOSITORY, $RUNNER_OS
${{ lower.dot.case }}in expressions (anywhere in YAML, incl. if:)${{ github.run_number }}, ${{ github.ref_name }}, ${{ runner.os }}, ${{ matrix.node }}, ${{ secrets.X }}, ${{ vars.X }}, ${{ env.X }}, ${{ inputs.x }}, ${{ needs.job.outputs.x }}, ${{ steps.id.outputs.x }}
${{ GITHUB_RUN_NUMBER }}, $github.run_number, ${{ var.X }}nowheremixes the two worlds → distractor

github.ref = refs/heads/main; github.ref_name = main. There's no github.branch, github.branch_name or github.ref.name. Secrets can't be used directly in if:; map to env: first. if: can drop the ${{ }}. Status functions: success() (default), always(), failure(), cancelled().

5. Where things are configured (not in YAML) ​

ThingWhere
Environments + required reviewers + wait timer + branch/tag rulesRepository Settings › Environments
Step debug logsSecret/variable ACTIONS_STEP_DEBUG=true (or Re-run › Enable debug logging)
Runner diagnostic logsSecret/variable ACTIONS_RUNNER_DEBUG=true
Allowed actions policy, default GITHUB_TOKEN permissions, fork-PR approvalOrg/Repo Settings › Actions › General
Secrets & variablesRepo, Environment, or Org (all / private / selected repos). No enterprise scope
Org workflow templatesOrg .github repo › workflow-templates/ + .properties.json
Runner groups (who may use runners) / labels (what a runner has)Org/Enterprise Settings › Actions › Runners
Share a private actionAction repo Settings › Actions › General › Access
Self-hosted runner logs_diag/Runner_*.log, Worker_*.log on the machine

6. Numbers worth knowing ​

FactValue
Job waiting for approval fails after / max wait timer30 days
Artifact & log default retention90 days (set retention-days)
Cache evicted when unused for7 days
GitHub-hosted job limit / default timeout-minutes6 h / 360 min
Max jobs per matrix256
Cron shortest interval, time zone5 min, UTC
Scheduled workflows in inactive public reposauto-disabled after 60 days
Secret size limit48 KB (bigger → encrypted file + passphrase secret)
Delete a workflow runonly when completed, needs write

7. Trigger picker ​

Stem saysEvent
Run from the UI / API / CLI by a personworkflow_dispatch
Outside system calls the APIrepository_dispatch
After another workflow finishes (don't edit it)workflow_run
Third-party tool using the Checks APIcheck_run
Called by another workflowworkflow_call
PR got a labelpull_request: types: [labeled]
Issue or PR comment createdissue_comment
On a timerschedule: - cron:

8. Names that do NOT exist (common distractors) ​

::set-env · ::set-output · :debug: · env: as - name/value · variables: / environment: as an env map · github.branch_name · github.branch.name · github.ref.name · ${{ GITHUB_RUN_NUMBER }} · self-hosted: as a job key · pull_request_label · workflow_exec · commit event · matrix-strategy · Bash script action · Actionfile · metadata.yml · core.setException · core.action.* · --actions-step-debug flag · "copy action" · "Marketplace partition" · actions/setup-docker · actions/debug-javascript

Personal study notes written from official documentation. Not affiliated with Microsoft or GitHub. Contains no exam questions.