Configuring Jobs
1. Defining Jobs
| Property | Description | Values |
|---|---|---|
| jobs.<job_id> | Unique identifier for the job | string |
| jobs.<job_id>.name | Human-readable name for the job | string |
| jobs.<job_id>.runs-on | Runner environment to execute the job | ubuntu-latest, macOS-latest, windows-latest, or custom runner labels |
| jobs.<job_id>.steps | List of steps to run in the job | array |
Example: Basic job definition
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
2. Naming Jobs
| Property | Values | Description |
|---|---|---|
| name | string |
The name of the job to display in the GitHub UI |
Example: Setting a Job Name
jobs:
build:
name: "Build and Test"
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v43. Setting Job Dependencies
| Property | Description | Values |
|---|---|---|
| needs | Defines job dependencies | string or array of job names |
| strategy | Defines job execution strategy | matrix, fail-fast |
Example: Basic Job Dependencies
jobs:
build:
runs-on: ubuntu-latest
test:
needs: build
runs-on: ubuntu-latest
Example: Multiple Job Dependencies
jobs:
build:
runs-on: ubuntu-latest
test:
needs: [build, deploy]
runs-on: ubuntu-latest
Note: Jobs run in parallel by default unless
needs is specified.
4. Running Jobs Conditionally
| Condition | Description | Example |
|---|---|---|
| if | Runs the job only if the specified condition evaluates to true | if: github.event_name == 'push' |
| continue-on-error | Allows the job to continue even if a step fails | continue-on-error: true |
| strategy.matrix | Runs the job multiple times with different matrix values | strategy: { matrix: { node-version: [12, 14, 16] } } |
Example: Conditional Job Execution
jobs:
build:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
Example: Matrix Strategy
jobs:
test:
strategy:
matrix:
node-version: [12, 14, 16]
runs-on: ubuntu-latest
steps:
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
5. Specifying Runner Type
| Runner Type | Description | Usage Example |
|---|---|---|
| ubuntu-latest | Latest Ubuntu Linux runner | runs-on: ubuntu-latest |
| ubuntu-22.04 | Ubuntu 22.04 Linux runner | runs-on: ubuntu-22.04 |
| ubuntu-20.04 | Ubuntu 20.04 Linux runner | runs-on: ubuntu-20.04 |
| macos-latest | Latest macOS runner | runs-on: macos-latest |
| macos-13 | macOS 13 runner | runs-on: macos-13 |
| windows-latest | Latest Windows runner | runs-on: windows-latest |
| windows-2022 | Windows Server 2022 runner | runs-on: windows-2022 |
Example: Using Ubuntu 22.04 runner
name: Build Job
on: [push]
jobs:
build:
runs-on: ubuntu-22.04
steps:
- name: Checkout code
uses: actions/checkout@v4
6. Configuring Job Timeout
| Property | Values | Description |
|---|---|---|
| timeout-minutes | 10 |
Maximum runtime in minutes before job is canceled |
Example: Setting Job Timeout
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Run build
run: |
echo "Building..."
sleep 600Note: The default timeout is 360 minutes (6 hours). Setting a shorter timeout helps prevent jobs from running indefinitely.
7. Setting Job Strategy
| Property | Description | Values | Notes |
|---|---|---|---|
| strategy.matrix | Defines a matrix of build configurations | { os: ['ubuntu-latest', 'windows-latest'], node-version: ['14', '16'] } |
Each combination runs as a separate job |
| strategy.max-parallel | Maximum number of jobs to run in parallel | 4 |
Defaults to 4; set to -1 for unlimited |
| strategy.fail-fast | Whether to fail the job if any matrix job fails | true, false |
Defaults to true |
Example: Matrix Strategy
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node-version: [14, 16, 18]
max-parallel: 2
fail-fast: false8. Setting Job Outputs
| Property | Description | Values |
|---|---|---|
| name | Name of the output | string |
| value | Value to set as output | string |
Example: Setting a Job Output
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Set output
id: set-output
run: echo "::set-output name=build-id::$(date +%s)"
- name: Use output
run: echo "Build ID is ${{ steps.set-output.outputs.build-id }}"
9. Configuring Job Environment
| Property | Description | Values |
|---|---|---|
| env | Environment variables available to all steps in the job | { "VAR1": "value1", "VAR2": "value2" } |
| env.<var>name</var> | Single environment variable | value |
| defaults | Default settings for all steps in the job | { "run": { "shell": "bash" } } |
| defaults.run | Default shell for all steps | bash, sh, pwsh, powershell |
| continue-on-error | Continue job execution even if a step fails | true, false |
| timeout-minutes | Maximum time in minutes before job is canceled | 10 |
Example: Setting Environment Variables
jobs:
build:
runs-on: ubuntu-latest
env:
NODE_VERSION: "18"
ENVIRONMENT: "production"
steps:
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
Example: Setting Default Shell
jobs:
build:
runs-on: ubuntu-latest
defaults:
run:
shell: pwsh
steps:
- name: Run PowerShell Script
run: |
Write-Host "Hello from PowerShell"
Note: Environment variables set in a job are not available to other jobs or workflows.
Warning: Setting
continue-on-error can mask failures and should be used carefully.
10. Using Job Containers
| Property | Description | Values |
|---|---|---|
| container | Specifies the container to use for the job | image: string |
| container.credentials | Credentials to access the container registry | username: string, password: string |
| container.env | Environment variables to set in the container | VAR_NAME: value |
| container.ports | Ports to expose from the container | hostPort:containerPort |
| container.volumes | Volumes to mount into the container | source: target |
Example: Using a PostgreSQL container
jobs:
test:
runs-on: ubuntu-latest
container:
image: postgres:13
env:
POSTGRES_PASSWORD: password
ports:
- 5432:5432
Note: The job will run in a separate container, and all steps will execute inside that container.
11. Configuring Service Containers
| Property | Description | Values | Notes |
|---|---|---|---|
| services | Defines the service containers to use in a job | {} |
Each service is a key-value pair where the key is the alias and value is the container configuration |
| services.<alias>.image | Image to use for the service container | string |
Required. Must be a valid Docker image name or path |
| services.<alias>.credentials | Credentials to access private registries | { username: string, password: string } |
Optional. Used for private Docker images |
| services.<alias>.env | Environment variables to set in the service container | { [key: string]: string } |
Optional. Can include secrets |
| services.<alias>.ports | Ports to expose from the service container | [{ host: number, container: number }] |
Optional. Maps host to container ports |
| services.<alias>.options | Additional Docker options to pass to the container | string |
Optional. Example: --health-cmd "pg_isready" |
Example: Using a PostgreSQL Service Container
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:13
env:
POSTGRES_PASSWORD: password123
POSTGRES_DB: testdb
options: "--health-cmd "pg_isready" --health-interval 10s --health-timeout 5s --health-retries 5"
ports:
- 5432:5432
Note: Service containers are started before the job runs and stopped after the job completes. They share the same network as the job container.
Warning: When using service containers, ensure that the container image is from a trusted source to avoid security risks.
12. Setting Job Concurrency
| Property | Description | Values |
|---|---|---|
| concurrency | Controls the concurrency of jobs | string or object |
Example: Setting concurrency with a string
jobs:
build:
runs-on: ubuntu-latest
concurrency: build-job
Example: Setting concurrency with an object
jobs:
build:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
Note: Setting
cancel-in-progress to true cancels any currently running jobs in the same concurrency group.