Configuring Jobs

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

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 running environment (Runner tag) required for the job.

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 for the job. The official resource pool tags of AtomGit Action use a three-part format: {os}-{version},{arch},{flavor}.

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

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 example:

runs-on: [self-hosted, linux, x64]

self-hosted indicates self-hosted, and it matches the self-hosted resource pool through the method of self-hosted + custom tags.

needs Dependency

Use needs to configure dependencies between jobs. The current job will be executed only after the dependent job is completed:

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
      - build
    steps:
      - name: Run deploy
        run: echo "deploy"

if Conditional Execution

You can use conditional statements to prevent a job from running unless a certain condition is met. You can use any supported context and expression to create a conditional statement. For more information about the contexts supported by this reference, see Context Reference.

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

The 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"

strategy Matrix Strategy

See Configuring 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).

Common Issues

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

A: AtomGit managed resource pool tags use a 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 will not prevent subsequent jobs from running even if it fails.