Runtime Environment Variables

Pipeline System Variables

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

System Variable	GitCode 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 script name 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 within the container containing 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 on GitCode Actions, this variable is set to true by default. You can use this variable to distinguish whether the test is running locally or by GitCode Actions
ATOMGIT_ACTOR	The name of the person or application that started 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. The 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_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. The path of this file 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, which is 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 workflows triggered by a push, this is the pushed branch or tag reference. For workflows triggered by an unmerged pull_request, this is the merged branch of the pull request. If the pull request has been merged, it is the head branch. For workflows 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 and standardized: the 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. The 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 matches the branch or tag name displayed on GitCode. 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 rerun. 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 rerun. 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 rerun, this number does not change. For example: 3
ATOMGIT_SERVER_URL	The URL of the gitcode 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 summary of the workflow command task. The 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 rerun, this value may differ from ATOMGIT_ACTOR. Any workflow rerun will use the permissions of ATOMGIT_ACTOR, even if the operator who initiated the rerun (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): 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 the task. Possible values include: gitcode-hosted (gitcode public resource pool, provided by gitcode) 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 in the workflow run, as runners at the repository and organization level 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 delete 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 gitcode-hosted runner. For more information, see GitCode Hosted Runners. For example: C:\hostedtoolcache\windows

Contexts

Available Contexts

The following are the definitions of first-level contexts. For the full context definitions, please refer to the context section in the main document.

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 currently running job.
jobs	object	Only 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 available secrets 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 that apply to the current job.
inputs	object	Contains input properties passed to the 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 task 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 task starts running, you can also retrieve context variables from the runner executing the task, 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 GitCode Pipeline, and the task is only sent to the execution environment if the result is true. Once the task is sent to the execution environment, the steps are executed, and they reference the $ATOMGIT_REF variable..

Running Process File Instructions

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

Note: The paths of files like 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 effects of writing are generally effective from the next step or the runner summary phase.

1. Full List of Process Files

System Variable	File Type	Main Purpose	Scope of Effect	Typical Writing Format	Whether Recommended for Direct User Use
`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` so that subsequent steps can 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 format 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 writing in the current step, the current step itself cannot read the new value, but subsequent steps can read it.

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

Use Cases

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

Scenario	Example
Dynamically generate version numbers	Generate `BUILD_VERSION` from tag, commit, timestamp
Shared paths for multiple steps	Build artifact 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 switches

Usage Example: Setting the 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"

Usage Example: Writing Multi-line Environment Variables

Multi-line variables can use 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 in a separate line of 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 configure 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 appropriate for data transfer between steps and jobs than directly writing environment variables.

Scenario	Example
Get build results	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	The action internally exposes the calculated result to the caller

Usage Example: 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 }}"

Usage Example: 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 a Command Directory to PATH

Purpose

ATOMGIT_PATH is used to append a directory to the system PATH, allowing subsequent steps or actions to directly call 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

Usage Example: Using 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

Usage Example: Adding 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 eventually displayed on the workflow run summary page. 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 showing "workflow execution conclusions" to users.

Scenario	Example
Test result summary	Pass rate, number of failed test 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

Usage Example: 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"

Usage Example: 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 summaries, >> 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. Once the step is completed, the summary will be uploaded, and subsequent steps cannot modify the summary of previous steps.

Pipeline System Variables​

Contexts​

Running Process File Instructions​

1. Full List of Process Files​

2. ATOMGIT_ENV: Setting Environment Variables for Subsequent Steps​

Purpose​

Use Cases​

Usage Example: Setting the Build Version Number​

Usage Example: Writing Multi-line Environment Variables​

3. ATOMGIT_OUTPUT: Setting Step Output​

Purpose​

Use Cases​

Usage Example: Passing Output Between Steps​

Usage Example: Passing Output Between Jobs​

4. ATOMGIT_PATH: Appending a Command Directory to PATH​

Purpose​

Use Cases​

Usage Example: Using CLI After Installation​

Usage Example: Adding Repository Script Directory to PATH​

5. ATOMGIT_STEP_SUMMARY: Generating Job Summary Page Summary​

Purpose​

Use Cases​

Usage Example: Generating Test Summary​

Usage Example: Overwriting Summary Content on Failure​

Pipeline System Variables

Contexts

Running Process File Instructions

1. Full List of Process Files

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

Purpose

Use Cases

Usage Example: Setting the Build Version Number

Usage Example: Writing Multi-line Environment Variables

3. `ATOMGIT_OUTPUT`: Setting Step Output

Purpose

Use Cases

Usage Example: Passing Output Between Steps

Usage Example: Passing Output Between Jobs

4. `ATOMGIT_PATH`: Appending a Command Directory to PATH

Purpose

Use Cases

Usage Example: Using CLI After Installation

Usage Example: Adding Repository Script Directory to PATH

5. `ATOMGIT_STEP_SUMMARY`: Generating Job Summary Page Summary

Purpose

Use Cases

Usage Example: Generating Test Summary

Usage Example: Overwriting Summary Content on Failure