From 352c6768b25c1cacf70754e5478a923d3a438ea5 Mon Sep 17 00:00:00 2001 From: John Marshall Date: Mon, 24 May 2021 20:57:33 +0100 Subject: [PATCH 1/6] Describe $RUNNER_OS/etc environment variables Runners set up environment variables corresponding to the runner context's properties. The runner context documents the runner.os, runner.temp, and runner.tool_cache properties, so document these three as supported environment variables similarly. The tool_cache property value is not documented as being used for GitHub AE (see context-and-expression-syntax-for-github-actions.md), so just leave $RUNNER_TOOL_CACHE undocumented in this case. --- content/actions/reference/environment-variables.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index 5a22e11026af..e90f5d75781d 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -72,6 +72,9 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_SERVER_URL`| Returns the URL of the {% data variables.product.product_name %} server. For example: `https://{% data variables.product.product_url %}`. | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`. +| `RUNNER_OS` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. +| `RUNNER_TEMP` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. +{% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} {% tip %} From c0800a4ddb8439e5eb6a03ce082ff3a44aee0dd0 Mon Sep 17 00:00:00 2001 From: Martin Lopes Date: Wed, 2 Jun 2021 13:39:15 +1000 Subject: [PATCH 2/6] Added some edits (pending validation) --- content/actions/reference/environment-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index e90f5d75781d..94ff99dd7afc 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -73,8 +73,8 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`. | `RUNNER_OS` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. -| `RUNNER_TEMP` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. -{% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} +| `RUNNER_TEMP` | The path to a temporary directory on the runner. This directory is emptied after each job completes. +{% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path to the directory containing preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} {% tip %} From 031ae8476c5aca6d57c6463b75c9eeb6173084a1 Mon Sep 17 00:00:00 2001 From: Martin Lopes Date: Wed, 16 Jun 2021 09:10:24 +1000 Subject: [PATCH 3/6] Added update from dev feedback --- content/actions/reference/environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index 94ff99dd7afc..d5d102b35caf 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -73,7 +73,7 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`. | `RUNNER_OS` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. -| `RUNNER_TEMP` | The path to a temporary directory on the runner. This directory is emptied after each job completes. +| `RUNNER_TEMP` | The path to a temporary directory on the runner. This directory is emptied at the beginning and end of each job. Note that files will not be removed if the runner's user account does not have permission to delete them. {% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path to the directory containing preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} {% tip %} From 65b17ff946d6f03447443b890ef200d78b071df5 Mon Sep 17 00:00:00 2001 From: Martin Lopes Date: Wed, 16 Jun 2021 09:39:41 +1000 Subject: [PATCH 4/6] Moved runner temp descriptions into reusable --- .../context-and-expression-syntax-for-github-actions.md | 2 +- content/actions/reference/environment-variables.md | 2 +- data/reusables/actions/runner-temp-directory-description.md | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 data/reusables/actions/runner-temp-directory-description.md diff --git a/content/actions/reference/context-and-expression-syntax-for-github-actions.md b/content/actions/reference/context-and-expression-syntax-for-github-actions.md index 977b5016e726..37360c74ac27 100644 --- a/content/actions/reference/context-and-expression-syntax-for-github-actions.md +++ b/content/actions/reference/context-and-expression-syntax-for-github-actions.md @@ -161,7 +161,7 @@ The `runner` context contains information about the runner that is executing the | Property name | Type | Description | |---------------|------|-------------| | `runner.os` | `string` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. | -| `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. | +| `runner.temp` | `string` | {% data reusables.actions.runner-temp-directory-description %} | | `runner.tool_cache` | `string` | {% if currentVersion == "github-ae@latest" %}For instructions on how to make sure your {% data variables.actions.hosted_runner %} has the required software installed, see "[Creating custom images](/actions/using-github-hosted-runners/creating-custom-images)." {% else %}The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% endif %}| diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index 23568ce81999..e17cb3944380 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -73,7 +73,7 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`. | `RUNNER_OS` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. -| `RUNNER_TEMP` | The path to a temporary directory on the runner. This directory is emptied at the beginning and end of each job. Note that files will not be removed if the runner's user account does not have permission to delete them. +| `RUNNER_TEMP` | {% data reusables.actions.runner-temp-directory-description %} {% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path to the directory containing preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} {% tip %} diff --git a/data/reusables/actions/runner-temp-directory-description.md b/data/reusables/actions/runner-temp-directory-description.md new file mode 100644 index 000000000000..cf57265d75c1 --- /dev/null +++ b/data/reusables/actions/runner-temp-directory-description.md @@ -0,0 +1 @@ +The path to a temporary directory on the runner. This directory is emptied at the beginning and end of each job. Note that files will not be removed if the runner's user account does not have permission to delete them. From 4f692c9a3ba4c5c6e690eb128823fa69b4501459 Mon Sep 17 00:00:00 2001 From: Martin Lopes Date: Wed, 16 Jun 2021 11:19:16 +1000 Subject: [PATCH 5/6] Moved remaining descriptions into reusables --- .../context-and-expression-syntax-for-github-actions.md | 4 ++-- content/actions/reference/environment-variables.md | 4 ++-- data/reusables/actions/runner-os-description.md | 1 + data/reusables/actions/runner-tool-cache-description.md | 1 + 4 files changed, 6 insertions(+), 4 deletions(-) create mode 100644 data/reusables/actions/runner-os-description.md create mode 100644 data/reusables/actions/runner-tool-cache-description.md diff --git a/content/actions/reference/context-and-expression-syntax-for-github-actions.md b/content/actions/reference/context-and-expression-syntax-for-github-actions.md index 37360c74ac27..b0e674e79f80 100644 --- a/content/actions/reference/context-and-expression-syntax-for-github-actions.md +++ b/content/actions/reference/context-and-expression-syntax-for-github-actions.md @@ -160,10 +160,10 @@ The `runner` context contains information about the runner that is executing the | Property name | Type | Description | |---------------|------|-------------| -| `runner.os` | `string` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. | +| `runner.os` | `string` | {% data reusables.actions.runner-os-description %} | | `runner.temp` | `string` | {% data reusables.actions.runner-temp-directory-description %} | | `runner.tool_cache` | `string` | {% if currentVersion == "github-ae@latest" %}For instructions on how to make sure your {% data variables.actions.hosted_runner %} has the required software installed, see "[Creating custom images](/actions/using-github-hosted-runners/creating-custom-images)." -{% else %}The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% endif %}| +{% else %} {% data reusables.actions.runner-tool-cache-description %} {% endif %}| ### `needs` context diff --git a/content/actions/reference/environment-variables.md b/content/actions/reference/environment-variables.md index e17cb3944380..b5a07413c072 100644 --- a/content/actions/reference/environment-variables.md +++ b/content/actions/reference/environment-variables.md @@ -72,9 +72,9 @@ We strongly recommend that actions use environment variables to access the files | `GITHUB_SERVER_URL`| Returns the URL of the {% data variables.product.product_name %} server. For example: `https://{% data variables.product.product_url %}`. | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`. -| `RUNNER_OS` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. +| `RUNNER_OS` | {% data reusables.actions.runner-os-description %} | `RUNNER_TEMP` | {% data reusables.actions.runner-temp-directory-description %} -{% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | The path to the directory containing preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".{% endif %} +{% if currentVersion != "github-ae@latest" %}| `RUNNER_TOOL_CACHE` | {% data reusables.actions.runner-tool-cache-description %}{% endif %} {% tip %} diff --git a/data/reusables/actions/runner-os-description.md b/data/reusables/actions/runner-os-description.md new file mode 100644 index 000000000000..2cb82a773284 --- /dev/null +++ b/data/reusables/actions/runner-os-description.md @@ -0,0 +1 @@ +The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. diff --git a/data/reusables/actions/runner-tool-cache-description.md b/data/reusables/actions/runner-tool-cache-description.md new file mode 100644 index 000000000000..d9674e873786 --- /dev/null +++ b/data/reusables/actions/runner-tool-cache-description.md @@ -0,0 +1 @@ +The path to the directory containing preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". From 672b0468459593c392bedfb3ae175db3119ce645 Mon Sep 17 00:00:00 2001 From: Martin Lopes Date: Wed, 16 Jun 2021 11:29:44 +1000 Subject: [PATCH 6/6] Small fix --- .../context-and-expression-syntax-for-github-actions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/actions/reference/context-and-expression-syntax-for-github-actions.md b/content/actions/reference/context-and-expression-syntax-for-github-actions.md index b0e674e79f80..6e0bbed14b76 100644 --- a/content/actions/reference/context-and-expression-syntax-for-github-actions.md +++ b/content/actions/reference/context-and-expression-syntax-for-github-actions.md @@ -162,8 +162,7 @@ The `runner` context contains information about the runner that is executing the |---------------|------|-------------| | `runner.os` | `string` | {% data reusables.actions.runner-os-description %} | | `runner.temp` | `string` | {% data reusables.actions.runner-temp-directory-description %} | -| `runner.tool_cache` | `string` | {% if currentVersion == "github-ae@latest" %}For instructions on how to make sure your {% data variables.actions.hosted_runner %} has the required software installed, see "[Creating custom images](/actions/using-github-hosted-runners/creating-custom-images)." -{% else %} {% data reusables.actions.runner-tool-cache-description %} {% endif %}| +| `runner.tool_cache` | `string` | {% if currentVersion == "github-ae@latest" %}For instructions on how to make sure your {% data variables.actions.hosted_runner %} has the required software installed, see "[Creating custom images](/actions/using-github-hosted-runners/creating-custom-images)." {% else %} {% data reusables.actions.runner-tool-cache-description %} {% endif %}| ### `needs` context