From a143ef4779ec5d6373585b5336fa51ac9c42a167 Mon Sep 17 00:00:00 2001
From: lonix1 <40320097+lonix1@users.noreply.github.com>
Date: Fri, 21 Jul 2023 21:58:17 +0200
Subject: [PATCH] docs: advanced pipeline management (#2018)

Various ways to factor out common data in a pipeline file - having them
in one place rather than spread out over many pages, will help newbies
like me.
---
 docs/docs/20-usage/90-pipeline-management.md | 84 ++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 docs/docs/20-usage/90-pipeline-management.md

diff --git a/docs/docs/20-usage/90-pipeline-management.md b/docs/docs/20-usage/90-pipeline-management.md
new file mode 100644
index 000000000..e160922f3
--- /dev/null
+++ b/docs/docs/20-usage/90-pipeline-management.md
@@ -0,0 +1,84 @@
+# Advanced pipeline management
+
+## Using variables
+
+Once your pipeline starts to grow in size, it will become important to keep it DRY ("Don't Repeat Yourself") by using variables and environment variables. Depending on your specific need, there are a number of options.
+
+### YAML extensions
+
+As described in [Advanced YAML syntax](./35-advanced-yaml-syntax.md).
+
+```yml
+variables:
+  - &golang_image 'golang:1.18'
+
+ steps:
+   build:
+     image: *golang_image
+     commands: build
+```
+
+Note that the `golang_image` alias cannot be used with string interpolation. But this is otherwise a good option for most cases.
+
+### YAML extensions (alternate form)
+
+Another approach using YAML extensions:
+
+```yml
+variables:
+  - global_env: &global_env
+    - BASH_VERSION=1.2.3
+    - PATH_SRC=src/
+    - PATH_TEST=test/
+    - FOO=something
+
+steps:
+  build:
+    image: bash:${BASH_VERSION}
+    directory: ${PATH_SRC}
+    commands:
+      - make ${FOO} -o ${PATH_TEST}
+    environment: *global_env
+
+  test:
+    image: bash:${BASH_VERSION}
+    commands:
+      - test ${PATH_TEST}
+    environment:
+      - <<:*global_env
+      - ADDITIONAL_LOCAL="var value"
+```
+
+### Persisting environment data between steps
+
+One can create a file containing environment variables, and then source it in each step that needs them.
+
+```yml
+steps:
+  init:
+    image: bash
+    commands:
+      echo "FOO=hello" >> envvars
+      echo "BAR=world" >> envvars
+
+  debug:
+    image: bash
+    commands:
+      - source envvars
+      - echo $FOO
+```
+
+### Declaring global variables in `docker-compose.yml`
+
+As described in [Global environment variables](./50-environment.md#global-environment-variables), one can define global variables:
+
+```yml
+services:
+  woodpecker-server:
+    # ...
+    environment:
+      - WOODPECKER_ENVIRONMENT=first_var:value1,second_var:value2
+      # ...
+```
+
+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.