2023-10-17 08:31:08 +00:00
# Advanced usage
2022-07-17 16:25:56 +00:00
2023-10-17 08:31:08 +00:00
## Advanced YAML syntax
YAML has some advanced syntax features that can be used like variables to reduce duplication in your pipeline config:
### Anchors & aliases
2022-07-17 16:25:56 +00:00
You can use [YAML anchors & aliases ](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases ) as variables in your pipeline config.
To convert this:
2023-10-24 12:42:05 +00:00
2023-11-05 09:43:44 +00:00
```yaml
2023-06-07 10:04:37 +00:00
steps:
2022-07-17 16:25:56 +00:00
test:
image: golang:1.18
2022-07-18 21:08:13 +00:00
commands: go test ./...
2022-07-17 16:25:56 +00:00
build:
image: golang:1.18
2022-07-18 21:08:13 +00:00
commands: build
2022-07-17 16:25:56 +00:00
```
Just add a new section called **variables** like this:
```diff
+variables:
+ - & golang_image 'golang:1.18'
2023-06-07 10:04:37 +00:00
steps:
2022-07-17 16:25:56 +00:00
test:
- image: golang:1.18
+ image: *golang_image
2022-07-18 21:08:13 +00:00
commands: go test ./...
2022-07-17 16:25:56 +00:00
build:
- image: golang:1.18
+ image: *golang_image
2022-07-18 21:08:13 +00:00
commands: build
2022-07-17 16:25:56 +00:00
```
2023-10-17 08:31:08 +00:00
### Map merges and overwrites
2022-09-17 07:00:40 +00:00
2023-04-29 12:49:41 +00:00
```yaml
variables:
- & base-plugin-settings
2022-09-17 07:00:40 +00:00
target: dist
recursive: false
try: true
2023-04-29 12:49:41 +00:00
- & special-setting
special: true
- & some-plugin codeberg.org/6543/docker-images/print_env
2022-07-17 16:25:56 +00:00
2023-06-07 10:04:37 +00:00
steps:
2022-07-17 16:25:56 +00:00
develop:
2023-04-29 12:49:41 +00:00
image: *some-plugin
settings:
< < : [ * base-plugin-settings , * special-setting ] # merge two maps into an empty map
2022-07-17 16:25:56 +00:00
when:
branch: develop
2022-09-17 07:00:40 +00:00
main:
2023-04-29 12:49:41 +00:00
image: *some-plugin
2022-07-17 16:25:56 +00:00
settings:
2023-04-29 12:49:41 +00:00
< < : * base-plugin-settings # merge one map and . . .
try: false # ... overwrite original value
ongoing: false # ... adding a new value
2022-07-17 16:25:56 +00:00
when:
branch: main
```
2023-04-29 12:49:41 +00:00
2023-10-17 08:31:08 +00:00
### Sequence merges
2023-04-29 12:49:41 +00:00
```yaml
variables:
pre_cmds: & pre_cmds
2023-10-24 12:42:05 +00:00
- echo start
- whoami
2023-04-29 12:49:41 +00:00
post_cmds: & post_cmds
2023-10-24 12:42:05 +00:00
- echo stop
2023-04-29 12:49:41 +00:00
hello_cmd: & hello_cmd
2023-10-24 12:42:05 +00:00
- echo hello
2023-04-29 12:49:41 +00:00
2023-06-07 10:04:37 +00:00
steps:
2023-04-29 12:49:41 +00:00
step1:
image: debian
commands:
2023-10-24 12:42:05 +00:00
- < < : * pre_cmds # prepend a sequence
- echo exec step now do dedicated things
- < < : * post_cmds # append a sequence
2023-04-29 12:49:41 +00:00
step2:
image: debian
commands:
2023-10-24 12:42:05 +00:00
- < < : [* pre_cmds , * hello_cmd ] # prepend two sequences
- echo echo from second step
- < < : * post_cmds
2023-04-29 12:49:41 +00:00
```
2023-08-28 14:24:56 +00:00
2023-10-17 08:31:08 +00:00
### References
- [Official YAML specification ](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases )
- [YAML Cheatsheet ](https://learnxinyminutes.com/docs/yaml )
## Persisting environment data between steps
One can create a file containing environment variables, and then source it in each step that needs them.
2023-11-05 09:43:44 +00:00
```yaml
2023-10-17 08:31:08 +00:00
steps:
init:
image: bash
commands:
2023-10-24 12:42:05 +00:00
- echo "FOO=hello" >> envvars
- echo "BAR=world" >> envvars
2023-10-17 08:31:08 +00:00
debug:
image: bash
commands:
- source envvars
- echo $FOO
```
2024-01-11 17:43:54 +00:00
## Declaring global variables
2023-10-17 08:31:08 +00:00
2024-01-11 17:43:54 +00:00
As described in [Global environment variables ](./50-environment.md#global-environment-variables ), you can define global variables:
2023-10-17 08:31:08 +00:00
2024-01-11 17:43:54 +00:00
```ini
WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
2023-10-17 08:31:08 +00:00
```
2023-08-28 14:24:56 +00:00
2023-10-17 08:31:08 +00:00
Note that this tightly couples the server and app configurations (where the app is a completely separate application). But this is a good option for truly global variables which should apply to all steps in all pipelines for all apps.