Configuration Steps

This document introduces how to configure properties such as command execution, Action calls, environment variables, conditional execution, timeout, and error tolerance in workflow steps (Step).

When you need to define specific execution steps within a job, including running scripts, calling Action plugins, setting environment variables, conditional execution, etc.

Prerequisites

• A job has been defined and runs-on has been specified.
• Understand the specific operation to be executed (script or Action plugin).

Quick Example

jobs:
  build:
    name: Build
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Checkout source code
        uses: checkout

      - name: Setup Node.js
        uses: setup-node
        with:
          node-version: "20"

      - name: Install and test
        run: |
          npm ci
          npm test

      - name: Print version
        env:
          APP_VERSION: "1.0.0"
        run: echo "version=$APP_VERSION"

Configuration Explanation

id Step Identifier

id is used to uniquely identify a step, and the output of this step can be referenced later using ${{ steps.<id>.outputs.<key> }}:

steps:
  - name: Run output
    id: version
    run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"
  - name: Print version
    run: echo "${{ steps.version.outputs.version }}"

name Step Display Name

name is the display name of the step in logs and interface:

steps:
  - name: Install dependencies
    run: npm install

uses Call Action Plugin

uses specifies the Action plugin to call, in the format {owner}/{repo}@{ref}:

steps:
  - name: Checkout source code
    uses: checkout

See Using Action Plugins for details.

with Pass Parameters

with is used to pass input parameters to the Action plugin:

steps:
  - name: setup node
    uses: setup-node
    with:
      node-version: "20"
      registry-url: "https://registry.npmjs.org"

run Execute Commands

run is used to execute shell commands, supporting single-line and multi-line:

Single-line command:

steps:
  - name: Single command
    run: echo "hello"

Multi-line command:

steps:
  - name: Multi-line commands
    run: |
      npm install
      npm run build
      npm test

shell Select Shell Type

shell specifies the shell type for executing commands, supporting bash, sh, python:

steps:
  - name: Run bash
    shell: bash
    run: Write-Host "Hello from bash"

steps:
  - name: Run Python
    shell: python
    run: echo "Hello from python"

working-directory Working Directory

working-directory specifies the working directory for the step (relative to the repository root):

steps:
  - name: checkout source code
    uses: checkout
  - name: Build frontend
    working-directory: frontend
    run: npm run build

AtomGit Action supports a three-level priority rule for working-directory:

Workflow level → Job level → Step level (priority from low to high)

defaults:
  run:
    shell: bash
    working-directory: project

jobs:
  build:
    name: Build
    runs-on: [ubuntu-latest, x64, small]
    defaults:
      run:
        shell: sh
        working-directory: src
    steps:
      - name: Echo sh
        run: echo "uses sh in src"
      - name: Run shell
        shell: bash
        run: echo "overrides to bash"

env Environment Variables

The env at the step level is only effective within that step:

steps:
  - name: Print env
    env:
      APP_ENV: staging
      DEBUG: true
    run: |
      echo "APP_ENV=$APP_ENV"
      echo "DEBUG=$DEBUG"

if Conditional Execution

The if at the step level controls whether the step is executed, supporting expressions and status functions:

steps:
  - name: Deploy only on main
    if: ${{ atomgit.ref == 'refs/heads/main' }}
    run: echo "deploy to production"

continue-on-error Step Error Tolerance

steps:
  - name: Maybe-fail step
    continue-on-error: true
    run: ./flaky-script.sh

After setting this, if the step fails, it will not cause the job to fail, and subsequent steps will still continue to execute.

timeout-minutes Step Timeout

steps:
  - name: Long running step
    timeout-minutes: 10
    run: ./slow-build.sh

By default, a step does not have an independent timeout limit (controlled by the job's timeout-minutes).

Frequently Asked Questions

Q: What is the difference between step-level env and job-level env?

A: The env at the job level is visible to all steps within the job; the env at the step level is only effective within that step. Step-level variables with the same name will override job-level variables.

Q: How to reference context variables in run commands?

A: Use ${{ }} expressions in YAML to reference them, such as ${{ atomgit.sha }}; use environment variables directly in shell commands, such as $ATOMGIT_SHA.