From 05fdc8dbd2d28ee0bdf4d1e51d54e29cba8c7978 Mon Sep 17 00:00:00 2001 From: Tauhid Anjum Date: Tue, 17 Jan 2023 09:07:08 +0530 Subject: [PATCH] Variables docs additions and corrections (#33908) Co-authored-by: Lucas Costi --- .../using-environments-for-deployment.md | 15 ++++++++++++++- content/actions/learn-github-actions/variables.md | 14 ++++++++------ .../enabling-debug-logging.md | 13 +++++-------- .../actions/security-guides/encrypted-secrets.md | 4 ++-- ...tory-and-organization-for-github-codespaces.md | 2 +- ...aging-encrypted-secrets-for-your-codespaces.md | 2 +- 6 files changed, 31 insertions(+), 19 deletions(-) diff --git a/content/actions/deployment/targeting-different-environments/using-environments-for-deployment.md b/content/actions/deployment/targeting-different-environments/using-environments-for-deployment.md index c6106c5b56..1408882970 100644 --- a/content/actions/deployment/targeting-different-environments/using-environments-for-deployment.md +++ b/content/actions/deployment/targeting-different-environments/using-environments-for-deployment.md @@ -65,6 +65,12 @@ Secrets stored in an environment are only available to workflow jobs that refere {% endnote %} +{% ifversion actions-configuration-variables %} +## Environment variables + +Variables stored in an environment are only available to workflow jobs that reference the environment. These variables are only accessible using the [`vars`](/actions/learn-github-actions/contexts#vars-context) context. For more information, see "[Variables](/actions/learn-github-actions/variables)." +{% endif %} + ## Creating an environment {% data reusables.actions.permissions-statement-environment %} @@ -98,8 +104,15 @@ Secrets stored in an environment are only available to workflow jobs that refere 1. Enter the secret name. 1. Enter the secret value. 1. Click **Add secret**. +{%- ifversion actions-configuration-variables %} +5. Optionally, add environment variables. These variables are only available to workflow jobs that use the environment, and are only accessible using the [`vars`](/actions/learn-github-actions/contexts#vars-context) context. For more information, see "[Variables](/actions/learn-github-actions/variables)." + 1. Under **Environment variables**, click **Add Variable**. + 1. Enter the variable name. + 1. Enter the variable value. + 1. Click **Add variable**. +{%- endif %} -You can also create and configure environments through the REST API. For more information, see "[Deployment environments](/rest/deployments/environments)," "[GitHub Actions Secrets](/rest/actions/secrets)," and "[Deployment branch policies](/rest/deployments/branch-policies)." +You can also create and configure environments through the REST API. For more information, see "[Deployment environments](/rest/deployments/environments)," "[{% data variables.product.prodname_actions %} Secrets](/rest/actions/secrets),"{% ifversion actions-configuration-variables %} "[{% data variables.product.prodname_actions %} Variables](/rest/actions/variables),"{% endif %} and "[Deployment branch policies](/rest/deployments/branch-policies)." Running a workflow that references an environment that does not exist will create an environment with the referenced name. The newly created environment will not have any protection rules or secrets configured. Anyone that can edit workflows in the repository can create environments via a workflow file, but only repository admins can configure the environment. diff --git a/content/actions/learn-github-actions/variables.md b/content/actions/learn-github-actions/variables.md index c7779a2d02..ed7521a078 100644 --- a/content/actions/learn-github-actions/variables.md +++ b/content/actions/learn-github-actions/variables.md @@ -80,6 +80,12 @@ You can access `env` variable values using runner environment variables or using Because runner environment variable interpolation is done after a workflow job is sent to a runner machine, you must use the appropriate syntax for the shell that's used on the runner. In this example, the workflow specifies `ubuntu-latest`. By default, Linux runners use the bash shell, so you must use the syntax `$NAME`. If the workflow specified a Windows runner, you would use the syntax for PowerShell, `$env:NAME`. For more information about shells, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsshell)." +### Naming conventions for environment variables + +When you set an environment variable, you cannot use any of the default environment variable names. For a complete list of default environment variables, see "[Default environment variables](#default-environment-variables)" below. If you attempt to override the value of one of these default variables, the assignment is ignored. + +Any new variables you set that point to a location on the filesystem should have a `_PATH` suffix. The `GITHUB_ENV` and `GITHUB_WORKSPACE` default variables are exceptions to this convention. + {% note %} **Note**: You can list the entire set of environment variables that are available to a workflow step by using `run: env` in a step and then examining the output for the step. @@ -102,14 +108,10 @@ When you define configuration variables, they are automatically available in the If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence. For example, if an organization-level variable has the same name as a repository-level variable, then the repository-level variable takes precedence. Similarly, if an organization, repository, and environment all have a variable with the same name, the environment-level variable takes precedence. -If a repository contains reusable workflows, its configuration variables are automatically made available to the caller workflows with the `vars` context. However, if the same variable name is used in the caller and the called workflow repositories, the variable from the caller workflow repository is be used. +For reusable workflows, the variables from the caller workflow's repository are used. Variables from the repository that contains the called workflow are not made available to the caller workflow. ### Naming conventions for configuration variables -When you set a custom variable, you cannot use any of the default environment variable names. For a complete list of default environment variables, see "[Default environment variables](#default-environment-variables)" below. If you attempt to override the value of one of these default variables, the assignment is ignored. - -Any new variables you set that point to a location on the filesystem should have a `_PATH` suffix. The `GITHUB_ENV` and `GITHUB_WORKSPACE` default variables are exceptions to this convention. - The following rules apply to configuration variable names: {% data reusables.actions.actions-secrets-and-variables-naming %} @@ -165,7 +167,7 @@ A workflow created in a repository can access the following number of variables: * If the repository is assigned access to more than 100 organization variables, the workflow can only use the first 100 organization variables (sorted alphabetically by variable name). * All 100 environment variables. -Variables are limited to 64 KB in size. +Variables are limited to 48 KB in size. {% endif %} diff --git a/content/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging.md b/content/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging.md index 66a76c21dc..3296955399 100644 --- a/content/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging.md +++ b/content/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging.md @@ -14,14 +14,13 @@ versions: {% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-github-hosted-runners %} -These extra logs are enabled by setting secrets in the repository containing the workflow, so the same permissions requirements will apply: +These extra logs are enabled by setting secrets{% ifversion actions-configuration-variables %} or variables{% endif %} in the repository containing the workflow, so the same permissions requirements will apply: - {% data reusables.actions.permissions-statement-secrets-variables-repository %} - {% data reusables.actions.permissions-statement-secrets-environment %} - {% data reusables.actions.permissions-statement-secrets-and-variables-organization %} -- {% data reusables.actions.permissions-statement-secrets-api %} -For more information on setting secrets, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." +For more information on setting secrets{% ifversion actions-configuration-variables %} and variables, see "[Encrypted secrets](/actions/security-guides/encrypted-secrets)" and "[Variables](/actions/learn-github-actions/variables)."{% else %}, see "[Encrypted secrets](/actions/security-guides/encrypted-secrets)."{% endif %} {% ifversion debug-reruns %} @@ -36,14 +35,12 @@ Runner diagnostic logging provides additional log files that contain information * The runner process log, which includes information about coordinating and setting up runners to execute jobs. * The worker process log, which logs the execution of a job. -1. To enable runner diagnostic logging, set the following secret in the repository that contains the workflow: `ACTIONS_RUNNER_DEBUG` to `true`. - +1. To enable runner diagnostic logging, set the following secret{% ifversion actions-configuration-variables %} or variable{% endif %} in the repository that contains the workflow: `ACTIONS_RUNNER_DEBUG` to `true`.{% ifversion actions-configuration-variables %} If both the secret and variable are set, the value of the secret takes precedence over the variable.{% endif %} 1. To download runner diagnostic logs, download the log archive of the workflow run. The runner diagnostic logs are contained in the `runner-diagnostic-logs` folder. For more information on downloading logs, see "[Downloading logs](/actions/managing-workflow-runs/using-workflow-run-logs/#downloading-logs)." ## Enabling step debug logging Step debug logging increases the verbosity of a job's logs during and after a job's execution. -1. To enable step debug logging, you must set the following secret in the repository that contains the workflow: `ACTIONS_STEP_DEBUG` to `true`. - -1. After setting the secret, more debug events are shown in the step logs. For more information, see ["Viewing logs to diagnose failures"](/actions/managing-workflow-runs/using-workflow-run-logs/#viewing-logs-to-diagnose-failures). +1. To enable step debug logging, set the following secret{% ifversion actions-configuration-variables %} or variable{% endif %} in the repository that contains the workflow: `ACTIONS_STEP_DEBUG` to `true`.{% ifversion actions-configuration-variables %} If both the secret and variable are set, the value of the secret takes precedence over the variable.{% endif %} +1. After setting the secret{% ifversion actions-configuration-variables %} or variable{% endif %}, more debug events are shown in the step logs. For more information, see ["Viewing logs to diagnose failures"](/actions/managing-workflow-runs/using-workflow-run-logs/#viewing-logs-to-diagnose-failures). diff --git a/content/actions/security-guides/encrypted-secrets.md b/content/actions/security-guides/encrypted-secrets.md index e26ce1dd22..b48e92d408 100644 --- a/content/actions/security-guides/encrypted-secrets.md +++ b/content/actions/security-guides/encrypted-secrets.md @@ -303,11 +303,11 @@ A workflow created in a repository can access the following number of secrets: * If the repository is assigned access to more than 100 organization secrets, the workflow can only use the first 100 organization secrets (sorted alphabetically by secret name). * All 100 environment secrets. -Secrets are limited to 64 KB in size. To store larger secrets, see the "[Storing large secrets](#storing-large-secrets)" workaround below. +Secrets are limited to 48 KB in size. To store larger secrets, see the "[Storing large secrets](#storing-large-secrets)" workaround below. ### Storing large secrets -To use secrets that are larger than 64 KB, you can use a workaround to store encrypted secrets in your repository and save the decryption passphrase as a secret on {% data variables.product.prodname_dotcom %}. For example, you can use `gpg` to encrypt a file containing your secret locally before checking the encrypted file in to your repository on {% data variables.product.prodname_dotcom %}. For more information, see the "[gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html)." +To use secrets that are larger than 48 KB, you can use a workaround to store encrypted secrets in your repository and save the decryption passphrase as a secret on {% data variables.product.prodname_dotcom %}. For example, you can use `gpg` to encrypt a file containing your secret locally before checking the encrypted file in to your repository on {% data variables.product.prodname_dotcom %}. For more information, see the "[gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html)." {% warning %} diff --git a/content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces.md b/content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces.md index 288914c3ad..06a6adfdc3 100644 --- a/content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces.md +++ b/content/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces.md @@ -34,7 +34,7 @@ Organization-level secrets let you share secrets between multiple repositories, You can store up to 100 secrets per organization and 100 secrets per repository. -Secrets are limited to 64 KB in size. +Secrets are limited to 48 KB in size. ## Adding secrets for a repository diff --git a/content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md b/content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md index 4d2b46f721..995d783399 100644 --- a/content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md +++ b/content/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces.md @@ -42,7 +42,7 @@ You can choose which repositories should have access to each secret. Then, you c You can store up to 100 secrets for {% data variables.product.prodname_github_codespaces %}. -Secrets are limited to 64 KB in size. +Secrets are limited to 48 KB in size. ## Adding a secret