Skip to main content

Environment variables

Woodpecker provides the ability to pass environment variables to individual pipeline steps. Example pipeline step with custom environment variables:

image: golang
+ environment:
+ - CGO=0
+ - GOOS=linux
+ - GOARCH=amd64
- 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.

image: golang
- environment:
- - PATH=$PATH:/go
+ - 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:

image: golang
- - 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.

CI=woodpeckerenvironment is woodpecker
CI_REPOrepository full name <owner>/<name>
CI_REPO_OWNERrepository owner
CI_REPO_NAMErepository name
CI_REPO_SCMrepository scm (git)
CI_REPO_LINKrepository link
CI_REPO_REMOTErepository 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
CI_COMMIT_TARGET_BRANCHcommit target branch
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_LINKcommit link in remote
CI_COMMIT_MESSAGEcommit message
CI_COMMIT_AUTHORcommit author username
CI_COMMIT_AUTHOR_EMAILcommit author email address
CI_COMMIT_AUTHOR_AVATARcommit author avatar
Current build
CI_BUILD_NUMBERbuild number
CI_BUILD_PARENTbuild number of parent build
CI_BUILD_EVENTbuild event (push, pull_request, tag, deployment)
CI_BUILD_LINKbuild link in ci
CI_BUILD_DEPLOY_TARGETbuild deploy target for deployment events (ie production)
CI_BUILD_STATUSbuild status (success, failure)
CI_BUILD_CREATEDbuild created unix timestamp
CI_BUILD_STARTEDbuild started unix timestamp
CI_BUILD_FINISHEDbuild finished unix timestamp
Current job
CI_JOB_NUMBERjob number
CI_JOB_STATUSjob status (success, failure)
CI_JOB_STARTEDjob started unix timestamp
CI_JOB_FINISHEDjob 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_LINKprevious commit link in remote
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 build
CI_PREV_BUILD_NUMBERprevious build number
CI_PREV_BUILD_PARENTprevious build number of parent build
CI_PREV_BUILD_EVENTprevious build event (push, pull_request, tag, deployment)
CI_PREV_BUILD_LINKprevious build link in ci
CI_PREV_BUILD_DEPLOY_TARGETprevious build deploy target for deployment events (ie production)
CI_PREV_BUILD_STATUSprevious build status (success, failure)
CI_PREV_BUILD_CREATEDprevious build created unix timestamp
CI_PREV_BUILD_STARTEDprevious build started unix timestamp
CI_PREV_BUILD_FINISHEDprevious build finished unix timestamp
CI_WORKSPACEPath of the workspace where source code gets cloned to
CI_SYSTEM_NAMEname of the ci system: woodpecker
CI_SYSTEM_LINKlink to ci system
CI_SYSTEM_HOSThostname of ci server
CI_SYSTEM_VERSIONversion of the server
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 builds use the WOODPECKER_ENVIRONMENT setting on the Woodpecker server.

- [...]
+ - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2

String Substitutionโ€‹

Woodpecker provides the ability to substitute environment variables at runtime. This gives us the ability to use dynamic build or commit details in our pipeline configuration.

Example commit substitution:

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

Example tag substitution:

image: plugins/docker
+ 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.

${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:

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

Example variable substitution strips v prefix from v.1.0.0:

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