From fd1b62ebb653e229cd07807d709270bc2c4a9e73 Mon Sep 17 00:00:00 2001 From: Brendon Smith Date: Tue, 7 Dec 2021 17:44:12 -0500 Subject: [PATCH 1/5] :lock: Document how to use secrets with `if:` github/docs#6861 github/docs#12722 - Add a complete workflow example to `jobs..steps[*].if`, demonstrating how to skip a step if a secret is not present - Add an explanation to "Using encrypted secrets in a workflow" - Cross-reference the two pages --- .../security-guides/encrypted-secrets.md | 4 +++ .../workflow-syntax-for-github-actions.md | 28 +++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/content/actions/security-guides/encrypted-secrets.md b/content/actions/security-guides/encrypted-secrets.md index e6a4f5b110c6..1a11115c668a 100644 --- a/content/actions/security-guides/encrypted-secrets.md +++ b/content/actions/security-guides/encrypted-secrets.md @@ -227,6 +227,10 @@ steps: ``` {% endraw %} +Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. For more information, see "[Context availability](/actions/learn-github-actions/contexts#context-availability)" and [`jobs..steps[*].if`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif). + +If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SuperSecret }}` in the example) will be an empty string. + Avoid passing secrets between processes from the command line, whenever possible. Command-line processes may be visible to other users (using the `ps` command) or captured by [security audit events](https://docs.microsoft.com/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing). To help protect secrets, consider using environment variables, `STDIN`, or other mechanisms supported by the target process. If you must pass secrets within a command line, then enclose them within the proper quoting rules. Secrets often contain special characters that may unintentionally affect your shell. To escape these special characters, use quoting with your environment variables. For example: diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 4623da349ce3..e156467f2996 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -342,6 +342,34 @@ steps: uses: actions/heroku@1.0.0 ``` +### Example: Using secrets + +Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. + +The example assumes there is a secret named `SECRET_IS_SET`. + +{% raw %} +```yaml +name: Run a step if a secret has been set +on: push +jobs: + my-jobname: + runs-on: ubuntu-latest + env: + SECRET_IS_SET: ${{ secrets.SECRET_IS_SET }} + SECRET_IS_NOT_SET: ${{ secrets.SECRET_IS_NOT_SET }} + steps: + - if: ${{ env.SECRET_IS_SET }} + run: echo 'This secret has a value set.' + - if: ${{ env.SECRET_IS_NOT_SET }} + run: echo 'This step should be skipped.' +``` +{% endraw %} + +If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SECRET_IS_NOT_SET }}` in the example) will be an empty string. + +For more information, see "[Context availability](/actions/learn-github-actions/contexts#context-availability)" and "[Encrypted secrets](/actions/security-guides/encrypted-secrets)." + ### `jobs..steps[*].name` A name for your step to display on {% data variables.product.prodname_dotcom %}. From 0ea4ebdd753f8e81933e6ce8ef90f29cdfada689 Mon Sep 17 00:00:00 2001 From: Brendon Smith Date: Sat, 12 Feb 2022 18:34:52 -0500 Subject: [PATCH 2/5] :lock: Compare secrets with empty strings in `if:` github/docs#6861 https://github.com/github/docs/pull/12722#discussion_r801011000 Rather than referencing two secrets: 1. `${{ secrets.SECRET_IS_SET }}` 2. `${{ secrets.SECRET_IS_NOT_SET }}`) This commit will update the related section of the docs to reference a single secret (`${{ secrets.SECRET_IS_SET }}`), and will update the `if:` conditionals to compare with empty strings as suggested. --- .../workflow-syntax-for-github-actions.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index e156467f2996..7a2ceda0876f 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -346,7 +346,7 @@ steps: Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. -The example assumes there is a secret named `SECRET_IS_SET`. +If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SECRET_IS_SET }}` in the example) will be an empty string. {% raw %} ```yaml @@ -357,17 +357,14 @@ jobs: runs-on: ubuntu-latest env: SECRET_IS_SET: ${{ secrets.SECRET_IS_SET }} - SECRET_IS_NOT_SET: ${{ secrets.SECRET_IS_NOT_SET }} steps: - - if: ${{ env.SECRET_IS_SET }} - run: echo 'This secret has a value set.' - - if: ${{ env.SECRET_IS_NOT_SET }} - run: echo 'This step should be skipped.' + - if: ${{ env.SECRET_IS_SET != '' }} + run: echo 'This step will only run if the secret has a value set.' + - if: ${{ env.SECRET_IS_SET == '' }} + run: echo 'This step will only run if the secret does not have a value set.' ``` {% endraw %} -If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SECRET_IS_NOT_SET }}` in the example) will be an empty string. - For more information, see "[Context availability](/actions/learn-github-actions/contexts#context-availability)" and "[Encrypted secrets](/actions/security-guides/encrypted-secrets)." ### `jobs..steps[*].name` From e8b1ecf968ff30823138b7ba8f17e6ff730cb2c8 Mon Sep 17 00:00:00 2001 From: Brendon Smith Date: Sat, 12 Feb 2022 18:58:24 -0500 Subject: [PATCH 3/5] :lock: Add missing `{% raw %}`/`{% endraw %}` github/docs#6861 github/docs#12722 Some `${{ }}` values were converted to `$` in the preview environment. Adding `{% raw %}`/`{% endraw %}` will preserve the raw value. --- content/actions/security-guides/encrypted-secrets.md | 2 +- .../using-workflows/workflow-syntax-for-github-actions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/actions/security-guides/encrypted-secrets.md b/content/actions/security-guides/encrypted-secrets.md index 1a11115c668a..d202e8bfb094 100644 --- a/content/actions/security-guides/encrypted-secrets.md +++ b/content/actions/security-guides/encrypted-secrets.md @@ -229,7 +229,7 @@ steps: Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. For more information, see "[Context availability](/actions/learn-github-actions/contexts#context-availability)" and [`jobs..steps[*].if`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif). -If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SuperSecret }}` in the example) will be an empty string. +If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SuperSecret }}`{% endraw %} in the example) will be an empty string. Avoid passing secrets between processes from the command line, whenever possible. Command-line processes may be visible to other users (using the `ps` command) or captured by [security audit events](https://docs.microsoft.com/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing). To help protect secrets, consider using environment variables, `STDIN`, or other mechanisms supported by the target process. diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 7a2ceda0876f..e02845ac4d4b 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -346,7 +346,7 @@ steps: Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. -If a secret has not been set, the return value of an expression referencing the secret (such as `${{ secrets.SECRET_IS_SET }}` in the example) will be an empty string. +If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SECRET_IS_SET }}`{% endraw %} in the example) will be an empty string. {% raw %} ```yaml From f1b635984e6db5652c63338016271e237b1092eb Mon Sep 17 00:00:00 2001 From: Brendon Smith Date: Mon, 14 Mar 2022 23:05:54 -0400 Subject: [PATCH 4/5] :lock: Match variable and secret names in examples github/docs#6861 https://github.com/github/docs/pull/12722#discussion_r801011000 This PR adds an example of how to use secrets with `if:` conditionals. The reviewer suggested comparing variable values with empty strings to make the `if:` conditionals clearer. Commit cecdf00 updated the secret names accordingly, but the names of the secret and environment variable may still have been confusing. This commit will update the secret and environment variable names to match the cross-referenced example on the "Encrypted secrets" page. --- .../using-workflows/workflow-syntax-for-github-actions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index e02845ac4d4b..e5fa2831a575 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -346,7 +346,7 @@ steps: Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. -If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SECRET_IS_SET }}`{% endraw %} in the example) will be an empty string. +If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SuperSecret }}`{% endraw %} in the example) will be an empty string. {% raw %} ```yaml @@ -356,11 +356,11 @@ jobs: my-jobname: runs-on: ubuntu-latest env: - SECRET_IS_SET: ${{ secrets.SECRET_IS_SET }} + super_secret: ${{ secrets.SuperSecret }} steps: - - if: ${{ env.SECRET_IS_SET != '' }} + - if: ${{ env.super_secret != '' }} run: echo 'This step will only run if the secret has a value set.' - - if: ${{ env.SECRET_IS_SET == '' }} + - if: ${{ env.super_secret == '' }} run: echo 'This step will only run if the secret does not have a value set.' ``` {% endraw %} From da74eb7235d1c367654df9957264696c062d647a Mon Sep 17 00:00:00 2001 From: hubwriter Date: Thu, 17 Mar 2022 10:31:54 +0000 Subject: [PATCH 5/5] Update content/actions/using-workflows/workflow-syntax-for-github-actions.md --- .../using-workflows/workflow-syntax-for-github-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 662b0e3f0290..40e81f395f75 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -342,7 +342,7 @@ steps: uses: actions/heroku@1.0.0 ``` -### Example: Using secrets +#### Example: Using secrets Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.