woodpecker/docs/versioned_docs/version-2.0/20-usage/50-environment.md
6543 936c9bdb0d
Export changed files via builtin environment variables (#2935)
add **`CI_PIPELINE_FILES`** to builtin env vars

close  #853

---
*Sponsored by Kithara Software GmbH*
2023-12-18 22:37:38 +01:00

15 KiB
Raw Blame History

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.

NAME Description
CI CI environment name (value: woodpecker)
Repository
CI_REPO repository full name <owner>/<name>
CI_REPO_OWNER repository owner
CI_REPO_NAME repository name
CI_REPO_REMOTE_ID repository remote ID, is the UID it has in the forge
CI_REPO_SCM repository SCM (git)
CI_REPO_URL repository web URL
CI_REPO_CLONE_URL repository clone URL
CI_REPO_CLONE_SSH_URL repository SSH clone URL
CI_REPO_DEFAULT_BRANCH repository default branch (main)
CI_REPO_PRIVATE repository is private
CI_REPO_TRUSTED repository is trusted
Current Commit
CI_COMMIT_SHA commit SHA
CI_COMMIT_REF commit ref
CI_COMMIT_REFSPEC commit ref spec
CI_COMMIT_BRANCH commit branch (equals target branch for pull requests)
CI_COMMIT_SOURCE_BRANCH commit source branch (empty if event is not pull_request)
CI_COMMIT_TARGET_BRANCH commit target branch (empty if event is not pull_request)
CI_COMMIT_TAG commit tag name (empty if event is not tag)
CI_COMMIT_PULL_REQUEST commit pull request number (empty if event is not pull_request)
CI_COMMIT_PULL_REQUEST_LABELS labels assigned to pull request (empty if event is not pull_request)
CI_COMMIT_MESSAGE commit message
CI_COMMIT_AUTHOR commit author username
CI_COMMIT_AUTHOR_EMAIL commit author email address
CI_COMMIT_AUTHOR_AVATAR commit author avatar
Current pipeline
CI_PIPELINE_NUMBER pipeline number
CI_PIPELINE_PARENT number of parent pipeline
CI_PIPELINE_EVENT pipeline event (push, pull_request, tag, deployment, cron, manual)
CI_PIPELINE_URL link to the web UI for the pipeline
CI_PIPELINE_FORGE_URL link to the forge's web UI for the commit(s) or tag that triggered the pipeline
CI_PIPELINE_DEPLOY_TARGET pipeline deploy target for deployment events (ie production)
CI_PIPELINE_STATUS pipeline status (success, failure)
CI_PIPELINE_CREATED pipeline created UNIX timestamp
CI_PIPELINE_STARTED pipeline started UNIX timestamp
CI_PIPELINE_FINISHED pipeline finished UNIX timestamp
Current workflow
CI_WORKFLOW_NAME workflow name
Current step
CI_STEP_NAME step name
CI_STEP_NUMBER step number
CI_STEP_STATUS step status (success, failure)
CI_STEP_STARTED step started UNIX timestamp
CI_STEP_FINISHED step finished UNIX timestamp
CI_STEP_URL URL to step in UI
Previous commit
CI_PREV_COMMIT_SHA previous commit SHA
CI_PREV_COMMIT_REF previous commit ref
CI_PREV_COMMIT_REFSPEC previous commit ref spec
CI_PREV_COMMIT_BRANCH previous commit branch
CI_PREV_COMMIT_SOURCE_BRANCH previous commit source branch
CI_PREV_COMMIT_TARGET_BRANCH previous commit target branch
CI_PREV_COMMIT_URL previous commit link in forge
CI_PREV_COMMIT_MESSAGE previous commit message
CI_PREV_COMMIT_AUTHOR previous commit author username
CI_PREV_COMMIT_AUTHOR_EMAIL previous commit author email address
CI_PREV_COMMIT_AUTHOR_AVATAR previous commit author avatar
Previous pipeline
CI_PREV_PIPELINE_NUMBER previous pipeline number
CI_PREV_PIPELINE_PARENT previous pipeline number of parent pipeline
CI_PREV_PIPELINE_EVENT previous pipeline event (push, pull_request, tag, deployment)
CI_PREV_PIPELINE_URL previous pipeline link in CI
CI_PREV_PIPELINE_FORGE_URL previous pipeline link to event in forge
CI_PREV_PIPELINE_DEPLOY_TARGET previous pipeline deploy target for deployment events (ie production)
CI_PREV_PIPELINE_STATUS previous pipeline status (success, failure)
CI_PREV_PIPELINE_CREATED previous pipeline created UNIX timestamp
CI_PREV_PIPELINE_STARTED previous pipeline started UNIX timestamp
CI_PREV_PIPELINE_FINISHED previous pipeline finished UNIX timestamp
CI_WORKSPACE Path of the workspace where source code gets cloned to
System
CI_SYSTEM_NAME name of the CI system: woodpecker
CI_SYSTEM_URL link to CI system
CI_SYSTEM_HOST hostname of CI server
CI_SYSTEM_VERSION version of the server
Forge
CI_FORGE_TYPE name of forge (gitea, github, ...)
CI_FORGE_URL root URL of configured forge
Internal - Please don't use!
CI_SCRIPT Internal script path. Used to call pipeline step commands.
CI_NETRC_USERNAME Credentials for private repos to be able to clone data. (Only available for specific images)
CI_NETRC_PASSWORD Credentials for private repos to be able to clone data. (Only available for specific images)
CI_NETRC_MACHINE Credentials 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.

OPERATION DESCRIPTION
${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}