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
- Each layer has its own casing, and a mismatch is a fake. Events
snake_case(pull_request,check_run) · YAML keyskebab-case(runs-on,fail-fast,cancel-in-progress,paths-ignore) · context propertieslower.dot.snake(github.ref_name,github.run_number) · default env varsUPPER_SNAKE(GITHUB_REF,RUNNER_OS) · functions/toolkitcamelCase(startsWith(),fromJSON(),core.setFailed()). - Every key has one home level. Workflow:
on,permissions,env,defaults,concurrency. Job:runs-on,needs,strategy,services,environment,outputs, reusable-workflowuses. Step: actionuses,run,with,shell,id. (if,env,timeout-minutes,continue-on-errorappear at more than one level.) - 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. - Write via files, read via
noun.id.outputs.name.>> $GITHUB_ENV / OUTPUT / PATH / STEP_SUMMARY; readsteps.<id>.outputs.x,needs.<job>.outputs.x.::verb::survives only for logging (debug, notice, warning, error, group, add-mask).::set-*::is dead. - Two evaluation worlds.
${{ }}is evaluated by Actions before the runner;$VARby the shell on the runner.if:is always an expression; secrets aren't allowed directly in it. - Plural vs singular is fixed. Plural:
secrets,vars,steps,needs,inputs,outputs,jobs. Singular:github,env,runner,matrix,strategy,job. - 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
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)
# 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 stepruns:
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: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"
| Goal | Real syntax |
|---|---|
| Debug message (shows only with debug logging) | echo "::debug::text" |
| Error/warning/notice annotation on a file line | echo "::error file=app.js,line=10,col=5::text" |
| Mask a derived secret | echo "::add-mask::$VALUE" |
| Collapsible log group | echo "::group::Title" … echo "::endgroup::" |
| Env var for later steps | echo "NAME=value" >> "$GITHUB_ENV" |
| Step output | echo "name=value" >> "$GITHUB_OUTPUT" |
| Add to PATH | echo "/opt/tool/bin" >> "$GITHUB_PATH" |
| Job summary | echo "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 see | Where it's valid | Example |
|---|---|---|
$UPPER_CASE | in 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 }} | nowhere | mixes 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)
| Thing | Where |
|---|---|
| Environments + required reviewers + wait timer + branch/tag rules | Repository Settings › Environments |
| Step debug logs | Secret/variable ACTIONS_STEP_DEBUG=true (or Re-run › Enable debug logging) |
| Runner diagnostic logs | Secret/variable ACTIONS_RUNNER_DEBUG=true |
| Allowed actions policy, default GITHUB_TOKEN permissions, fork-PR approval | Org/Repo Settings › Actions › General |
| Secrets & variables | Repo, Environment, or Org (all / private / selected repos). No enterprise scope |
| Org workflow templates | Org .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 action | Action repo Settings › Actions › General › Access |
| Self-hosted runner logs | _diag/Runner_*.log, Worker_*.log on the machine |
6. Numbers worth knowing
| Fact | Value |
|---|---|
| Job waiting for approval fails after / max wait timer | 30 days |
| Artifact & log default retention | 90 days (set retention-days) |
| Cache evicted when unused for | 7 days |
GitHub-hosted job limit / default timeout-minutes | 6 h / 360 min |
| Max jobs per matrix | 256 |
| Cron shortest interval, time zone | 5 min, UTC |
| Scheduled workflows in inactive public repos | auto-disabled after 60 days |
| Secret size limit | 48 KB (bigger → encrypted file + passphrase secret) |
| Delete a workflow run | only when completed, needs write |
7. Trigger picker
| Stem says | Event |
|---|---|
| Run from the UI / API / CLI by a person | workflow_dispatch |
| Outside system calls the API | repository_dispatch |
| After another workflow finishes (don't edit it) | workflow_run |
| Third-party tool using the Checks API | check_run |
| Called by another workflow | workflow_call |
| PR got a label | pull_request: types: [labeled] |
| Issue or PR comment created | issue_comment |
| On a timer | schedule: - 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