Prerequisites

Before you can complete this tutorial, you need to understand workflow artifacts. SeeWorkflow artifacts.

Uploading build and test artifacts

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.

You can use theupload-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 thenartifact will be used as the default name. For more information on syntax, see theactions/upload-artifact action.

Example

For example, your repository or a web application might contain SASS and TypeScript files that you must convert to CSS and JavaScript. Assuming your build configuration outputs the compiled files in thedist directory, you would deploy the files in thedist directory to your web application server if all tests completed successfully.

|-- hello-world (repository)|   └── dist|   └── tests|   └── src|       └── sass/app.scss|       └── app.ts|   └── output|       └── test|

This example shows you how to create a workflow for a Node.js project that builds the code in thesrc directory and runs the tests in thetests directory. You can assume that runningnpm test produces a code coverage report namedcode-coverage.html stored in theoutput/test/ directory.

The workflow uploads the production artifacts in thedist directory, but excludes any markdown files. It also uploads thecode-coverage.html report as another artifact.

name: Node CIon: [push]jobs:  build_and_test:    runs-on: ubuntu-latest    steps:      - name: Checkout repository        uses: actions/checkout@v5      - name: npm install, build, and test        run: |          npm install          npm run build --if-present          npm test      - name: Archive production artifacts        uses: actions/upload-artifact@v4        with:          name: dist-without-markdown          path: |            dist            !dist/**/*.md      - name: Archive code coverage results        uses: actions/upload-artifact@v4        with:          name: code-coverage-report          path: output/test/code-coverage.html

name:NodeCIon: [push]jobs:build_and_test:runs-on:ubuntu-lateststeps:-name:Checkoutrepositoryuses:actions/checkout@v5-name:npminstall,build,andtestrun:|          npm install          npm run build --if-present          npm test-name:Archiveproductionartifactsuses:actions/upload-artifact@v4with:name:dist-without-markdownpath:|            dist            !dist/**/*.md-name:Archivecodecoverageresultsuses:actions/upload-artifact@v4with:name:code-coverage-reportpath:output/test/code-coverage.html

Configuring a custom artifact retention period

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 useretention-days with theupload-artifact action. This example demonstrates how to set a custom retention period of 5 days for the artifact namedmy-artifact:

  - name: 'Upload Artifact'    uses: actions/upload-artifact@v4    with:      name: my-artifact      path: my_file.txt      retention-days: 5

-name:'Upload Artifact'uses:actions/upload-artifact@v4with:name:my-artifactpath:my_file.txtretention-days:5

Theretention-days value cannot exceed the retention limit set by the repository, organization, or enterprise.

Downloading artifacts during a workflow run

You can use theactions/download-artifact action to download previously uploaded artifacts during a workflow run.

Specify an artifact's name to download an individual artifact. If you uploaded an artifact without specifying a name, the default name isartifact.

-name:Downloadasingleartifactuses:actions/download-artifact@v5with:name:my-artifact

You can also download all artifacts in a workflow run by not specifying a name. This can be useful if you are working with lots of artifacts.

-name:Downloadallworkflowrunartifactsuses:actions/download-artifact@v5

If you download all workflow run's artifacts, a directory for each artifact is created using its name.

For more information on syntax, see theactions/download-artifact action.

Passing data between jobs in a workflow

You can use theupload-artifact anddownload-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 theactions/upload-artifact anddownload-artifact actions.

Jobs that are dependent on a previous job's artifacts must wait for the dependent job to complete successfully. This workflow uses theneeds keyword to ensure thatjob_1,job_2, andjob_3 run sequentially. For example,job_2 requiresjob_1 using theneeds: job_1 syntax.

Job 1 performs these steps:

• Performs a math calculation and saves the result to a text file calledmath-homework.txt.
• Uses theupload-artifact action to upload themath-homework.txt file with the artifact namehomework_pre.

Job 2 uses the result in the previous job:

• Downloads thehomework_pre artifact uploaded in the previous job. By default, thedownload-artifact action downloads artifacts to the workspace directory that the step is executing in. You can use thepath input parameter to specify a different download directory.
• Reads the value in themath-homework.txt file, performs a math calculation, and saves the result tomath-homework.txt again, overwriting its contents.
• Uploads themath-homework.txt file. As artifacts are considered immutable inv4, the artifact is passed a different input,homework_final, as a name.

Job 3 displays the result uploaded in the previous job:

• Downloads thehomework_final artifact from Job 2.
• Prints the result of the math equation to the log.

The full math operation performed in this workflow example is(3 + 7) x 9 = 90.

name: Share data between jobson: [push]jobs:  job_1:    name: Add 3 and 7    runs-on: ubuntu-latest    steps:      - shell: bash        run: |          expr 3 + 7 > math-homework.txt      - name: Upload math result for job 1        uses: actions/upload-artifact@v4        with:          name: homework_pre          path: math-homework.txt  job_2:    name: Multiply by 9    needs: job_1    runs-on: windows-latest    steps:      - name: Download math result for job 1        uses: actions/download-artifact@v5        with:          name: homework_pre      - shell: bash        run: |          value=`cat math-homework.txt`          expr $value \* 9 > math-homework.txt      - name: Upload math result for job 2        uses: actions/upload-artifact@v4        with:          name: homework_final          path: math-homework.txt  job_3:    name: Display results    needs: job_2    runs-on: macOS-latest    steps:      - name: Download math result for job 2        uses: actions/download-artifact@v5        with:          name: homework_final      - name: Print the final result        shell: bash        run: |          value=`cat math-homework.txt`          echo The result is $value

name:Sharedatabetweenjobson: [push]jobs:job_1:name:Add3and7runs-on:ubuntu-lateststeps:-shell:bashrun:|          expr 3 + 7 > math-homework.txt-name:Uploadmathresultforjob1uses:actions/upload-artifact@v4with:name:homework_prepath:math-homework.txtjob_2:name:Multiplyby9needs:job_1runs-on:windows-lateststeps:-name:Downloadmathresultforjob1uses:actions/download-artifact@v5with:name:homework_pre-shell:bashrun:|          value=`cat math-homework.txt`          expr $value \* 9 > math-homework.txt-name:Uploadmathresultforjob2uses:actions/upload-artifact@v4with:name:homework_finalpath:math-homework.txtjob_3:name:Displayresultsneeds:job_2runs-on:macOS-lateststeps:-name:Downloadmathresultforjob2uses:actions/download-artifact@v5with:name:homework_final-name:Printthefinalresultshell:bashrun:|          value=`cat math-homework.txt`          echo The result is $value

The workflow run will archive any artifacts that it generated. For more information on downloading archived artifacts, seeDownloading workflow artifacts.

Validating artifacts

Every time the upload-artifact action is used it returns an output calleddigest. This is a SHA256 digest of the Artifact you uploaded during a workflow run.

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.

If the digest does not match, the run will display a warning in the UI and in the job logs.

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.