actions/.serena/memories/github-workflow-expressions.md

GitHub Actions: Expressions and Contexts Reference

Expression Syntax

GitHub Actions expressions are written using ${{ <expression> }} syntax.

Literals

Supported Types:

• Boolean: true, false
• Null: null
• Number: Integer or floating-point
• String: Single or double quotes

Falsy Values:

• false, 0, -0, "", '', null

Truthy Values:

• true and all non-falsy values

Operators

Logical Operators

• ( ) - Grouping
• ! - NOT
• && - AND
• || - OR

Comparison Operators

• == - Equal (case-insensitive for strings)
• != - Not equal
• < - Less than
• <= - Less than or equal
• > - Greater than
• >= - Greater than or equal

Built-in Functions

String Functions

contains(search, item)        # Check if item exists in search string/array
startsWith(searchString, searchValue)  # Check prefix
endsWith(searchString, searchValue)    # Check suffix
format(string, replaceValue0, replaceValue1, ...)  # String formatting
join(array, optionalSeparator)  # Join array elements

Conversion Functions

toJSON(value)     # Convert to JSON string
fromJSON(value)   # Parse JSON string to object/type

Status Check Functions

success()    # True if no previous step failed
always()     # Always returns true, step always runs
cancelled()  # True if workflow cancelled
failure()    # True if any previous step failed

Hash Functions

hashFiles(path) # Generate SHA-256 hash of files matching pattern

Type Casting Rules

GitHub Actions performs loose equality comparisons:

• Numbers compared as floating-point
• Strings are case-insensitive when compared
• Type mismatches coerced to numbers:
  • Null → 0
  • Boolean → 1 (true) or 0 (false)
  • String → Parsed as number, or NaN if invalid
  • Array/Object → NaN
• Objects/arrays only equal if same instance reference

Best Practice: Use fromJSON() for precise numerical comparisons

Contexts

github Context

Workflow run and event information:

${{ github.event }}          # Full webhook payload
${{ github.actor }}          # User who triggered workflow
${{ github.ref }}            # Branch/tag reference (e.g., refs/heads/main)
${{ github.repository }}     # owner/repo format
${{ github.sha }}            # Commit SHA
${{ github.token }}          # Automatic GITHUB_TOKEN
${{ github.event_name }}     # Event that triggered workflow
${{ github.run_id }}         # Unique workflow run ID
${{ github.run_number }}     # Run number for this workflow
${{ github.job }}            # Job ID
${{ github.workflow }}       # Workflow name

env Context

Environment variables (workflow → job → step scope):

${{ env.MY_VARIABLE }}

vars Context

Configuration variables (organization/repo/environment level):

${{ vars.MY_CONFIG_VAR }}

secrets Context

Secret values (never printed to logs):

${{ secrets.MY_SECRET }}
${{ secrets.GITHUB_TOKEN }} # Automatic token

inputs Context

Inputs for reusable workflows or workflow_dispatch:

${{ inputs.deploy_target }}
${{ inputs.environment }}

steps Context

Information from previous steps in same job:

${{ steps.step_id.outputs.output_name }}
${{ steps.step_id.outcome }}     # success, failure, cancelled, skipped
${{ steps.step_id.conclusion }}  # success, failure, cancelled, skipped

job Context

Current job information:

${{ job.status }}           # success, failure, cancelled
${{ job.container.id }}     # Container ID if running in container
${{ job.services }}         # Service containers

runner Context

Runner environment details:

${{ runner.os }}            # Linux, Windows, macOS
${{ runner.arch }}          # X86, X64, ARM, ARM64
${{ runner.temp }}          # Temporary directory path
${{ runner.tool_cache }}    # Tool cache directory

needs Context

Outputs from jobs that current job depends on:

${{ needs.job_id.outputs.output_name }}
${{ needs.job_id.result }} # success, failure, cancelled, skipped

matrix Context

Matrix strategy values:

${{ matrix.os }}
${{ matrix.version }}

Common Patterns

Conditional Execution

if: github.ref == 'refs/heads/main'
if: success()
if: failure() && steps.test.outcome == 'failure'
if: always()

Ternary-like Logic

env:
  DEPLOY_ENV: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

String Manipulation

if: startsWith(github.ref, 'refs/tags/')
if: contains(github.event.head_commit.message, '[skip ci]')
if: endsWith(github.repository, '-prod')

Array/Object Access

${{ github.event.pull_request.title }}
${{ fromJSON(steps.output.outputs.json_data).key }}

Combining Conditions

if: github.event_name == 'push' && github.ref == 'refs/heads/main'
if: (github.event_name == 'pull_request' || github.event_name == 'push') && !cancelled()

Security Best Practices

1. Environment Variables for Shell Scripts:

   • ✅ Use env: block to pass inputs to shell scripts
   • ❌ Avoid direct ${{ inputs.* }} in shell commands (script injection risk)

2. Secret Masking:

   - run: echo "::add-mask::${{ secrets.MY_SECRET }}"
   

3. Input Validation:

   • Always validate user inputs before use
   • Use dedicated validation steps
   • Check for command injection patterns

4. Type Safety:

   • Use fromJSON() for structured data
   • Cast to expected types explicitly
   • Validate ranges and formats

Common Pitfalls

1. String Comparison Case Sensitivity:

   • GitHub Actions comparisons are case-insensitive
   • Be careful with exact matches

2. Type Coercion:

   • Empty string "" is falsy, not truthy
   • Number 0 is falsy
   • Use fromJSON() for precise comparisons

3. Object/Array Equality:

   • Objects/arrays compared by reference, not value
   • Use toJSON() to compare by value

4. Status Functions:

   • success() checks ALL previous steps
   • Use steps.id.outcome for specific step status

5. Context Availability:

   • Not all contexts available in all places
   • env context not available in if: at workflow/job level
   • secrets should never be used in if: conditions (may leak)

Examples from Project

Input Validation Pattern

- name: Validate Inputs
  env:
    VERSION: ${{ inputs.version }}
    EMAIL: ${{ inputs.email }}
  run: |
    if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+(\.[0-9]+)?$ ]]; then
      echo "::error::Invalid version: $VERSION"
      exit 1
    fi

Conditional Steps

- name: Deploy Production
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  run: ./deploy.sh production

- name: Cleanup
  if: always()
  run: ./cleanup.sh

Dynamic Outputs

- name: Set Environment
  id: env
  run: |
    if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
      echo "environment=production" >> $GITHUB_OUTPUT
    else
      echo "environment=staging" >> $GITHUB_OUTPUT
    fi

- name: Deploy
  run: ./deploy.sh ${{ steps.env.outputs.environment }}

References

• GitHub Actions Expressions
• GitHub Actions Contexts
• Project validation patterns in validate-inputs/ directory
• Security patterns documented in CLAUDE.md