Working with Expression Functions

1. Using contains() Function

Expression	Description	Examples
contains(source, searchValue)	Checks if a string contains a substring	`contains('Hello World', 'World') // true`
contains(source, searchValue)	Case-sensitive check	`contains('Hello World', 'world') // false`

Note: The contains() function is case-sensitive and works with strings only.

2. Using startsWith() Function

Expression	Description	Example
startsWith()	Checks if a string starts with the specified substring	`startsWith('Hello', 'He')` returns `true`

Example: Using startsWith() in a GitHub Actions Workflow

name: Check Branch Name
on:
  push:
    branches:
      - main
jobs:
  check-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Check if branch starts with 'release'
        if: ${{ startsWith(github.ref, 'refs/heads/release') }}
        run: echo "This is a release branch"

3. Using endsWith() Function

Expression	Description	Example
endsWith()	Checks if a string ends with the specified suffix.	`'hello world'.endsWith('world')` returns `true`
endsWith(str, suffix)	Checks if a string ends with the specified suffix.	`'GitHub Actions'.endsWith('Actions')` returns `true`

Example: Using endsWith() in a Condition

on:
  push:
    branches:
      - '*'

jobs:
  check-branch:
    runs-on: ubuntu-latest
    if: endsWith(github.ref, '-feature')
    steps:
      - name: Check branch name
        run: echo "This is a feature branch"

4. Using format() Function

Parameter	Description	Example
format()	Formats a string using placeholders	`format('Hello {0}, you are {1} years old', 'John', 25)`

Example: Using format() in a GitHub Action

name: Format Example
on:
  push:
    branches: [ main ]
jobs:
  format-job:
    runs-on: ubuntu-latest
    steps:
      - name: Set formatted message
        id: format-step
        run: |
          echo "message=$(echo 'Hello {0}, you are {1} years old' | sed 's/{0}/John/g; s/{1}/25/g')" >> $GITHUB_ENV
      - name: Output formatted message
        run: echo "Formatted message: ${{ env.message }}"

5. Using join() Function

Parameter	Description	Example
join()	Joins array elements into a string with a specified separator	`join(array, separator)`

Example: Joining Array Elements

const items = ['apple', 'banana', 'cherry'];
const result = join(items, ', ');
// Result: "apple, banana, cherry"

Example: Joining with Custom Separator

const tags = ['web', 'dev', 'ops'];
const joined = join(tags, ' | ');
// Result: "web | dev | ops"

6. Using toJSON() Function

Function	Description	Usage
toJSON()	Converts an object to its JSON string representation	`JSON.stringify(object)`

Example: Converting Object to JSON String

{
  "name": "John",
  "age": 30
}

Note: The toJSON() function is often used in JavaScript to customize how objects are serialized into JSON format.

7. Using fromJSON() Function

Function	Description	Usage
fromJSON()	Converts a JSON string into a JavaScript object or value	`fromJSON(string)`

Example: Parsing JSON String

const jsonStr = '{"name": "John", "age": 30}';
const parsedObj = fromJSON(jsonStr);
console.log(parsedObj.name); // Output: John

Note: The fromJSON() function is useful for converting JSON strings into JavaScript objects within GitHub Actions workflows.

8. Using hashFiles() Function

The hashFiles() function is a built-in expression function in GitHub Actions that generates a SHA256 hash of the content of files matching a specified pattern. It is commonly used to cache dependencies or detect changes in files.

Parameter	Description	Example
pattern	File path pattern to match files (supports glob patterns)	`**/package-lock.json`

Example: Caching Dependencies Based on Lock File Changes

steps:
  - name: Cache node modules
    uses: actions/cache@v3
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Note: The hashFiles() function is evaluated at runtime, so it will reflect any changes in the files matching the pattern.

9. Using success() Function

Expression	Description	Return Value
success()	Checks if all previous job steps have succeeded or are skipped	`true` if all previous steps succeeded or were skipped, otherwise `false`

Example: Using success() in a conditional

steps:
  - name: Run tests
    run: npm test
  - name: Upload coverage
    if: success()
    run: npm run upload-coverage

10. Using failure() Function

Expression	Description	Return Value
failure()	Checks if any previous job in the workflow has failed	`true` if any previous job failed, otherwise `false`

Example: Using failure() in a conditional

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build
        run: echo "Building..."
  test:
    runs-on: ubuntu-latest
    needs: build
    if: failure()
    steps:
      - name: Run tests on failure
        run: echo "Running tests after build failure"

11. Using always() Function

Function	Description	Usage
always()	Always returns true, regardless of the outcome of a previous step or job.	`if: always()`

Example: Using always() in a job

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Run a step that might fail
        run: echo "This might fail"
        continue-on-error: true

      - name: Always run this step
        if: always()
        run: echo "This runs no matter what"

12. Using cancelled() Function

Expression	Description	Return Value
cancelled()	Checks if the workflow run was cancelled	`true` if the workflow was cancelled, otherwise `false`

Example: Using cancelled() in a conditional

name: Check Workflow Status
on: [push]

jobs:
  check-status:
    runs-on: ubuntu-latest
    steps:
      - name: Check if workflow was cancelled
        if: ${{ cancelled() }}
        run: |
          echo "Workflow was cancelled"