Configuring Conditional Execution

This document explains 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 prerequisite state checks.

When you need to control whether a job or step is executed based on conditions such as branch, Tag, event type, or the state of previous steps.

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	Condition for returning true
always	Regardless of the status	Returns true in any status

Example usage:

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 like resource cleanup or sending notifications.

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) }}
substring(str, start, len)	Substring extraction	${{ substring(atomgit.sha, 0, 7) }}
replace(str, old, new)	String replacement	${{ replace(atomgit.ref, 'refs/heads/', '') }}