Configure Jobs

This document introduces how to define job tasks (Jobs), including the running environment, dependencies, conditional execution, timeout, environment variables, output parameters, and fault tolerance configurations.

When you need to define one or more tasks in a workflow, specifying the running environment, timeout, environment variables, concurrency control, matrix strategy, etc.

Prerequisites

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

Quick Example

name: ci

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build
    runs-on: [ubuntu-latest, x64, small]
    timeout-minutes: 30
    env:
      APP_ENV: production
    steps:
      - name: Checkout source code
        uses: checkout
      - name: Run bash
        run: ./build.sh

Configuration Description

runs-on Running Environment

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

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

Complete tag example:

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

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

runs-on: default
# Equivalent to [ubuntu-latest, x64, small]

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	Group to which the Runner belongs
labels	List of Runner tags used for matching

needs Dependency

Use needs to configure dependencies between jobs. The current job will only execute after the dependent job completes:

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

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

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

if Conditional Execution

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

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

timeout-minutes Timeout

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

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

env Environment Variables

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

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

outputs Output Parameters

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

jobs:
  prepare:
    name: Prepare
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run output
        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:
    name: Deploy
    runs-on: [ubuntu-latest, x64, small]
    concurrency:
      enable: true
      max: 1
      exceed-action: IGNORE
    steps:
      - name: Run deploy
        run: echo "deploy"

strategy Matrix Strategy

See Configure Matrix Builds.

continue-on-error Fault Tolerance

jobs:
  flaky-test:
    name: Flaky Test
    runs-on: [ubuntu-latest, x64, small]
    continue-on-error: true
    steps:
      - name: Run bash
        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 need to use if conditions to determine whether to continue).

Frequently Asked Questions

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

A: The official resource pool tags of AtomGit Action use the three-part format {os}-{version},{arch},{flavor}, which provides more precise environment selection capabilities.

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

A: When there is no needs configuration, multiple jobs are executed in parallel by default. After configuring needs, they are executed in the order of dependencies. You can also use the stages stage 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 set will not prevent subsequent jobs from running even if it fails.