Expressions

AtomGit Action uses the ${{ expression }} syntax to write expressions in workflows. Expressions can be used in positions such as 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' }}
!	Logical not	${{ !success }}
&&	Logical and	${{ success && atomgit.ref == 'refs/heads/main' }}
||	Logical or	${{ failed || cancelled }}
>	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
success	Returns true when all previous steps are successful	if: ${{ success }}
always	Always returns true regardless of previous steps	if: ${{ always }}
cancelled	Returns true when the workflow is cancelled	if: ${{ cancelled }}
failed	Returns true when any previous step fails	if: ${{ failed }}
contains(search, item)	Checks if search contains item	${{ contains(atomgit.ref, 'release') }}
startsWith(search, prefix)	Checks if search starts with prefix	${{ startsWith(atomgit.ref, 'refs/tags/') }}
endsWith(search, suffix)	Checks if search ends with suffix	${{ endsWith(atomgit.ref_name, '.rc') }}
format(template, args...)	Formats a string, 0/1... are placeholders	${{ format('Hello {0}, {1}!', name, role) }}
substring(str, start, len)	Extracts a substring	${{ substring(atomgit.sha, 0, 7) }}
replace(str, old, new)	Replaces a string	${{ replace(atomgit.ref, 'refs/heads/', '') }}
hashFiles(paths...))	Calculates the hash of files	${{ hashFiles('src/**', 'package.json') }}
toJson(value)	Serializes an object into a JSON string	${{ toJson(atomgit.event) }}

Detailed function descriptions:

• success: Returns true when all previous steps have a conclusion of success. In if conditions, if no condition is specified, it defaults to success.
• always: Always returns true, used to ensure that a step is always executed (e.g., clean-up steps). Used in conjunction with post or run_always.
• cancelled: Returns true when the workflow is cancelled.
• failed: Returns true when any previous step has a conclusion of failure.
• contains(search, item): For string searches, it checks for substring matches; for arrays or objects, it checks whether the element exists.
• startsWith/endsWith: Pure string operations, case-sensitive.
• format: Uses {0}, {1}, ... as placeholders, and replaces them sequentially with arguments.
• hashFiles: Calculates the combined SHA256 hash of matching files, used for generating cache keys.

3.4 Expression Examples

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

  - name: Execute cleanup even if failed or cancelled
    if: ${{ always }}
    run: echo "Cleanup resources"

  - name: Execute notification only on failure
    if: ${{ failed }}
    run: echo "Send failure notification"

  - 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