Skip to content

Commit 2418439

Browse files
EDI-ify "Storing and sharing data from a workflow" (#56606)
Co-authored-by: Joe Clark <[email protected]>
1 parent 8c973a6 commit 2418439

File tree

5 files changed

+62
-83
lines changed

5 files changed

+62
-83
lines changed

content/actions/concepts/workflows-and-actions/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ children:
1414
- /contexts
1515
- /expressions
1616
- /deployment-environments
17+
- /workflow-artifacts
1718
- /dependency-caching
1819
- /about-monitoring-workflows
1920
- /notifications-for-workflow-runs
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Workflow artifacts
3+
intro: 'Learn about storing and sharing data as artifacts of {% data variables.product.prodname_actions %} workflows.'
4+
versions:
5+
fpt: '*'
6+
ghes: '*'
7+
ghec: '*'
8+
type: overview
9+
topics:
10+
- Actions
11+
- Workflows
12+
---
13+
14+
## About workflow artifacts
15+
16+
An artifact is a file or collection of files produced during a workflow run. Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. For example, you can use artifacts to save your build and test output after a workflow run has ended.
17+
18+
{% data variables.product.github %} provides two actions that you can use to upload and download build artifacts, {% ifversion fpt or ghec %}[upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact){% else %} `upload-artifact` and `download-artifact` on {% data variables.product.prodname_ghe_server %}{% endif %}.
19+
20+
Common artifacts include:
21+
22+
* Log files and core dumps
23+
* Test results, failures, and screenshots
24+
* Binary or compressed files
25+
* Stress test performance output and code coverage results
26+
27+
{% data reusables.actions.comparing-artifacts-caching %}
28+
29+
For more information on dependency caching, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows#comparing-artifacts-and-dependency-caching).
30+
31+
{% ifversion artifact-attestations %}
32+
33+
## Generating artifact attestations for builds
34+
35+
{% data reusables.actions.about-artifact-attestations %}
36+
37+
You can access attestations after a build run, underneath the list of the artifacts the build produced.
38+
39+
For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
40+
41+
{% endif %}
42+
43+
{% data reusables.actions.artifacts.artifacts-from-deleted-workflow-runs %}

content/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/index.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,5 +21,4 @@ children:
2121
- /deploying-to-a-specific-environment
2222
- /control-the-concurrency-of-workflows-and-jobs
2323
- /running-variations-of-jobs-in-a-workflow
24-
- /storing-and-sharing-data-from-a-workflow
2524
---

content/actions/tutorials/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ children:
1212
- /creating-a-docker-container-action
1313
- /creating-a-javascript-action
1414
- /creating-a-composite-action
15+
- /store-and-share-data
1516
- /quickstart-for-actions-runner-controller
1617
- /deploying-with-github-actions
1718
- /communicating-with-docker-service-containers
1819
redirect_from:
1920
- /actions/guides
2021
---
21-
Lines changed: 17 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: Storing and sharing data from a workflow
3-
shortTitle: Store artifacts
4-
intro: Artifacts allow you to share data between jobs in a workflow and store data once that workflow has completed.
2+
title: Store and share data with workflow artifacts
3+
shortTitle: Store and share data
4+
intro: Use artifacts to share data between jobs in a workflow and store data once that workflow has completed.
55
redirect_from:
66
- /articles/persisting-workflow-data-using-artifacts
77
- /github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts
@@ -12,59 +12,23 @@ redirect_from:
1212
- /actions/using-workflows/storing-workflow-data-as-artifacts
1313
- /actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts
1414
- /actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow
15+
- /actions/how-tos/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow
1516
versions:
1617
fpt: '*'
1718
ghes: '*'
1819
ghec: '*'
1920
type: tutorial
2021
topics:
2122
- Workflows
23+
allowTitleToDifferFromFilename: true
2224
---
2325

24-
{% data reusables.actions.enterprise-github-hosted-runners %}
26+
## Prerequisites
2527

26-
## About workflow artifacts
27-
28-
Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended. {% data reusables.actions.reusable-workflow-artifacts %}
29-
30-
{% data reusables.actions.artifact-log-retention-statement %} The retention period for a pull request restarts each time someone pushes a new commit to the pull request.
31-
32-
These are some of the common artifacts that you can upload:
33-
34-
* Log files and core dumps
35-
* Test results, failures, and screenshots
36-
* Binary or compressed files
37-
* Stress test performance output and code coverage results
38-
39-
{% ifversion fpt or ghec %}
40-
41-
Storing artifacts uses storage space on {% data variables.product.github %}. {% data reusables.actions.actions-billing %} For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions).
42-
43-
{% else %}
44-
45-
Artifacts consume storage space on the external blob storage that is configured for {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}.
46-
47-
{% endif %}
48-
49-
Artifacts are uploaded during a workflow run, and you can view an artifact's name and size in the UI. When an artifact is downloaded using the {% data variables.product.github %} UI, all files that were individually uploaded as part of the artifact get zipped together into a single file. This means that billing is calculated based on the size of the uploaded artifact and not the size of the zip file.
50-
51-
{% data variables.product.github %} provides two actions that you can use to upload and download build artifacts. For more information, see the {% ifversion fpt or ghec %}[upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `upload-artifact` and `download-artifact` actions on {% data variables.product.prodname_ghe_server %}{% endif %}.
52-
53-
To share data between jobs:
54-
55-
* **Uploading files:** Give the uploaded file a name and upload the data before the job ends.
56-
* **Downloading files:** You can only download artifacts that were uploaded during the same workflow run. When you download a file, you can reference it by name.
57-
58-
The steps of a job share the same environment on the runner machine, but run in their own individual processes. To pass data between steps in a job, you can use inputs and outputs. For more information about inputs and outputs, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions).
59-
60-
{% data reusables.actions.comparing-artifacts-caching %}
61-
62-
For more information on dependency caching, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows#comparing-artifacts-and-dependency-caching).
28+
Before you can complete this tutorial, you need to understand workflow artifacts. See [AUTOTITLE](/actions/concepts/workflows-and-actions/workflow-artifacts).
6329

6430
## Uploading build and test artifacts
6531

66-
You can create a continuous integration (CI) workflow to build and test your code. For more information about using {% data variables.product.prodname_actions %} to perform CI, see [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration).
67-
6832
The output of building and testing your code often produces files you can use to debug test failures and production code that you can deploy. You can configure a workflow to build and test the code pushed to your repository and report a success or failure status. You can upload the build and test output to use for deployments, debugging failed tests or crashes, and viewing test suite coverage.
6933

7034
You can use the `upload-artifact` action to upload artifacts. When uploading an artifact, you can specify a single file or directory, or multiple files or directories. You can also exclude certain files or directories, and use wildcard patterns. We recommend that you provide a name for an artifact, but if no name is provided then `artifact` will be used as the default name. For more information on syntax, see the {% ifversion fpt or ghec %}[actions/upload-artifact](https://github.com/actions/upload-artifact) action{% else %} `actions/upload-artifact` action on {% data variables.product.prodname_ghe_server %}{% endif %}.
@@ -119,18 +83,6 @@ jobs:
11983
path: output/test/code-coverage.html
12084
```
12185
122-
{% ifversion artifact-attestations %}
123-
124-
## Generating artifact attestations for builds
125-
126-
{% data reusables.actions.about-artifact-attestations %}
127-
128-
You can access attestations after a build run, underneath the list of the artifacts the build produced.
129-
130-
For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
131-
132-
{% endif %}
133-
13486
## Configuring a custom artifact retention period
13587
13688
You can define a custom retention period for individual artifacts created by a workflow. When using a workflow to create a new artifact, you can use `retention-days` with the `upload-artifact` action. This example demonstrates how to set a custom retention period of 5 days for the artifact named `my-artifact`:
@@ -146,15 +98,9 @@ You can define a custom retention period for individual artifacts created by a w
14698

14799
The `retention-days` value cannot exceed the retention limit set by the repository, organization, or enterprise.
148100

149-
## Downloading or deleting artifacts
150-
151-
During a workflow run, you can use the [`download-artifact`](https://github.com/actions/download-artifact) action to download artifacts that were previously uploaded in the same workflow run.
152-
153-
After a workflow run has been completed, you can download or delete artifacts on {% data variables.product.prodname_dotcom %} or using the REST API. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts), [AUTOTITLE](/actions/managing-workflow-runs/removing-workflow-artifacts), and [AUTOTITLE](/rest/actions/artifacts).
154-
155-
### Downloading artifacts during a workflow run
101+
## Downloading artifacts during a workflow run
156102

157-
The [`actions/download-artifact`](https://github.com/actions/download-artifact) action can be used to download previously uploaded artifacts during a workflow run.
103+
You can use the [`actions/download-artifact`](https://github.com/actions/download-artifact) action to download previously uploaded artifacts during a workflow run.
158104

159105
> [!NOTE]
160106
> {% ifversion fpt or ghec %}If you want to download artifacts from a different workflow or workflow run, you need to supply a token and run identifier. See [Download Artifacts from other Workflow Runs or Repositories](https://github.com/actions/download-artifact?tab=readme-ov-file#download-artifacts-from-other-workflow-runs-or-repositories) in the documentation for the `download-artifact` action.
@@ -180,20 +126,6 @@ If you download all workflow run's artifacts, a directory for each artifact is c
180126

181127
For more information on syntax, see the {% ifversion fpt or ghec %}[actions/download-artifact](https://github.com/actions/download-artifact) action{% else %} `actions/download-artifact` action on {% data variables.product.prodname_ghe_server %}{% endif %}.
182128

183-
{% ifversion fpt or ghec %}
184-
185-
## Validating artifacts
186-
187-
Every time the upload-artifact action is used it returns an output called `digest`. This is a SHA256 digest of the Artifact you uploaded during a workflow run.
188-
189-
When the download-artifact action is then used to download that artifact, it automatically calculates the digest for that downloaded artifact and validates that it matches the output from the upload-artifact step.
190-
191-
If the digest does not match, the run will display a warning in the UI and in the job logs.
192-
193-
To view the SHA256 digest you can open the logs for the upload-artifact job or check in the Artifact output that appears in the workflow run UI.
194-
195-
{% endif %}
196-
197129
## Passing data between jobs in a workflow
198130

199131
You can use the `upload-artifact` and `download-artifact` actions to share data between jobs in a workflow. This example workflow illustrates how to pass data between jobs in the same workflow. For more information, see the {% ifversion fpt or ghec %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {% data variables.product.prodname_ghe_server %}{% endif %}.
@@ -271,12 +203,16 @@ jobs:
271203
272204
The workflow run will archive any artifacts that it generated. For more information on downloading archived artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts).
273205
274-
{% data reusables.actions.artifacts.artifacts-from-deleted-workflow-runs %}
275-
276206
{% ifversion fpt or ghec %}
277207
278-
## Further reading
208+
## Validating artifacts
209+
210+
Every time the upload-artifact action is used it returns an output called `digest`. This is a SHA256 digest of the Artifact you uploaded during a workflow run.
211+
212+
When the download-artifact action is then used to download that artifact, it automatically calculates the digest for that downloaded artifact and validates that it matches the output from the upload-artifact step.
213+
214+
If the digest does not match, the run will display a warning in the UI and in the job logs.
279215

280-
* [AUTOTITLE](/billing/managing-billing-for-github-actions).
216+
To view the SHA256 digest, open the logs for the upload-artifact job or check in the Artifact output that appears in the workflow run UI.
281217

282218
{% endif %}

0 commit comments

Comments
 (0)