Runtime Environment Variables

Pipeline System Variables

The following built-in public environment variables are supported and can be referenced directly without definition.

System Variable	AtomGit Definition
CI	Always set to true.
ATOMGIT_ACTION	The name of the current operation being run. Usually, it is the action name. Note: If the same script or action is used multiple times in the same job, the name will include a suffix composed of an underscore and a number. For example: the first run of the script is actionscheckout, and the second run is actionscheckout_2.
ATOMGIT_ACTION_PATH	GITHUB_ACTION_PATH points to the path of the Action. For composite actions (Composite Actions): it points to the directory containing the action.yml file. For Docker container actions: it points to the directory inside the container that contains the Action files. Note: It is different from ATOMGIT_WORKSPACE, which is the root directory where the code is checked out when the workflow runs.
ATOMGIT_ACTION_REPOSITORY	For the step that executes the action, this is the owner and repository name of the action. For example: actions/checkout.
ATOMGIT_ACTIONS	When a workflow runs with AtomGit Actions, this variable is set to true by default. You can use this variable to distinguish whether the test is running locally or by AtomGit Actions
ATOMGIT_ACTOR	The name of the person or application that triggered the workflow.
ATOMGIT_ACTOR_ID	The account ID of the user or application that triggered the initial workflow run. For example: 1234567. Please note that this ID is different from the actor's username.
ATOMGIT_API_URL	Returns the API URL.
ATOMGIT_BASE_REF	The base reference or target branch name for the pull request in the workflow run. This field is set only when the event that triggers the workflow run is `pull_request/merge_request` or `pull_request_target/merge_request_target`. For example: `main`.
ATOMGIT_ENV	The path on the runner pointing to the file that sets the workflow command variables. This file path is unique in the current step and changes in each step of the job. For example: /home/octopus/runner/workers/0.0.3.0.version/temp/runner_file_commands/set_env_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_EVENT_NAME	The name of the event that triggered the workflow. For example: workflow_dispatch.
ATOMGIT_HEAD_REF	The head reference or source branch for the pull request in the workflow run. This property is set only when the event that triggers the workflow run is `pull_request` or `pull_request_target`. For example: feature-branch-1.
ATOMGIT_JOB	The current job's job_id. For example: greeting_job.
ATOMGIT_OUTPUT	The path on the runner pointing to the file used to set the output of the current step of the workflow command. This file path is unique in the current step and changes in each step of the job. For example: /home/octopus/runner/workers/0.0.3.0.version/temp/runner_file_commands/set_output_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_PATH	The file path on the runner used to set the system path variable, generated by the workflow command. This file path is unique in the current step and changes in each step of the job. For example: /home/octopus/runner/workers/0.0.3.0.version/temp/runner_file_commands/add_path_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_REF	The full reference of the branch or tag that triggered the workflow run. For a workflow triggered by a push, this is the pushed branch or tag reference. For a workflow triggered by an unmerged pull_request, this is the merge branch of the pull request. If the pull request has been merged, this is the head branch. For a workflow triggered by a release, this is the created release tag. For other triggers, this is the branch or tag reference that triggered the workflow run. This field is set only when the event type supports branches or tags. The given reference format is complete specifications: branch reference format is `refs/heads/<branch name>`. For unmerged pull request events other than pull_request_target, the reference format is `refs/pull/<pr number>/merge`. The pull_request_target event references the base branch. Tag event reference format is `refs/tags/<tag name>`. For example: refs/heads/feature-branch-1.
ATOMGIT_REF_NAME	The short reference name of the branch or tag that triggered the workflow run. This value is consistent with the branch or tag name displayed on AtomGit. For example: feature-branch-1. For unmerged pull requests, the format is `<pr number>/merge`.
ATOMGIT_REF_PROTECTED	True if the reference that triggered the workflow run is configured with branch protection or a ruleset.
ATOMGIT_REF_TYPE	The type of reference that triggered the workflow run. Valid values are branch or tag.
ATOMGIT_REPOSITORY	The owner and repository name. For example, octocat/Hello-World.
ATOMGIT_REPOSITORY_ID	The ID of the repository. For example: 123456789. Please note that this is different from the repository name.
ATOMGIT_REPOSITORY_OWNER	The name of the repository owner. For example, octocat.
ATOMGIT_REPOSITORY_OWNER_ID	The account ID of the repository owner. For example: 1234567. Please note that this is different from the owner's name.
ATOMGIT_RETENTION_DAYS	The number of days to retain workflow run logs and artifacts. For example, 90.
ATOMGIT_RUN_ATTEMPT	Each attempt of a workflow run in the repository has a unique number. This number starts at 1 for the first attempt of the workflow run and increments with each re-run. For example: 3.
ATOMGIT_RUN_ID	Each workflow run in the repository has a unique number. This number does not change even if the workflow is re-run. For example: 1658821493.
ATOMGIT_RUN_NUMBER	A unique number generated each time a specific workflow runs in the repository. This number starts at 1 for the first run of the workflow and increments with each new run. Even if the workflow is re-run, this number does not change. For example: 3
ATOMGIT_SERVER_URL	The URL of the AtomGit server. For example: xxxx
ATOMGIT_SHA	The commit SHA that triggered the workflow. The specific value of this commit SHA depends on the type of event that triggered the workflow. For more information, see "Events that trigger workflows." For example: ffac537e6cbbf934b08745a378932722df287a53.
ATOMGIT_STEP_SUMMARY	The path on the runner pointing to the file containing the workflow command task summary. This file path is unique in the current step and changes in each step of the job. For example: /home/octopus/runner/workers/0.0.3.0.version/temp/runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c.
ATOMGIT_TRIGGERING_ACTOR	The username of the user who initiated the workflow run. If the workflow run is a re-run, this value may differ from ATOMGIT_ACTOR. Any workflow re-run will use the permissions of ATOMGIT_ACTOR, even if the operator who initiated the re-run (ATOMGIT_ACTOR) has different permissions.
ATOMGIT_WORKFLOW	The name of the workflow. For example, My test workflow. If the workflow file does not specify a name, the value of this variable is the full path of the workflow file in the repository.
ATOMGIT_WORKFLOW_ID	The unique identifier ID of the workflow
ATOMGIT_WORKFLOW_REF	The reference path of the workflow. ATOMGIT_WORKFLOW_REF contains three core pieces of information: Repository path: organization name/repository name. Workflow file path: YAML filename under .atomgit/workflows/. Reference identifier (Ref): the branch name, tag name, or specific Commit SHA that triggered the workflow. Its standard format is usually as follows: `{owner}/{repo}/.gitcode/workflows/{filename}@{ref}` Example: octocat/hello-world/.gitcode/workflows/main.yml@refs/heads/main
ATOMGIT_WORKFLOW_SHA	The commit SHA value of the workflow file.
ATOMGIT_WORKSPACE	The default working directory for the step on the runner. For example: /home/octopus/runner/workers/0.0.3.0.version/worker_dir/placeholder_repo
RUNNER_ARCH	The architecture of the runner executing the task. Possible values include X86, X64, ARM, or ARM64
RUNNER_ENVIRONMENT	The runner environment defining the resource pool type for executing tasks. Possible values include: gitcode-hosted (AtomGit public resource pool, provided by AtomGit) self-hosted (self-hosted resource pool, configured by the user)
RUNNER_NAME	The name of the runner executing the task. This name may not be unique within the workflow run, as runners at the repository and organization levels may use the same name. For example: hosted agent
RUNNER_OS	The operating system of the runner executing the task. Possible values are Linux, Windows, or macOS. For example, Windows
RUNNER_TEMP	The temporary directory path on the runner. This directory is cleared at the beginning and end of each task. Please note that if the runner's user account does not have deletion permissions, the files will not be removed. For example: D:\a_temp
RUNNER_TOOL_CACHE	The path pointing to the directory containing the pre-installed tools on the AtomGit-managed runners. For more information, see AtomGit-managed runners. For example: C:\hostedtoolcache\windows

Contexts

Available Contexts

The following are first-level context definitions. Full context definitions can be found in the main document's context section.

Context Name	Type	Description
atomgit	object	Information about the workflow run.
env	object	Contains variables set in the workflow, job, or step.
vars	object	Contains variables set at the repository, organization, or environment level.
job	object	Information about the current job being run.
jobs	object	For reusable workflows, contains outputs from the reusable workflow.
steps	object	Information about the steps that have been run in the current job.
runner	object	Information about the runner running the current job.
secrets	object	Contains names and values of secrets available for the workflow run.
strategy	object	Information about the matrix execution strategy for the current job.
matrix	object	Contains matrix properties defined in the workflow applicable to the current job.
inputs	object	Contains input properties passed to an action, reusable workflow, or manually triggered workflow.

If you try to reference a non-existent property, it will evaluate to an empty string.

Determining When to Use Contexts

Default environment variables: These environment variables exist only on the runner executing your task. For more information, see Variable Reference.
Contexts: You can use most contexts at any time in the workflow, including when default variables are not available. For example, you can use contexts with expressions to perform initial processing before the job is routed to the runner; this allows you to use contexts related to the if keyword to determine whether a step should be run. Once the job starts running, you can also retrieve context variables from the runner executing the job, such as runner.os.

The following example demonstrates how to use these different types of variables in a job:

name: CI  
on: push  
jobs:  
  prod-check:  
    if: ${{ atomgit.ref == 'refs/heads/main' }}  
    runs-on: default 
    steps:  
      - run: echo "Deploying to production server on branch $ATOMGIT_REF"

In this example, the if statement checks the atomgit.ref context to determine the current branch name; if the name is refs/heads/main, the subsequent steps are executed. The if check is handled by AtomGit Pipeline, and the job is only sent to the execution environment if the result is true. Once the job is sent to the execution environment, the steps are executed, and they reference the $ATOMGIT_REF variable.

Runtime Process File Instructions

AtomGit Runner generates a set of temporary process files on the runner during workflow execution, and exposes the file paths through environment variables to the current step or action. Users can write content to these files to interact with the runner, such as setting environment variables, setting step outputs, appending to PATH, generating Job Summary, passing state between the pre/main/post lifecycle of an action, etc.

Note: The paths of files such as ATOMGIT_ENV, ATOMGIT_OUTPUT, ATOMGIT_PATH, and ATOMGIT_STEP_SUMMARY are usually "unique to the current step," and the paths change in different steps; the effect of writing usually takes effect from the next step or the runner aggregation phase.

1. Full List of Process Files

System Variable	File Type	Main Purpose	Effective Scope	Typical Writing Format	Whether Recommended for User to Use Directly
`ATOMGIT_ENV`	Environment Variable File	Set environment variables readable by subsequent steps	Subsequent steps of the current job	`echo "NAME=value" >> "$ATOMGIT_ENV"`	Yes
`ATOMGIT_OUTPUT`	Step Output File	Set the output of the current step, used by subsequent steps, job outputs, or reusable workflows	Current step output; referenced via `steps.<id>.outputs`	`echo "name=value" >> "$ATOMGIT_OUTPUT"`	Yes
`ATOMGIT_PATH`	PATH Append File	Append a directory to the system `PATH`, allowing subsequent steps to directly call commands in the directory	Subsequent steps/actions of the current job	`echo "/path/to/bin" >> "$ATOMGIT_PATH"`	Yes
`ATOMGIT_STEP_SUMMARY`	Step/Job Summary File	Generate Markdown-formatted Job Summary, displayed on the workflow run summary page	Written in the current step, summarized and displayed after the job ends	`echo "### Summary" >> "$ATOMGIT_STEP_SUMMARY"`	Yes

2. `ATOMGIT_ENV`: Setting Environment Variables for Subsequent Steps

Purpose

ATOMGIT_ENV is used to inject environment variables into subsequent steps of the current job. After the current step writes, the current step itself cannot read the new value, but subsequent steps can read it.

It is not recommended to override the system variables injected by the runner, such as ATOMGIT_* and RUNNER_* variables, through ATOMGIT_ENV. System variables are usually controlled by the platform, and user-defined overrides may not take effect or may cause unexpected behavior.

Use Cases

Suitable for dynamically calculating variables during the pipeline execution and reusing them in subsequent steps.

Scenario	Example
Dynamically generate version numbers	Generate `BUILD_VERSION` from tag, commit, timestamp
Shared paths among multiple steps	Build product directory, temporary directory, tool installation directory
Shared deployment parameters	Environment name, image tag, release channel
Shared script calculation results	Detection results, changed module list, build switch

Use Case: Setting Build Version Number

name: env-example

on:
  push:

jobs:
  build:
    runs-on: default
    steps:
      - name: Generate build version
        run: |
          VERSION="1.0.${ATOMGIT_RUN_NUMBER}"
          echo "BUILD_VERSION=$VERSION" >> "$ATOMGIT_ENV"

      - name: Use build version
        run: |
          echo "Current build version is $BUILD_VERSION"

Use Case: Writing Multi-line Environment Variables

Multi-line variables can be written using the delimiter syntax:

steps:
  - name: Set multiline env
    run: |
      {
        echo 'CHANGELOG<<EOF'
        echo '- add login feature'
        echo '- fix build script'
        echo EOF
      } >> "$ATOMGIT_ENV"

  - name: Use multiline env
    run: |
      echo "$CHANGELOG"

When writing multi-line, the delimiter should not appear on a separate line in the variable content. If the content is completely uncontrollable, it is recommended to write to a regular file and then pass the file path.

3. `ATOMGIT_OUTPUT`: Setting Step Output

Purpose

ATOMGIT_OUTPUT is used to set the output parameters of the current step. Subsequent steps can read this value via ${{ steps.<step_id>.outputs.<output_name> }}. The step that sets the output must be configured with an id; otherwise, subsequent steps cannot reference it via steps.<id>.outputs.

Use Cases

Suitable for expressing "the structured result of a step", which is more suitable for data transfer between steps and jobs compared to directly writing environment variables.

Scenario	Example
Get build result	Output `artifact_name`, `artifact_path`
Dynamically decide subsequent behavior	Output `should_deploy=true/false`
Generate image information	Output `image_tag`, `image_digest`
Pass parameters between jobs	First set step output, then map it to job output
Custom action output	Action internally exposes calculation results to the caller

Use Case: Passing Output Between Steps

name: output-example

on:
  push:

jobs:
  build:
    runs-on: default
    steps:
      - name: Generate image tag
        id: meta
        run: |
          IMAGE_TAG="app-${ATOMGIT_SHA::7}"
          echo "image_tag=$IMAGE_TAG" >> "$ATOMGIT_OUTPUT"

      - name: Use image tag
        run: |
          echo "Image tag is ${{ steps.meta.outputs.image_tag }}"

Use Case: Passing Output Between Jobs

name: job-output-example

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      image_tag: ${{ steps.meta.outputs.image_tag }}
    steps:
      - name: Generate image tag
        id: meta
        run: |
          echo "image_tag=app-${ATOMGIT_SHA}" >> "$ATOMGIT_OUTPUT"

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        run: |
          echo "Deploy image tag: ${{ needs.build.outputs.image_tag }}"

When passing data across jobs, it is usually necessary to first set the step output via ATOMGIT_OUTPUT, then map the step output to the job output via jobs.<job_id>.outputs, and finally have downstream jobs retrieve it via needs.<job_id>.outputs.<output_name>.

4. `ATOMGIT_PATH`: Appending Command Directories to PATH

Purpose

ATOMGIT_PATH is used to append a directory to the system PATH, so that subsequent steps or actions can directly call the executable files in that directory. After writing, the current step cannot immediately access the updated PATH, only subsequent steps can access it.

Use Cases

Suitable for temporarily installing CLI, script tools, or build tools in the pipeline and allowing subsequent steps to directly call them.

Scenario	Example
Install custom CLI	Download `mycli` to `$HOME/.local/bin`
Use project scripts	Add `scripts/bin` to PATH
Prepare language toolchain	Add the temporarily installed Go/Node/Python tool directories to PATH
Compatible with multi-platform execution	Write different tool directories based on OS

Use Case: Directly Calling CLI After Installation

name: path-example

on:
  push:

jobs:
  use-cli:
    runs-on: ubuntu-latest
    steps:
      - name: Install custom cli
        run: |
          mkdir -p "$HOME/.local/bin"
          cat > "$HOME/.local/bin/hello-cli" <<'EOF'
          #!/usr/bin/env bash
          echo "hello from custom cli"
          EOF
          chmod +x "$HOME/.local/bin/hello-cli"
          echo "$HOME/.local/bin" >> "$ATOMGIT_PATH"

      - name: Use custom cli
        run: |
          hello-cli

Use Case: Adding the Repository Script Directory to PATH

steps:
  - uses: actions/checkout@v4

  - name: Add scripts to PATH
    run: |
      echo "$ATOMGIT_WORKSPACE/scripts/bin" >> "$ATOMGIT_PATH"

  - name: Run project script
    run: |
      project-build

5. `ATOMGIT_STEP_SUMMARY`: Generating Job Summary Page Summary

Purpose

ATOMGIT_STEP_SUMMARY is used to write Markdown content, which is finally displayed on the summary page of the workflow run. It is suitable for displaying key information such as test summaries, build results, deployment results, and quality gate results, avoiding users having to look into the logs to find important conclusions.

Each step's ATOMGIT_STEP_SUMMARY file is independent, and after the job ends, it is summarized and displayed.

Use Cases

Suitable for presenting "workflow execution conclusions" to users.

Scenario	Example
Test result summary	Pass rate, number of failed cases, report link
Build result summary	Version number, product name, image tag
Deployment summary	Environment, service address, deployment status
Quality gate summary	Coverage, scan results, blocking items
Change summary	Modules affected by this commit, PR change scope

Use Case: Generating Test Summary

name: summary-example

on:
  push:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Generate test summary
        run: |
          echo "## Test Summary" >> "$ATOMGIT_STEP_SUMMARY"
          echo "" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Metric | Value |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "|---|---:|" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Total | 128 |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Passed | 126 |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Failed | 2 |" >> "$ATOMGIT_STEP_SUMMARY"

Use Case: Overwriting Summary Content on Failure

steps:
  - name: Generate summary
    run: |
      echo "## Build Summary" >> "$ATOMGIT_STEP_SUMMARY"
      echo "Build is running..." >> "$ATOMGIT_STEP_SUMMARY"

      echo "## Build Summary" > "$ATOMGIT_STEP_SUMMARY"
      echo "Build failed. Please check logs." >> "$ATOMGIT_STEP_SUMMARY"

For summary, >> means appending content, while > means overwriting the content already written in the current step. If you want to completely delete the summary of the current step, you can delete the file pointed to by ATOMGIT_STEP_SUMMARY. After the step completes, the summary will be uploaded, and subsequent steps cannot modify the summary uploaded by previous steps.

Pipeline System Variables​

Contexts​

Runtime Process File Instructions​

1. Full List of Process Files​

2. ATOMGIT_ENV: Setting Environment Variables for Subsequent Steps​

Purpose​

Use Cases​

Use Case: Setting Build Version Number​

Use Case: Writing Multi-line Environment Variables​

3. ATOMGIT_OUTPUT: Setting Step Output​

Purpose​

Use Cases​

Use Case: Passing Output Between Steps​

Use Case: Passing Output Between Jobs​

4. ATOMGIT_PATH: Appending Command Directories to PATH​

Purpose​

Use Cases​

Use Case: Directly Calling CLI After Installation​

Use Case: Adding the Repository Script Directory to PATH​

5. ATOMGIT_STEP_SUMMARY: Generating Job Summary Page Summary​

Purpose​

Use Cases​

Use Case: Generating Test Summary​

Use Case: Overwriting Summary Content on Failure​

Pipeline System Variables

Contexts

Runtime Process File Instructions

1. Full List of Process Files

2. `ATOMGIT_ENV`: Setting Environment Variables for Subsequent Steps

Purpose

Use Cases

Use Case: Setting Build Version Number

Use Case: Writing Multi-line Environment Variables

3. `ATOMGIT_OUTPUT`: Setting Step Output

Purpose

Use Cases

Use Case: Passing Output Between Steps

Use Case: Passing Output Between Jobs

4. `ATOMGIT_PATH`: Appending Command Directories to PATH

Purpose

Use Cases

Use Case: Directly Calling CLI After Installation

Use Case: Adding the Repository Script Directory to PATH

5. `ATOMGIT_STEP_SUMMARY`: Generating Job Summary Page Summary

Purpose

Use Cases

Use Case: Generating Test Summary

Use Case: Overwriting Summary Content on Failure