From 37f7da515913fb8902e66a4ad175c2614788d30a Mon Sep 17 00:00:00 2001 From: Bastian Greshake Tzovaras Date: Sat, 14 Dec 2024 10:43:32 -0300 Subject: [PATCH] Expand docs around the deprecation of former secret syntax (#4561) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Thomas Anderson <127358482+zc-devs@users.noreply.github.com> Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com> --- docs/docs/20-usage/40-secrets.md | 18 ++++++++++---- .../version-2.8/20-usage/40-secrets.md | 24 +++++++++++++++---- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/docs/20-usage/40-secrets.md b/docs/docs/20-usage/40-secrets.md index 2c7065815..de120300c 100644 --- a/docs/docs/20-usage/40-secrets.md +++ b/docs/docs/20-usage/40-secrets.md @@ -11,17 +11,27 @@ Woodpecker provides three different levels to add secrets to your pipeline. The ## Usage -You can set a setting or an environment value from secrets using the `from_secret` syntax. +You can set a setting or environment value from secrets using the `from_secret` syntax. -In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`. +The example below passes a secret called `secret_token` as an environment variable that will be called `TOKEN_ENV`: ```diff steps: - - name: docker - image: my-plugin + env-secret-example: + image: alpine + commands: ++ - echo "The secret is $TOKEN_ENV" + environment: + TOKEN_ENV: + from_secret: secret_token +``` + +You can use the same syntax to pass secrets to settings. For example, you can pass a secret named `secret_token` to the settings called `token`, which will then be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details). + +```diff + steps: + - name: settings-secret-example + image: my-plugin + settings: + token: + from_secret: secret_token diff --git a/docs/versioned_docs/version-2.8/20-usage/40-secrets.md b/docs/versioned_docs/version-2.8/20-usage/40-secrets.md index 1b55d9ce1..2666ea86f 100644 --- a/docs/versioned_docs/version-2.8/20-usage/40-secrets.md +++ b/docs/versioned_docs/version-2.8/20-usage/40-secrets.md @@ -13,6 +13,12 @@ Woodpecker provides three different levels to add secrets to your pipeline. The ### Use secrets in commands +:::warning +The use of secrets is deprecated as of version 2.8 and planned to be removed with version 3. +Instead, you can use the *secrets in settings and environment* approach outlined below. +You can already migrate to this strategy with version 2.8. +::: + Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline, once their usage is declared in the `secrets` section: @@ -30,17 +36,27 @@ The case of the environment variables is not changed, but secret matching is don ### Use secrets in settings and environment -You can set an setting or environment value from secrets using the `from_secret` syntax. +You can set a setting or environment value from secrets using the `from_secret` syntax. -In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`. +The example below passes a secret called `secret_token` as an environment variable that will be called `TOKEN_ENV`: ```diff steps: - - name: docker - image: my-plugin + env-secret-example: + image: alpine + commands: ++ - echo "The secret is $TOKEN_ENV" + environment: + TOKEN_ENV: + from_secret: secret_token +``` + +You can use the same syntax to pass secrets to settings. For example, you can pass a secret named `secret_token` to the settings called `token`, which will then be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details). + +```diff + steps: + - name: settings-secret-example + image: my-plugin + settings: + token: + from_secret: secret_token