GitHub Actions/Workflow Syntax/Jobs: needs, if, matrix, outputs

ReferenceUpdated 3 weeks ago

Jobs: needs, if, matrix, outputs

Control how jobs relate: ordering with needs, conditions with if, fan-out with matrix, passing values with outputs, plus services, timeouts and environments.

#github-actions #jobs #matrix

Order and conditions

needs + if

YAML

1jobs:

2 test:

3 runs-on: ubuntu-latest

4 steps: [...]

6 build:

7 needs: test # wait for test to succeed

8 runs-on: ubuntu-latest

9 steps: [...]

11 deploy:

12 needs: [test, build] # wait for both

13 if: github.ref == 'refs/heads/main' # only on main

14 environment: production # secrets + approval rules of that env

15 runs-on: ubuntu-latest

16 steps: [...]

18 notify:

19 needs: deploy

20 if: failure() # runs only when something failed

21 runs-on: ubuntu-latest

22 steps:

23 - run: echo "deploy failed"

Matrix (fan-out)

One job definition, many parallel variants. Each combination is a separate job.

strategy.matrix

YAML

1test:

2 runs-on: ${{ matrix.os }}

3 strategy:

4 fail-fast: false # let the other variants finish

5 max-parallel: 4

6 matrix:

7 os: [ubuntu-latest, windows-latest]

8 java: ['21', '25']

9 exclude:

10 - { os: windows-latest, java: '21' }

11 steps:

12 - uses: actions/checkout@v7

13 - uses: actions/setup-java@v6

14 with:

15 distribution: temurin

16 java-version: ${{ matrix.java }}

17 cache: maven

18 - run: mvn -B verify

Pass values between jobs

step output → job output → needs

YAML

1build:

2 runs-on: ubuntu-latest

3 outputs:

4 version: ${{ steps.ver.outputs.version }} # expose to other jobs

5 steps:

6 - id: ver # id makes it addressable

7 run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"

9deploy:

10 needs: build

11 runs-on: ubuntu-latest

12 steps:

13 - run: echo "Deploying ${{ needs.build.outputs.version }}"

Service containers

Real databases for integration tests, reachable on localhost.

services

YAML

1integration:

2 runs-on: ubuntu-latest

3 services:

4 postgres:

5 image: postgres:17

6 env: { POSTGRES_PASSWORD: test, POSTGRES_DB: app }

7 ports: ['5432:5432']

8 options: >-

9 --health-cmd "pg_isready -U postgres"

10 --health-interval 5s --health-retries 10

11 redis:

12 image: redis:7

13 ports: ['6379:6379']

14 steps:

15 - uses: actions/checkout@v7

16 - run: mvn -B verify -Dspring.datasource.url=jdbc:postgresql://localhost:5432/app

GitHub Actions/Workflow Syntax/Jobs: needs, if, matrix, outputs

ReferenceUpdated 3 weeks ago

Jobs: needs, if, matrix, outputs

Control how jobs relate: ordering with needs, conditions with if, fan-out with matrix, passing values with outputs, plus services, timeouts and environments.

#github-actions #jobs #matrix

Order and conditions

needs + if

YAML

1jobs:

2 test:

3 runs-on: ubuntu-latest

4 steps: [...]

6 build:

7 needs: test # wait for test to succeed

8 runs-on: ubuntu-latest

9 steps: [...]

11 deploy:

12 needs: [test, build] # wait for both

13 if: github.ref == 'refs/heads/main' # only on main

14 environment: production # secrets + approval rules of that env

15 runs-on: ubuntu-latest

16 steps: [...]

18 notify:

19 needs: deploy

20 if: failure() # runs only when something failed

21 runs-on: ubuntu-latest

22 steps:

23 - run: echo "deploy failed"

Matrix (fan-out)

One job definition, many parallel variants. Each combination is a separate job.

strategy.matrix

YAML

1test:

2 runs-on: ${{ matrix.os }}

3 strategy:

4 fail-fast: false # let the other variants finish

5 max-parallel: 4

6 matrix:

7 os: [ubuntu-latest, windows-latest]

8 java: ['21', '25']

9 exclude:

10 - { os: windows-latest, java: '21' }

11 steps:

12 - uses: actions/checkout@v7

13 - uses: actions/setup-java@v6

14 with:

15 distribution: temurin

16 java-version: ${{ matrix.java }}

17 cache: maven

18 - run: mvn -B verify

Pass values between jobs

step output → job output → needs

YAML

1build:

2 runs-on: ubuntu-latest

3 outputs:

4 version: ${{ steps.ver.outputs.version }} # expose to other jobs

5 steps:

6 - id: ver # id makes it addressable

7 run: echo "version=1.4.${{ github.run_number }}" >> "$GITHUB_OUTPUT"

9deploy:

10 needs: build

11 runs-on: ubuntu-latest

12 steps:

13 - run: echo "Deploying ${{ needs.build.outputs.version }}"

Service containers

Real databases for integration tests, reachable on localhost.

services

YAML

1integration:

2 runs-on: ubuntu-latest

3 services:

4 postgres:

5 image: postgres:17

6 env: { POSTGRES_PASSWORD: test, POSTGRES_DB: app }

7 ports: ['5432:5432']

8 options: >-

9 --health-cmd "pg_isready -U postgres"

10 --health-interval 5s --health-retries 10

11 redis:

12 image: redis:7

13 ports: ['6379:6379']

14 steps:

15 - uses: actions/checkout@v7

16 - run: mvn -B verify -Dspring.datasource.url=jdbc:postgresql://localhost:5432/app