Skip to content

Commit f219414

Browse files
bdehamerCopilotjc-clark
authored
docs: add GITHUB_ARTIFACTS and GITHUB_ARTIFACTS_LIST env files (#62574)
Signed-off-by: Brian DeHamer <bdehamer@github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> Copilot-Session: 68bd6853-1101-4aa0-80d5-da928dc71905
1 parent c82c687 commit f219414

4 files changed

Lines changed: 109 additions & 0 deletions

File tree

‎content/actions/reference/workflows-and-actions/contexts.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,10 @@ The `github` context contains information about the workflow run and the event t
181181
| `github.actor` | `string` | The username of the user that triggered the initial workflow run. If the workflow run is a re-run, this value may differ from `github.triggering_actor`. Any workflow re-runs will use the privileges of `github.actor`, even if the actor initiating the re-run (`github.triggering_actor`) has different privileges. |
182182
| `github.actor_id` | `string` | {% data reusables.actions.actor_id-description %} |
183183
| `github.api_url` | `string` | The URL of the {% data variables.product.prodname_dotcom %} REST API. |
184+
| {% ifversion actions-artifacts-file %} |
185+
| `github.artifacts` | `string` | Path on the runner to the file that identifies workflow artifacts for the current step. Write one declaration per line to identify files or OCI digest references as workflow artifacts. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#declaring-workflow-artifacts). |
186+
| `github.artifacts_list` | `string` | Path on the runner to a read-only file containing the aggregated workflow artifact metadata for the current job as JSON. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#reading-workflow-artifacts). |
187+
| {% endif %} |
184188
| `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. |
185189
| `github.env` | `string` | Path on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#setting-an-environment-variable). |
186190
| `github.event` | `object` | The full event webhook payload. You can access individual properties of the event using this context. This object is identical to the webhook payload of the event that triggered the workflow run, and is different for each event. The webhooks for each {% data variables.product.prodname_actions %} event is linked in [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_call). For example, for a workflow run triggered by the [`push` event](/actions/reference/workflows-and-actions/events-that-trigger-workflows#push), this object contains the contents of the [push webhook payload](/webhooks/webhook-events-and-payloads#push). |

‎content/actions/reference/workflows-and-actions/variables.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ We strongly recommend that actions use variables to access the filesystem rather
3737
| `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. |
3838
| `GITHUB_ACTOR_ID` | {% data reusables.actions.actor_id-description %} |
3939
| `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.rest_url %}`. |
40+
| {% ifversion actions-artifacts-file %} |
41+
| `GITHUB_ARTIFACTS` | The path on the runner to the file that declares workflow artifacts for the current step. Write one declaration per line to identify files or OCI digest references as workflow artifacts. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#declaring-workflow-artifacts). |
42+
| `GITHUB_ARTIFACTS_LIST` | The path on the runner to a read-only file that contains aggregated workflow artifact metadata for the current job as a JSON object. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#reading-workflow-artifacts). |
43+
| {% endif %} |
4044
| `GITHUB_BASE_REF` | The name of the base ref or target branch of the pull request in a workflow run. This is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `main`. |
4145
| `GITHUB_ENV` | The path on the runner to the file that sets variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a`. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-commands#setting-an-environment-variable). |
4246
| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. For example, `workflow_dispatch`. |

‎content/actions/reference/workflows-and-actions/workflow-commands.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -959,3 +959,98 @@ This example demonstrates how to add the user `$env:HOMEPATH/.local/bin` directo
959959
```
960960

961961
{% endpowershell %}
962+
963+
{% ifversion actions-artifacts-file %}
964+
965+
## Declaring workflow artifacts
966+
967+
Declare files or OCI references as workflow artifacts by writing one declaration per line to the `GITHUB_ARTIFACTS` environment file. Each step writes to a fresh, per-step file; the path is unique to that step.
968+
969+
Metadata about declared artifacts is collected across all steps in a job and exposed through the `GITHUB_ARTIFACTS_LIST` file.
970+
971+
Each line must be one of the following formats. Blank lines and lines starting with `#` are ignored.
972+
973+
* **File path**: A relative or absolute path to a file, optionally prefixed with `file://`. Relative paths are resolved against `GITHUB_WORKSPACE`. The path must point to an existing regular file (not a directory). The runner records the file's base name and its SHA-256 digest.
974+
* **OCI reference**: A reference in the form `REFERENCE@ALGORITHM:HEX`, optionally prefixed with `oci://`. `REFERENCE` is the image name (including optional tag), and `ALGORITHM` must be one of `sha256`, `sha384`, or `sha512`. `HEX` must be the full lowercase digest for the algorithm: 64 hexadecimal characters for `sha256`, 96 for `sha384`, or 128 for `sha512`.
975+
976+
Limits:
977+
978+
* The per-step command file is capped at 1MiB.
979+
* A job can accumulate up to 500 workflow artifacts across all steps.
980+
* If the same artifact is declared more than once with identical name and digest, it is deduplicated. Conflicting declarations (same name, different digest) produce an error.
981+
982+
{% bash %}
983+
984+
```bash copy
985+
echo "dist/my-binary" >> "$GITHUB_ARTIFACTS"
986+
```
987+
988+
To declare an OCI reference:
989+
990+
```bash copy
991+
echo "oci://ghcr.io/octocat/myapp:1.0.0@sha256:914b38d45a65e4263a179d9c2b09cc04dcbcaa8257fa85100cf42f9a3b408cfb" >> "$GITHUB_ARTIFACTS"
992+
```
993+
994+
{% endbash %}
995+
996+
{% powershell %}
997+
998+
```powershell copy
999+
"dist/my-binary" >> $env:GITHUB_ARTIFACTS
1000+
```
1001+
1002+
To declare an OCI reference:
1003+
1004+
```powershell copy
1005+
"oci://ghcr.io/octocat/myapp:1.0.0@sha256:914b38d45a65e4263a179d9c2b09cc04dcbcaa8257fa85100cf42f9a3b408cfb" >> $env:GITHUB_ARTIFACTS
1006+
```
1007+
1008+
{% endpowershell %}
1009+
1010+
## Reading workflow artifacts
1011+
1012+
Read the aggregated workflow artifact metadata declared by earlier steps in the current job from the `GITHUB_ARTIFACTS_LIST` environment file. This file is read-only and is updated by the runner after each step completes. It contains a UTF-8-encoded JSON object with the following structure:
1013+
1014+
```json
1015+
{
1016+
"version": 1,
1017+
"subjects": [
1018+
{
1019+
"name": "my-binary",
1020+
"digest": "sha256:abc123...",
1021+
"kind": "file"
1022+
},
1023+
{
1024+
"name": "ghcr.io/octocat/myapp:1.0.0",
1025+
"digest": "sha256:a1b2c3d4...",
1026+
"kind": "oci"
1027+
}
1028+
]
1029+
}
1030+
```
1031+
1032+
Each entry in the `subjects` array contains:
1033+
1034+
* `name`: The base name of the file or the OCI reference name (without the digest).
1035+
* `digest`: The `algorithm:hex` digest of the artifact.
1036+
* `kind`: Either `file` or `oci`.
1037+
1038+
Artifacts are sorted alphabetically by `name`.
1039+
1040+
{% bash %}
1041+
1042+
```bash copy
1043+
cat "$GITHUB_ARTIFACTS_LIST"
1044+
```
1045+
1046+
{% endbash %}
1047+
1048+
{% powershell %}
1049+
1050+
```powershell copy
1051+
Get-Content $env:GITHUB_ARTIFACTS_LIST
1052+
```
1053+
1054+
{% endpowershell %}
1055+
1056+
{% endif %}

‎data/features/actions-artifacts-file.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Reference: actions/runner#4527
2+
# Versioning for the GITHUB_ARTIFACTS and GITHUB_ARTIFACTS_LIST environment files.
3+
versions:
4+
fpt: '*'
5+
ghec: '*'
6+
ghes: '>=3.22'

0 commit comments

Comments
 (0)