3.2 Contexts, Expressions & Functions

Contexts, Expressions & Functions

GitHub Actions workflows are not static scripts; they are dynamic, programmable automation pipelines. Through contexts, expressions, and built-in functions, you can interrogate runtime metadata, evaluate boolean logic, manipulate strings and JSON payloads, and dynamically control step and job execution.

---

1. GitHub Actions Contexts Architecture

A context is a structured collection of variables and metadata exposed as a JSON object during workflow execution. Contexts provide information about the triggering webhook event, the repository, the runner environment, secrets, configuration variables, and upstream job/step outputs.

+-----------------------------------------------------------------------------+
|                        GITHUB ACTIONS CONTEXT MODEL                         |
|                                                                             |
|   [ Workflow Execution Engine ]                                             |
|         |                                                                   |
|         +---> github   : Event payload, ref, actor, repository, SHA         |
|         +---> env      : Workflow / Job / Step environment variables        |
|         +---> vars     : Non-sensitive configuration variables              |
|         +---> secrets  : Encrypted repository / org / env secrets           |
|         +---> steps    : Step execution status and outputs                  |
|         +---> runner   : OS, architecture, temp path, tool cache            |
|         +---> needs    : Upstream job outputs and status results            |
|         +---> matrix   : Current matrix permutation properties              |
|         +---> strategy : Matrix fail-fast and max-parallel settings         |
|         +---> inputs   : Workflow dispatch / reusable workflow inputs       |
+-----------------------------------------------------------------------------+

Comprehensive Context Reference Table

---

2. Expression Syntax & Evaluation Rules

Expressions are written using the format ${{ <expression> }}. They can contain literal values, context references, mathematical operators, logical operators, and built-in functions.

steps:
  - name: Conditional Execution Example
    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
    run: ./deploy.sh

The if: Condition Special Syntax Rule

In an if: key at the job or step level, the ${{ }} wrapper is optional unless you are concatenating an expression with literal strings:

# Both of these are 100% valid and identical in behavior:
if: github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'do-not-merge')
if: ${{ github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'do-not-merge') }}

Literal Data Types in Expressions:

• Boolean: true, false (case-insensitive in expression engine)
• Null: null
• Number: 42, 3.14159, -10, 0xFF
• String: Single quotes must be used for literal strings: 'production', 'ubuntu-latest'. Double quotes inside ${{ 'string' }} cause syntax errors. To escape a literal single quote inside a string, use two single quotes: 'It''s a release build'.

---

3. Built-In Functions Catalog

GitHub Actions provides a rich suite of built-in functions for string matching, formatting, array inspection, JSON handling, and file fingerprinting.

String & Array Manipulation Functions

1. contains(search, item) Returns true if search contains item. If search is an array, it checks for item presence. If search is a string, it checks for substring occurrence. Comparison is case-insensitive.

   # Checks if branch name contains 'feature/'
   if: contains(github.ref, 'feature/')
   # Checks if PR has 'security' label
   if: contains(github.event.pull_request.labels.*.name, 'security')
   

2. startsWith(searchString, searchValue) & endsWith(searchString, searchValue) Checks if a string starts or ends with a given substring (case-insensitive).

   if: startsWith(github.ref, 'refs/tags/v')
   if: endsWith(github.actor, '-bot')
   

3. format(string, val1, val2, ...) Replaces {0}, {1}, etc., in the template string with supplied arguments.

   run: echo "${{ format('Deploying {0} to {1} cluster', github.sha, vars.CLUSTER_NAME) }}"
   

4. join(array, optional_separator) Concatenates array elements into a single string. If separator is omitted, commas are used.

   # If matrix.targets = ['x86_64', 'arm64'], join yields 'x86_64;arm64'
   run: ./build --targets "${{ join(matrix.targets, ';') }}"
   

Data Transformation Functions: toJSON & fromJSON

1. toJSON(value) Converts any context, object, or array into a pretty-printed JSON string. Invaluable for debugging and inspecting webhook payloads.

   - name: Dump GitHub Context for Debugging
     run: echo '${{ toJSON(github) }}'
   

2. fromJSON(str) Parses a JSON string into a structured data type (object or array), or converts JSON literals ('true', '42') into boolean/numeric primitives.

   # Accessing properties from a JSON string output
   - name: Parse Metadata
     run: echo "Deployed to: ${{ fromJSON(needs.setup.outputs.config_json).region }}"
   

Integrity & Caching Function: hashFiles()

hashFiles(path1, path2, ...) accepts one or more comma-separated file paths or glob patterns and returns a single SHA-256 hash of the matched files' contents. If no files match or the path does not exist, it returns an empty string "".

- name: Cache Node Modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}
    restore-keys: |
      ${{ runner.os }}-node-

---

4. Operator Precedence & Evaluation Truth Table

GitHub Actions evaluates expressions using standard operator precedence (highest to lowest):

1. () (Grouping)
2. ! (Logical NOT)
3. <, <=, >, >= (Relational operators)
4. ==, != (Equality operators)
5. && (Logical AND)
6. || (Logical OR)

Expression Evaluation & Truthiness Rules

---

5. End-to-End Practical YAML Workflow

name: Advanced Context & Expression Pipeline

on:
  pull_request:
    types: [opened, synchronize, labeled]
  push:
    branches: [main]

jobs:
  evaluate-environment:
    runs-on: ubuntu-latest
    outputs:
      is_release: ${{ steps.check-release.outputs.is_release }}
      target_env: ${{ steps.check-release.outputs.target_env }}
    steps:
      - name: Inspect Runner Context
        run: |
          echo "Operating System: ${{ runner.os }}"
          echo "Architecture: ${{ runner.arch }}"
          echo "Temp Directory: ${{ runner.temp }}"

      - name: Determine Deployment Target
        id: check-release
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" && "${{ github.event_name }}" == "push" ]]; then
            echo "is_release=true" >> "$GITHUB_OUTPUT"
            echo "target_env=production" >> "$GITHUB_OUTPUT"
          else
            echo "is_release=false" >> "$GITHUB_OUTPUT"
            echo "target_env=preview" >> "$GITHUB_OUTPUT"
          fi

  conditional-step-demo:
    needs: evaluate-environment
    runs-on: ${{ fromJSON('["ubuntu-latest", "ubuntu-24.04"]')[0] }}
    steps:
      - name: Production Only Step
        # Demonstrates unquoted if expression with boolean coercion
        if: needs.evaluate-environment.outputs.is_release == 'true' && github.actor != 'dependabot[bot]'
        run: echo "Executing authorized production release triggered by ${{ github.actor }}"

      - name: Formatting Notification Message
        run: |
          MSG="${{ format('Run {0} for commit {1} targeting {2}', github.run_number, github.sha, needs.evaluate-environment.outputs.target_env) }}"
          echo "Formatted Message: $MSG"