Configuring Conditional Execution

This document introduces how to control whether a Job or Step is executed using if expressions and status functions, supporting scenarios such as branch judgment, event type filtering, and prior state checks.

When you need to control whether a job or step is executed based on conditions such as branch, Tag, event type, and prior step status.

Prerequisites

• Understand the atomgit context.
• Understand the expression syntax ${{ }}.

Quick Example

name: conditional-workflow

on:
  push:
    branches:
      - main
      - develop

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

      - name: Run only on main
        if: ${{ atomgit.ref == 'refs/heads/main' }}
        run: echo "main branch"

      - name: Run always
        if: ${{ always() }}
        run: echo "always runs"

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

Configuration Instructions

if Expression

The if condition uses the ${{ }} expression syntax:

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

# if at step level
steps:
  - name: Run on main
    if: ${{ atomgit.ref == 'refs/heads/main' }}
    run: echo "main branch"

Status Functions

Status functions are used to check the execution status of previous steps or jobs:

Function	Meaning	Conditions for Returning true
always	Regardless of the status	Returns true for any status

Usage example:

steps:
  - name: Build
    run: ./build.sh

  - name: Cleanup
    if: ${{ always() }}
    run: ./cleanup.sh

Important: if: ${{ always() }} forces the step to execute, even if the previous step fails or the workflow is canceled. It is suitable for scenarios such as resource cleanup and notification sending.

Conditional Expression Operators

Operator	Description	Example
==	Equal to	${{ atomgit.ref == 'refs/heads/main' }}
!=	Not equal to	${{ inputs.event_name != 'schedule' }}
> / >= / < / <=	Comparison	${{ inputs.count > 10 }}

String Functions

Function	Description	Example
contains(str, substr)	Contains substring	${{ contains(atomgit.ref, 'main') }}
startsWith(str, prefix)	Starts with prefix	${{ startsWith(atomgit.ref, 'refs/tags/') }}
endsWith(str, suffix)	Ends with suffix	${{ endsWith(atomgit.ref, '.0') }}
format(template, ...)	Formatting	${{ format('Hello {0}', atomgit.actor) }}
replace(str, substr, replacement )	Replacement	${{ replace('hello world', 'world', 'atomgit') }}
substring(str, start, end)	Substring	${{ substring('hello world', 0, 5) }}