Runtime Environment Variables

StackGuardian sets a list of environment variables in every workflow step container. They tell your code which run it belongs to, where the workspace is mounted, which repository was checked out and what inputs the step received.

Use these variables instead of hardcoding IDs or paths. They hold the right values on both shared and private runners.

These are different from the environment variables you define yourself in Deployment Environment. Your own variables are passed to the same container, next to the ones on this page.

Default variables

Every variable below is read-only from the platform's point of view. If your step changes one, the change only affects that step's process.

Run identity

The ID variables hold resource IDs, not display names. An ID is generated from the resource's name when you create it and can differ from the name, for example when the name has spaces.

Variable	Description	Example value
SG_ORG_ID	The organization the run belongs to.	/orgs/<org-id>
SG_WORKFLOW_GROUP_ID	The workflow group the workflow belongs to. For a nested group, the path lists each parent group: /wfgrps/<parent-group-id>/<workflow-group-id>.	/wfgrps/<workflow-group-id>
SG_WORKFLOW_ID	The workflow being run. In a stack, the path includes the stack: /wfgrps/<workflow-group-id>/stacks/<stack-id>/wfs/<workflow-id>.	/wfgrps/<workflow-group-id>/wfs/<workflow-id>
SG_WORKFLOW_RUN_ID	The current workflow run. In a stack, the path includes the stack, as with SG_WORKFLOW_ID.	/wfgrps/<workflow-group-id>/wfs/<workflow-id>/wfruns/<run-id>
SG_STACK_ID	The stack the workflow belongs to. Empty when the workflow isn't part of a stack.	/wfgrps/<workflow-group-id>/stacks/<stack-id>
SG_WORKFLOW_STEP_TEMPLATE_ID	The workflow step template the current step runs, with its revision.	/<org-id>/<template-id>:<revision>
SG_INTEGRATION_ID	The ID of the connector selected in Deployment Environment. Empty when no connector is selected.	/integrations/<connector-id>
SG_EXECUTOR_USER	Who started the run, usually the user's email. A run started by another workflow may show a different value; use SG_TRIGGER_EVENT_INITIALIZER to get the user who started the chain.	user@example.com

Workspace paths

Each run gets a workspace that is mounted into every step container. Use these variables to find it.

Variable	Description	Example value
SG_MOUNTED_WORKSPACE_ROOT_DIR	Root of the workspace. Everything except the artifacts directory is cleaned before and after each run.	/mnt/sg_workspace
SG_MOUNTED_ARTIFACTS_DIR	Directory whose contents persist between runs of the workflow, such as Terraform state. Write sg.outputs.json here to publish outputs.	/mnt/sg_workspace/artifacts
SG_MOUNTED_IAC_SOURCE_CODE_DIR	Root of the checked-out repository. Set only when the workflow has a VCS source. This is the repository root, not the working directory. Join it with SG_VCS_WORKING_DIRECTORY to get there.	/mnt/sg_workspace/user/<repo-name>

Source control

Set when the workflow's source is a VCS repository. SG_VCS_AUTH_CREDS is always set and is empty when there's no repository.

Variable	Description	Example value
SG_VCS_REPO_URL	URL of the repository. For a private repository, the URL includes the access token, so treat it as a secret and never print it.	https://github.com/<owner>/<repo-name>
SG_VCS_REPO_NAME	Name of the repository. This is also the directory name under the workspace.	<repo-name>
SG_VCS_REPO_REF	The branch, tag or commit that was checked out. Empty when none was set.	<branch-tag-or-commit>
SG_VCS_WORKING_DIRECTORY	Working directory inside the repository, as set in the workflow's source settings. Empty when none was set.	<path/in/repo>
SG_VCS_AUTH_CREDS	Credentials used to clone the repository, such as a short-lived GitHub access token. Empty for public repositories. Treat this value as a secret and never print it.

Encoded inputs

Structured inputs are passed as base64-encoded JSON. Decode them in your step, as shown in the shell example.

Variable	Description
SG_BASE64_WORKFLOW_STEP_INPUT_VARIABLES	The input values of the current workflow step, as set in the workflow's settings.
SG_BASE64_IAC_INPUT_VARIABLES	The IaC input variables from the workflow's Source and Parameters settings. Empty when the workflow has none.
SG_BASE64_POLICIES	The policies attached to the run.

Large values

When an encoded input is too large for an environment variable, StackGuardian writes its JSON to a file in the workspace and sets the variable to file:// followed by that file's path.

echo "$SG_BASE64_POLICIES"
# file:///mnt/sg_workspace/user/.sg/<name>.json

The file holds plain JSON, not base64. Steps that read these variables should handle both forms, as the read_payload helper in the shell example does.

Trigger details

Runs started by a trigger or by a stack get one SG_TRIGGER_<KEY> variable for each text field of the trigger. The field name is converted from camelCase to upper snake case, so eventSource becomes SG_TRIGGER_EVENT_SOURCE.

The fields depend on what started the run. SG_TRIGGER_TYPE tells you which one it was:

SG_TRIGGER_TYPE	Other variables you can expect
github_webhook	SG_TRIGGER_GH_EVENT_TYPE, SG_TRIGGER_EVENT_ACTION, SG_TRIGGER_REPO_HTTP_URL
gitlab_webhook	SG_TRIGGER_GL_EVENT_TYPE, SG_TRIGGER_REPO_HTTP_URL
bitbucket_webhook	SG_TRIGGER_BB_EVENT_TYPE, SG_TRIGGER_REPO_HTTP_URL, SG_TRIGGER_EVENT_INITIALIZER
workflow_chain, started by another workflow	SG_TRIGGER_EVENT_SOURCE, the run that started it, such as /orgs/<org-id>/wfgrps/<workflow-group-id>/wfs/<workflow-id>/wfruns/<run-id>, and SG_TRIGGER_EVENT_INITIALIZER, the user who started that run
workflow_chain, started by a stack	SG_TRIGGER_EVENT_SOURCE and SG_TRIGGER_STACK_ID, both /orgs/<org-id>/wfgrps/<workflow-group-id>/stacks/<stack-id>, and SG_TRIGGER_STACK_RUN_ID, such as /stackruns/<stack-run-id>

Runs started by hand have no trigger variables, and runs on a schedule may have none. Check that a variable is set before you use it:

if [[ "${SG_TRIGGER_TYPE:-}" == "github_webhook" ]]; then
  echo "Started by a GitHub ${SG_TRIGGER_GH_EVENT_TYPE} event"
fi

Connector credentials

When a cloud connector is selected in Deployment Environment, StackGuardian sets the variables that the provider's SDKs and Terraform providers read, so most tools authenticate with no extra setup.

Connector	Variables
AWS OIDC	AWS_WEB_IDENTITY_TOKEN_FILE
AWS RBAC	AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE, pointing to files with temporary credentials for the connector's IAM role. The credentials are in the default profile unless the connector sets a profile name.
Azure service principal with federated credentials, Azure managed identity	ARM_USE_OIDC=true, ARM_OIDC_TOKEN_FILE_PATH
GCP workload identity federation, GCP service account	GOOGLE_APPLICATION_CREDENTIALS, the path to a credentials file written from the connector

Naming your own variables

• Don't start your own variable names with SG_. That prefix is reserved for the variables on this page.
• Don't reuse the names in Connector credentials when a connector is selected, because the connector sets them.
• To build a value from a runtime variable, reference it in the value of your own variable, as in the Terraform example.

Deprecated variables

Older workflow steps may use the names below. StackGuardian still sets them, but they will be removed. Use the replacement in new steps.

Deprecated	Use instead
ORG_ID, WORKFLOW_GROUP_ID, WORKFLOW_ID, WORKFLOW_RUN_ID, STACK_ID	SG_ORG_ID, SG_WORKFLOW_GROUP_ID, SG_WORKFLOW_ID, SG_WORKFLOW_RUN_ID, SG_STACK_ID
MOUNTED_WORKSPACE_ROOT_DIR, LOCAL_WORKSPACE_ROOT_DIR	SG_MOUNTED_WORKSPACE_ROOT_DIR
MOUNTED_WORKSPACE_USER_DIR	$SG_MOUNTED_WORKSPACE_ROOT_DIR/user
MOUNTED_ARTIFACTS_DIR, LOCAL_ARTIFACTS_DIR	SG_MOUNTED_ARTIFACTS_DIR
MOUNTED_IAC_SOURCE_CODE_DIR, LOCAL_IAC_SOURCE_CODE_DIR	$SG_MOUNTED_IAC_SOURCE_CODE_DIR/$SG_VCS_WORKING_DIRECTORY. The old names include the working directory; SG_MOUNTED_IAC_SOURCE_CODE_DIR is the repository root.
VCS_AUTH_CREDS	SG_VCS_AUTH_CREDS
BASE64_POLICIES	SG_BASE64_POLICIES
BASE64_WORKFLOW_STEP_INPUT_VARIABLES	SG_BASE64_WORKFLOW_STEP_INPUT_VARIABLES
BASE64_IAC_INPUT_VARIABLES	SG_BASE64_IAC_INPUT_VARIABLES
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN set for an AWS RBAC connector	The credentials files in AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE

Example

Terraform / OpenTofu

Terraform and OpenTofu read input variables from TF_VAR_<name> environment variables. To pass a runtime variable into your configuration, add an environment variable in Settings → Deployment Environment and set its value to the runtime variable. You can use it on its own or inside a longer string.

Key	Value
TF_VAR_sg_workflow_id	${SG_WORKFLOW_ID}
TF_VAR_created_by	$SG_EXECUTOR_USER
TF_VAR_custom_prefix_from_org	custom_${SG_ORG_ID}_prefix

Then declare the matching variables in your configuration:

variable "sg_workflow_id" {
  type = string
}

variable "created_by" {
  type = string
}

locals {
  tags = {
    ManagedBy   = "StackGuardian"
    WorkflowId  = var.sg_workflow_id
    CreatedBy   = var.created_by
  }
}

Shell step

A step that prints its run context, reads its inputs and publishes an output:

#!/usr/bin/env bash
set -euo pipefail

echo "Run ${SG_WORKFLOW_RUN_ID} in ${SG_ORG_ID}, started by ${SG_EXECUTOR_USER}"

# Encoded inputs hold base64 JSON, or a file:// pointer for large values.
read_payload() {
  local value="${!1:-}"
  if [[ "$value" == file://* ]]; then
    cat "${value#file://}"
  elif [[ -n "$value" ]]; then
    echo "$value" | base64 -d
  else
    echo '{}'
  fi
}

inputs=$(read_payload SG_BASE64_WORKFLOW_STEP_INPUT_VARIABLES)
region=$(echo "$inputs" | jq -r '.region // "us-east-1"')

# Files in the artifacts directory persist between runs.
# sg.outputs.json shows up in the workflow's Outputs tab.
cat > "${SG_MOUNTED_ARTIFACTS_DIR}/sg.outputs.json" <<EOF
{ "region": "${region}", "run_id": "${SG_WORKFLOW_RUN_ID}" }
EOF

Related

• Deployment Environment: add your own environment variables and select a connector.
• Reference Variables: pull outputs and secrets into variables.
• Outputs: how sg.outputs.json becomes workflow outputs.
• Runtime containers: build your own workflow step.
• Custom runtime image: run steps on your own image.
• Custom workflows: workflows made of your own steps.