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:
```diff
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.
```diff
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:
```diff
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.
| `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.
These can be used, for example, to manage the image tag used by multiple projects.
```diff
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:
```diff
steps:
docker:
image: plugins/docker
settings:
+ tags: ${CI_COMMIT_SHA}
```
Example tag substitution:
```diff
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.
