Expressions

This document is the complete reference for AtomGit Action expressions, including literals, operators, state functions, string functions, and expression usage examples.

AtomGit Action uses the ${{ expression }} syntax to write expressions in workflows. Expressions can be used in if conditions, variable assignments, step parameters, etc.

3.1 Literals

Type	Syntax	Example
Boolean	true / false	${{ true }}
null	null	${{ null }}
Number	Integer or float	${{ 42 }}, ${{ 3.14 }}
String	Enclosed in single quotes	${{ 'hello' }}

3.2 Operators

Operator	Description	Example
==	Equal	${{ atomgit.ref == 'refs/heads/main' }}
!=	Not equal	${{ atomgit.event_name != 'schedule' }}
>	Greater than	${{ matrix.version > 12 }}
<	Less than	${{ matrix.version < 14 }}
>=	Greater than or equal to	${{ strategy.job-total >= 3 }}
<=	Less than or equal to	${{ inputs.count <= 10 }}

Operator precedence (from highest to lowest): `` → ! → <, >, <=, >= → ==, != → && → ||

3.3 Functions

Function	Description	Example
always	Always returns true regardless of previous steps	if: ${{ always() }}
contains(search, item)	Check if search contains item	${{ contains(atomgit.ref, 'release') }}
startsWith(search, prefix)	Check if search starts with prefix	${{ startsWith(atomgit.ref, 'refs/tags/') }}
endsWith(search, suffix)	Check if search ends with suffix	${{ endsWith(atomgit.ref_name, '.rc') }}
format(template, args...)	Format a string, 0/1... as placeholders	${{ format('Hello {0}, {1}!', name, role) }}
substring(str, start, len)	Extract a substring	${{ substring(atomgit.sha, 0, 7) }}
replace(str, old, new)	Replace a string	${{ replace(atomgit.ref, 'refs/heads/', '') }}

Function details:

• always: Returns true in any case, used to ensure a step always runs (e.g., cleanup steps). Used in combination with post.
• contains(search, item): For string searches, it's substring matching; for array/object searches, it checks for the existence of the element.
• startsWith/endsWith: Pure string operations, case-sensitive.
• format: Uses {0}, {1}, ... as placeholders, replacing them with arguments in order.

3.4 Expression Examples

steps:
  - name: Run cleanup even if previous steps failed or were canceled
    if: ${{ always() }}
    run: echo "Cleanup resources"

  - name: Build on tag push
    if: ${{ startsWith(atomgit.ref, 'refs/tags/') }}
    run: echo "Build release"

  - name: Concatenate strings using format
    env:
      IMAGE_TAG: ${{ format('{0}:{1}', 'myimage', atomgit.sha) }}
    run: echo $IMAGE_TAG