Skip to main content
Version: 1.0.x ๐Ÿ’€

Environment variables

Woodpecker provides the ability to pass environment variables to individual pipeline steps. Note that these can't overwrite any existing, built-in variables. Example pipeline step with custom environment variables:

steps:
build:
image: golang
+ environment:
+ - CGO=0
+ - GOOS=linux
+ - GOARCH=amd64
commands:
- go build
- go test

Please note that the environment section is not able to expand environment variables. If you need to expand variables they should be exported in the commands section.

steps:
build:
image: golang
- environment:
- - PATH=$PATH:/go
commands:
+ - export PATH=$PATH:/go
- go build
- go test

Please be warned that ${variable} expressions are subject to pre-processing. If you do not want the pre-processor to evaluate your expression it must be escaped:

steps:
build:
image: golang
commands:
- - export PATH=${PATH}:/go
+ - export PATH=$${PATH}:/go
- go build
- go test

Built-in environment variablesโ€‹

This is the reference list of all environment variables available to your pipeline containers. These are injected into your pipeline step and plugins containers, at runtime.

NAMEDescription
CI=woodpeckerenvironment is woodpecker
Repository
CI_REPOrepository full name <owner>/<name>
CI_REPO_OWNERrepository owner
CI_REPO_NAMErepository name
CI_REPO_REMOTE_IDrepository remote ID, is the UID it has in the forge
CI_REPO_SCMrepository SCM (git)
CI_REPO_URLrepository web URL
CI_REPO_CLONE_URLrepository clone URL
CI_REPO_DEFAULT_BRANCHrepository default branch (master)
CI_REPO_PRIVATErepository is private
CI_REPO_TRUSTEDrepository is trusted
Current Commit
CI_COMMIT_SHAcommit SHA
CI_COMMIT_REFcommit ref
CI_COMMIT_REFSPECcommit ref spec
CI_COMMIT_BRANCHcommit branch (equals target branch for pull requests)
CI_COMMIT_SOURCE_BRANCHcommit source branch (empty if event is not pull_request)
CI_COMMIT_TARGET_BRANCHcommit target branch (empty if event is not pull_request)
CI_COMMIT_TAGcommit tag name (empty if event is not tag)
CI_COMMIT_PULL_REQUESTcommit pull request number (empty if event is not pull_request)
CI_COMMIT_PULL_REQUEST_LABELSlabels assigned to pull request (empty if event is not pull_request)
CI_COMMIT_URLcommit link in forge
CI_COMMIT_MESSAGEcommit message
CI_COMMIT_AUTHORcommit author username
CI_COMMIT_AUTHOR_EMAILcommit author email address
CI_COMMIT_AUTHOR_AVATARcommit author avatar
Current pipeline
CI_PIPELINE_NUMBERpipeline number
CI_PIPELINE_PARENTnumber of parent pipeline
CI_PIPELINE_EVENTpipeline event (push, pull_request, tag, deployment)
CI_PIPELINE_URLlink to the forge's web UI for the commit(s) or tag that triggered the pipeline
CI_PIPELINE_DEPLOY_TARGETpipeline deploy target for deployment events (ie production)
CI_PIPELINE_STATUSpipeline status (success, failure)
CI_PIPELINE_CREATEDpipeline created UNIX timestamp
CI_PIPELINE_STARTEDpipeline started UNIX timestamp
CI_PIPELINE_FINISHEDpipeline finished UNIX timestamp
Current workflow
CI_WORKFLOW_NAMEworkflow name
Current step
CI_STEP_NAMEstep name
CI_STEP_STATUSstep status (success, failure)
CI_STEP_STARTEDstep started UNIX timestamp
CI_STEP_FINISHEDstep finished UNIX timestamp
Previous commit
CI_PREV_COMMIT_SHAprevious commit SHA
CI_PREV_COMMIT_REFprevious commit ref
CI_PREV_COMMIT_REFSPECprevious commit ref spec
CI_PREV_COMMIT_BRANCHprevious commit branch
CI_PREV_COMMIT_SOURCE_BRANCHprevious commit source branch
CI_PREV_COMMIT_TARGET_BRANCHprevious commit target branch
CI_PREV_COMMIT_URLprevious commit link in forge
CI_PREV_COMMIT_MESSAGEprevious commit message
CI_PREV_COMMIT_AUTHORprevious commit author username
CI_PREV_COMMIT_AUTHOR_EMAILprevious commit author email address
CI_PREV_COMMIT_AUTHOR_AVATARprevious commit author avatar
Previous pipeline
CI_PREV_PIPELINE_NUMBERprevious pipeline number
CI_PREV_PIPELINE_PARENTprevious pipeline number of parent pipeline
CI_PREV_PIPELINE_EVENTprevious pipeline event (push, pull_request, tag, deployment)
CI_PREV_PIPELINE_URLprevious pipeline link in CI
CI_PREV_PIPELINE_DEPLOY_TARGETprevious pipeline deploy target for deployment events (ie production)
CI_PREV_PIPELINE_STATUSprevious pipeline status (success, failure)
CI_PREV_PIPELINE_CREATEDprevious pipeline created UNIX timestamp
CI_PREV_PIPELINE_STARTEDprevious pipeline started UNIX timestamp
CI_PREV_PIPELINE_FINISHEDprevious pipeline finished UNIX timestamp
โ€ƒ
CI_WORKSPACEPath of the workspace where source code gets cloned to
System
CI_SYSTEM_NAMEname of the CI system: woodpecker
CI_SYSTEM_URLlink to CI system
CI_SYSTEM_HOSThostname of CI server
CI_SYSTEM_VERSIONversion of the server
Forge
CI_FORGE_TYPEname of forge (gitea, github, ...)
CI_FORGE_URLroot URL of configured forge
Internal - Please don't use!
CI_SCRIPTInternal script path. Used to call pipeline step commands.
CI_NETRC_USERNAMECredentials for private repos to be able to clone data. (Only available for specific images)
CI_NETRC_PASSWORDCredentials for private repos to be able to clone data. (Only available for specific images)
CI_NETRC_MACHINECredentials for private repos to be able to clone data. (Only available for specific images)

Global environment variablesโ€‹

If you want specific environment variables to be available in all of your pipelines use the WOODPECKER_ENVIRONMENT setting on the Woodpecker server. Note that these can't overwrite any existing, built-in variables.

services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2

These can be used, for example, to manage the image tag used by multiple projects.

steps:
build:
- image: golang:1.18
+ image: golang:${GOLANG_VERSION}
commands:
- [...]
environment:
- [...]
+ - WOODPECKER_ENVIRONMENT=GOLANG_VERSION:1.18

String Substitutionโ€‹

Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic settings, commands and filters in our pipeline configuration.

Example commit substitution:

steps:
docker:
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_SHA}

Example tag substitution:

steps:
docker:
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_TAG}

String Operationsโ€‹

Woodpecker also emulates bash string operations. This gives us the ability to manipulate the strings prior to substitution. Example use cases might include substring and stripping prefix or suffix values.

OPERATIONDESCRIPTION
${param}parameter substitution
${param,}parameter substitution with lowercase first char
${param,,}parameter substitution with lowercase
${param^}parameter substitution with uppercase first char
${param^^}parameter substitution with uppercase
${param:pos}parameter substitution with substring
${param:pos:len}parameter substitution with substring and length
${param=default}parameter substitution with default
${param##prefix}parameter substitution with prefix removal
${param%%suffix}parameter substitution with suffix removal
${param/old/new}parameter substitution with find and replace

Example variable substitution with substring:

steps:
docker:
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_SHA:0:8}

Example variable substitution strips v prefix from v.1.0.0:

steps:
docker:
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_TAG##v}