Configuring Jobs

This document introduces how to define job tasks, including the runtime 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 runtime environment, timeout, environment variables, concurrency control, matrix strategy, etc.

Prerequisites

• Basic understanding of workflow structure.
• Identified the required runtime environment (Runner tag) 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 Guide

runs-on Runtime 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 combination of self-hosted + custom tags.

needs Dependencies

Use needs to configure dependencies between jobs, and the current job will only execute 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 a condition to prevent a job from running unless a certain condition is met. You can use any supported context and expression to create a condition. 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

Job-level env 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 must use if conditions to determine whether to continue).

Frequently Asked Questions

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

A: AtomGit's hosted resource pool tags use the three-part format {os}-{version},{arch},{flavor}, providing 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. When needs is configured, they are executed in 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.