Docs

Environment variables

Description

Updatecli reads configuration from three places, in decreasing priority: the manifest, command line flags, and the environment. This page covers the last one.

Environment variables exist mostly so credentials never have to be written into a manifest. Anything a manifest can set is documented on the plugin’s own page; what follows is only what has no home in a manifest, or what changes a default.

Tip
Run with --debug to see which variable was actually used. Credential lookups log the variable they picked, for example using GitHub token from environment variable UPDATECLI_GITHUB_TOKEN.

Credentials

GitHub

Updatecli tries these in order and stops at the first that yields a token:

  1. spec.token in the manifest

  2. UPDATECLI_GITHUB_TOKEN

  3. the GitHub App variables below

  4. GITHUB_TOKEN

VariablePurpose

UPDATECLI_GITHUB_TOKEN

Personal access token. The preferred variable.

UPDATECLI_GITHUB_USERNAME

Username paired with the token. Defaults to oauth2, which is what the GitHub API expects for token authentication, so it rarely needs setting.

GITHUB_TOKEN

Fallback, checked last. This is what makes Updatecli work inside GitHub Actions with no extra configuration, since the runner provides it.

GitHub App authentication is used when all three required variables are set. Any of them missing and the whole App path is skipped silently (no error, Updatecli simply moves on to GITHUB_TOKEN).

VariablePurpose

UPDATECLI_GITHUB_APP_CLIENT_ID

App client ID. Required.

UPDATECLI_GITHUB_APP_PRIVATE_KEY

The private key itself. Required, unless _PATH is used.

UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH

Path to the private key file. Alternative to the above.

UPDATECLI_GITHUB_APP_INSTALLATION_ID

Installation ID. Required.

UPDATECLI_GITHUB_APP_EXPIRATION_TIME

Token lifetime in seconds. Optional.

Important
A token and an App are alternatives. Setting both token and app on the same GitHub spec fails with you cannot use both token and app authentication methods.

Gitea

UPDATECLI_GITEA_TOKEN, falling back to GITEA_TOKEN.

Azure DevOps

UPDATECLI_AZURE_DEVOPS_TOKEN and UPDATECLI_AZURE_DEVOPS_USERNAME.

Udash

VariablePurpose

UPDATECLI_UDASH_URL

Udash instance URL.

UPDATECLI_UDASH_API_URL

Udash API URL.

UPDATECLI_UDASH_ACCESS_TOKEN

Access token. updatecli udash login writes one to the local config file instead.

Note
Reporting to Udash requires --experimental. Without it the step is skipped silently, whatever these variables say. See "Experimental features" page.

Flag defaults

Two flags read a default from the environment, which is the practical way to set them once for a whole CI job rather than on every invocation. An unparsable value is ignored and logged at debug level.

VariableFlagEffect

UPDATECLI_DISABLE_CHANGELOG

--disable-changelog

Skip changelog retrieval. Saves API calls.

UPDATECLI_DISABLE_VERSION_CHECK

--disable-version-check

Skip the check for a newer Updatecli release, which runs after the command completes.

The local scm

When a stage refers to scmid: local without that scm being defined, Updatecli guesses it from the Git repository in the current directory (the origin remote gives the URL, owner, and repository).

These variables override individual fields of that guess:

VariableOverrides

UPDATECLI_SCM_LOCAL_BRANCH

branch

UPDATECLI_SCM_LOCAL_DIRECTORY

directory

UPDATECLI_SCM_LOCAL_EMAIL

email used for commits

UPDATECLI_SCM_LOCAL_URL

repository URL

UPDATECLI_SCM_LOCAL_USER

user used for commits

UPDATECLI_SCM_LOCAL_USERNAME

username used to authenticate

UPDATECLI_SCM_LOCAL_OWNER

owner - GitHub remotes only

UPDATECLI_SCM_LOCAL_REPOSITORY

repository - GitHub remotes only

UPDATECLI_SCM_LOCAL_TOKEN

token - GitHub remotes only

Only non-empty values are applied, so exporting one variable leaves the rest of the guess intact. This is the tidiest way to change the commit author from CI without touching the manifest:

export UPDATECLI_SCM_LOCAL_EMAIL="bot@example.com"
export UPDATECLI_SCM_LOCAL_USER="example-bot"
updatecli pipeline apply
Note
These apply only to the auto-guessed local scm. An scm you declared yourself is configured in the manifest, not through the environment, and the guess itself can be turned off with scms.local.disabled: true.

Shell scripts

The shell plugin exports two variables into the environment of the command it runs:

VariableValue

DRY_RUN

true during a diff, false during an apply. The script is run either way - honouring this is the script’s responsibility.

UPDATECLI_PIPELINE_STAGE

source, condition, or target, so one script can serve several stages.

Warning

A shell target whose script ignores DRY_RUN will write to disk during updatecli pipeline diff, which otherwise changes nothing. Guard the write:

if test "$DRY_RUN" == "false"; then
  echo "$1" > version.txt
fi
echo "$1"

The "Shell" page has the complete pattern.

Network

Proxies

Updatecli’s HTTP clients honour the standard variables through Go’s own proxy resolution:

VariablePurpose

HTTP_PROXY

Proxy for plain HTTP requests.

HTTPS_PROXY

Proxy for HTTPS requests.

NO_PROXY

Hosts to reach directly. Accepts a comma-separated list.

The lowercase spellings are equally valid, and are what Go checks first.

Note
This covers HTTP traffic. A plugin that shells out to another tool (helm, mvn, npm) leaves that tool to read the environment for itself, which it usually does.

Telemetry

Tracing is off unless it is configured, and it is configured entirely through the OpenTelemetry variables: OTEL_TRACES_EXPORTER, OTEL_EXPORTER_OTLP_ENDPOINT, and OTEL_EXPORTER_OTLP_TRACES_ENDPOINT.

There is no --disable-telemetry flag, because nothing is sent in the first place until one of these is set. Setting an endpoint without naming an exporter implies otlp. The "Telemetry" page documents the exporters and the spans emitted.

Ecosystem tools

Plugins that work with a language ecosystem read that ecosystem’s own configuration, so credentials and mirrors you already have keep working.

Variable or fileUsed by

GOPROXY

go/module

MAVEN_MIRROR_URL, MAVEN_HOME, M2_HOME, ~/.m2/settings.xml

maven and the Maven crawler. ${env.NAME} inside settings.xml is expanded.

~/.npmrc

npm

DOCKER_CONFIG, ~/.docker/config.json

dockerimage, dockerdigest, helm - the standard Docker credential store, so docker login is enough to authenticate. See "Docker Hub rate limit".

CI detection

Updatecli identifies its CI environment from a single variable each, and uses it to enrich reports with a build URL.

Detected bySystemDebug triggered by

JENKINS_URL

Jenkins

-

GITLAB_CI

GitLab CI

CI_DEBUG_TRACE

GITHUB_ACTION

GitHub Actions

ACTIONS_RUNNER_DEBUG, ACTIONS_STEP_DEBUG

When the detected system reports being in debug mode, Updatecli enables its own debug logging and says so:

CI pipeline detected in Debug Mode - hence enabling debug mode

That is why a re-run with debug enabled in your CI system produces far more Updatecli output than the same manifest did before (nothing changed in the manifest).

Build URLs are assembled from BUILD_URL (Jenkins), CI_SERVER_URL + CI_PROJECT_PATH + CI_JOB_ID (GitLab), and GITHUB_SERVER_URL + GITHUB_REPOSITORY + GITHUB_RUN_ID (GitHub Actions).

Using variables inside a manifest

Reading a variable in a manifest is templating, not configuration:

scms:
  default:
    kind: github
    spec:
      token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'

requiredEnv fails the run when the variable is unset, which is what you want for a credential. env returns an empty string instead. See the "Manifest" page.

Go Further

Last updated on July 30, 2026
Prev
Others
Next
Experimental features