Configuring Jobs

Use Case: When you need to define one or more jobs in a workflow, specifying the runtime environment, timeout, environment variables, concurrency control, matrix strategy, etc.

Prerequisites

• Basic understanding of the workflow structure.
• Determined the required runtime environment (Runner labels) for the job.

Quick Example

name: ci

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    timeout-minutes: 30
    env:
      APP_ENV: production
    steps:
      - uses: checkout
      - run: ./build.sh

Configuration Description

runs-on Runtime Environment

runs-on specifies the Runner environment for the job. The official resource pool labels of AtomGit Action use a three-part format: {os}-{version},{arch},{flavor}.

Part	Description	Example
{os}-{version}	Operating system and version	ubuntu-latest
{arch}	CPU architecture	x64, arm64
{flavor}	Resource specifications	small, medium, large

Full label example:

runs-on: [ubuntu-latest, x64, small]

The default label default corresponds to [ubuntu-latest, x64, small], that is:

runs-on: default

Self-hosted resource pool configuration:

runs-on:
  type: self-hosted
  group: my-runner-group
  labels:
    - linux
    - x64
    - gpu

Field	Description
type	Runner type, self-hosted indicates self-hosted
group	The group the Runner belongs to
labels	List of Runner labels used for matching

needs Dependencies

Use needs to configure dependencies between jobs, which means the current job will only run after the dependent job completes:

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "build"

  test:
    runs-on: [ubuntu-latest, x64, small]
    needs: build
    steps:
      - run: echo "test"

  deploy:
    runs-on: [ubuntu-latest, x64, small]
    needs:
      - test
      - lint
    steps:
      - run: echo "deploy"

if Conditional Execution

The if at the job level delays the execution of the entire job:

jobs:
  deploy:
    if: ${{ atomgit.ref == 'refs/heads/main' }}
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "deploy only on main"

timeout-minutes Timeout

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    timeout-minutes: 30
    steps:
      - run: ./build.sh

The default timeout is 360 minutes (6 hours). After the timeout, the job will be forcibly terminated.

env Environment Variables

The env at the job level is visible to all steps within the job:

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    env:
      APP_ENV: production
      BUILD_MODE: release
    steps:
      - run: echo "$APP_ENV"
      - run: echo "$BUILD_MODE"

outputs Output Parameters

A job can declare output parameters, mapping from step outputs:

jobs:
  prepare:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - id: version
        run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"

concurrency Concurrency Control

Concurrency control can also be configured at the job level:

jobs:
  deploy:
    runs-on: [ubuntu-latest, x64, small]
    concurrency:
      enable: true
      max: 1
      exceed-action: IGNORE
    steps:
      - run: echo "deploy"

strategy Matrix Strategy

See Configuring Matrix Builds.

continue-on-error Fault Tolerance

jobs:
  flaky-test:
    runs-on: [ubuntu-latest, x64, small]
    continue-on-error: true
    steps:
      - run: ./run-flaky-test.sh

After setting continue-on-error: true, even if the job fails, the workflow will not terminate (subsequent jobs depending on this job must use if conditions to determine whether to proceed).

Frequently Asked Questions

Q: Why is the format of the runs-on label three-part?

A: The official resource pool labels of AtomGit Action use a three-part format {os}-{version},{arch},{flavor}, providing more precise environment selection capabilities.

Q: Are jobs executed in parallel or sequentially by default?

A: Without needs configuration, multiple jobs are executed in parallel by default. With needs configuration, they are executed in the order of dependencies. You can also use the stages mechanism to achieve sequential execution between stages.

Q: What impact does continue-on-error have on subsequent jobs?

A: A job with continue-on-error: true will not prevent subsequent jobs from running even if it fails. However, in subsequent jobs that depend on this job, the condition if: ${{ success }} will not be satisfied. Use if: ${{ always }} to ensure execution.