Contexts & Expressions

~13 min · context, expressions, templating

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

${{ ... }} is your templating engine

The expression syntax ${{ ... }} evaluates inside YAML strings and is how you do conditionals, lookups, and string manipulation in workflows.

The contexts

github — repo, ref, sha, actor, event, workflow info.
env — env vars at the current scope.
vars — repo/org/env variables.
secrets — repo/org/env secrets.
job — info about the current job.
steps — outputs from previous steps in this job.
matrix — current matrix cell's values.
needs — outputs of needs: jobs.
inputs — inputs from workflow_dispatch or workflow_call.
runner — info about the runner (OS, arch, temp dir).

Operators and functions

Comparisons: ==, !=, <, <=, >, >=.
Logic: &&, ||, !.
Common functions: contains(haystack, needle), startsWith(s, prefix), endsWith(s, suffix), format('hello {0}', name), fromJSON(s), toJSON(obj), hashFiles('**/lockfile').
Status: success(), failure(), cancelled(), always().

Code

Common conditional expressions·yaml

      # Run only on main
      - if: github.ref == 'refs/heads/main'
        run: ./deploy.sh

      # Run only on tag pushes
      - if: startsWith(github.ref, 'refs/tags/v')
        run: ./release.sh

      # Run only when label 'deploy' is on the PR
      - if: github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')
        run: ./preview-deploy.sh

      # Always run cleanup, even on failure
      - if: always()
        run: ./cleanup.sh

      # Use a previous step's output
      - id: meta
        run: echo "sha=${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
      - run: echo "Built ${{ steps.meta.outputs.sha }}"

External links

Exercise

Pick a workflow with a deploy job. Add an if: guard that runs deploy only when github.ref == 'refs/heads/main' && github.event_name == 'push'. Verify it skips on PRs.