GitHub Actions: Controlling Workflow and Job Execution

Controlling Execution Flow #

Using conditions to control job execution #

Step execution #

Example:

📄 File: .github/workflows/06-01-execution-flow.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

  test:
    runs-on: ubuntu-latest
    steps:
      - name: Get code
        uses: actions/checkout@v3
      - name: Cache dependencies
        id: cache
        uses: actions/cache@v3
        with:
          path: ~/06-react-exercise/.npm
          key: deps-node-modules-${{ hashFiles('**/package-lock.json') }}
      - name: Install dependencies
        run: npm ci
        working-directory: 06-react-exercise
      - name: Test code
        id: run-tests
        run: npm run test
        working-directory: 06-react-exercise
      - name: Upload test report
        if: ${{ failure() && steps.run-tests.outcome == 'failure' }}
        uses: actions/upload-artifact@v6
        with:
          name: test-report
          path: 06-react-exercise/test.json

Job execution #

Example:

📄 File: .github/workflows/06-01-execution-flow.yml

1
2
3
4
5
6
7
8

  build:
    needs: test
    # run this job even if the test job fails
    if: ${{ always() }}
    runs-on: ubuntu-latest
    steps:
      - name: Get code
        uses: actions/checkout@v3

Example: report job depends on lint and deploy jobs (needs: [lint, deploy]). It will still run if any of the jobs fails.

Hint:

More info:

• Using conditions to control job execution: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions
• Contexts: https://docs.github.com/en/actions/reference/workflows-and-actions/contexts
• Operators: https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#operators

Matrix Strategies #

How it Works #

Within a workflow file, you define a strategy block within a job, which contains a matrix key. Inside the matrix, you specify variables as keys and a list of values for each variable. GitHub Actions then automatically generates a separate, parallel job run for every possible combination of these values. 

Example:

This example tests a Node.js application on two different operating systems and two different Node.js versions:

jobs:
  build-and-test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node_version: [14, 16]
    steps:
      - uses: [actions/checkout@v4](github.com)
      - name: Use Node.js ${{ matrix.node_version }}
        uses: [actions/setup-node@v4](github.com)
        with:
          node-version: ${{ matrix.node_version }}
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

This configuration creates four jobs:

• os: ubuntu-latest, node_version: 14
• os: ubuntu-latest, node_version: 16
• os: windows-latest, node_version: 14
• os: windows-latest, node_version: 16

Inclusions and Exclusions in Matrix strategies #

Example:

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [14, 16]
    include:
      # Add a specific job for Node 18 on Ubuntu
      - os: ubuntu-latest
        node: 18
      # Add an extra property (e.g., 'test-suite') to the macos-latest/Node 16 job
      - os: macos-latest
        node: 16
        test-suite: "extended"

More info: Running variations of jobs in a workflow

🔥Re-Using Workflows #

Reusable workflows are YAML-formatted files, very similar to any other workflow file. As with other workflow files, you locate reusable workflows in the .github/workflows directory of a repository. Subdirectories of the workflows directory are not supported.

📄 File: cicd-gh-actions-course/.github/workflows/06-04-reusable-workflow.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

name: 06-04 Reusable Workflow
on:
  workflow_call:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Output information
        run: |
          echo "This is a reusable workflow example."
          echo "You can add deployment steps here."

Using inputs and secrets in a reusable workflow #

You can define inputs and secrets, which can be passed from the caller workflow and then used within the called workflow. There are three stages to using an input or a secret in a reusable workflow.

1. In the reusable workflow, use the inputs and secrets keywords to define inputs or secrets that will be passed from a caller workflow.

   on:
     workflow_call:
       inputs:
         config-path:
           required: true
           type: string
       secrets:
         personal_access_token:
           required: true
   

   For details of the syntax for defining inputs and secrets, see on.workflow_call.inputs and on.workflow_call.secrets.

2. In the reusable workflow, reference the input or secret that you defined in the on key in the previous step.

   Note

   If the secrets are inherited by using secrets: inherit in the calling workflow, you can reference them even if they are not explicitly defined in the on key. For more information, see Workflow syntax for GitHub Actions.

   jobs:
     reusable_workflow_job:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/labeler@v6
         with:
           repo-token: ${{ secrets.personal_access_token }}
           configuration-path: ${{ inputs.config-path }}
   

   In the example above, personal_access_token is a secret that’s defined at the repository or organization level.

   Warning

   Environment secrets cannot be passed from the caller workflow as on.workflow_call does not support the environment keyword. If you include environment in the reusable workflow at the job level, the environment secret will be used, and not the secret passed from the caller workflow. For more information, see Managing environments for deployment and Workflow syntax for GitHub Actions.

3. Pass the input or secret from the caller workflow.

   To pass named inputs to a called workflow, use the with keyword in a job. Use the secrets keyword to pass named secrets. For inputs, the data type of the input value must match the type specified in the called workflow (either boolean, number, or string).

1
2
3
4
5
6
7

    jobs:
      call-workflow-passing-data:
        uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
        with:
          config-path: .github/labeler.yml
        secrets:
          personal_access_token: ${{ secrets.token }}

Workflows that call reusable workflows in the same organization or enterprise can use the inherit keyword to implicitly pass the secrets.

1
2
3
4
5
6

	    jobs:
	      call-workflow-passing-data:
	        uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
	        with:
	          config-path: .github/labeler.yml
	        secrets: inherit

More info: Reuse workflows

» Sources « #

• Using conditions to control job execution: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions
• Contexts: https://docs.github.com/en/actions/reference/workflows-and-actions/contexts
• Operators: https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#operators

Matrix strategies:

• Running variations of jobs in a workflow
• Reuse workflows

» Disclaimer « #