Configuration Steps

Applicable Scenario: 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 operations to be executed (scripts or Action plugins).

Quick Example

jobs:
  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 Description

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:
  - 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 the interface:

steps:
  - name: Install dependencies
    run: npm install

uses Calling an 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 more details.

with Passing Parameters

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

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

run Executing Commands

run is used to execute shell commands, supporting both 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 Choosing Shell Type

shell specifies the shell type for executing commands, supporting bash, sh, pwsh, 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:
  - 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:
    defaults:
      run:
        shell: sh
        working-directory: src
    steps:
      - run: echo "uses sh in src"
      - 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"

steps:
  - name: Run on failure
    if: ${{ failed }}
    run: echo "previous step failed"

continue-on-error Step 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 has no independent timeout limit (controlled by the job's timeout-minutes).

Frequently Asked Questions

Q: What is the difference between the env of a step and the env of a job?

A: The env of a job is visible to all steps within that job; the env of a step 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.