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 Functions

Function	Description	Example
success	Returns true when all previous steps are successful	if: ${{ success }}
always	Always returns true regardless of the result 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 value of files	${{ hashFiles('src/**', 'package.json') }}
toJson(value)	Serializes an object into a JSON string	${{ toJson(atomgit.event) }}

Function Details:

• success: Returns true when the conclusion of all previous steps is 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., cleanup steps). Used in conjunction with post or run_always.
• cancelled: Returns true when the workflow is cancelled.
• failed: Returns true when the conclusion of any previous step is failure.
• contains(search, item): For string search, it matches substrings; for array/object search, it checks if the element exists.
• startsWith/endsWith: Pure string operations, case-sensitive.
• format: Uses {0}, {1}, ... as placeholders, replacing them sequentially with arguments.
• hashFiles: Calculates the combined SHA256 hash of matching files, used for generating cache keys.

3.3 Expression Examples

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

  - name: Clean up 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