Storing and sharing data from a workflow

Artifacts allow you to share data between jobs in a workflow and store data once that workflow has completed.

이 문서의 내용

About workflow artifacts

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. 실행 중 호출되는 모든 작업 및 워크플로는 실행 중인 아티팩트에 대한 쓰기 액세스 권한을 갖습니다.

기본적으로 GitHub는 90일 동안 빌드 로그 및 아티팩트를 저장하며 보존 기간은 사용자 지정할 수 있습니다. 자세한 내용은 "사용 제한, 청구, 관리"을(를) 참조하세요. The retention period for a pull request restarts each time someone pushes a new commit to the pull request.

These are some of the common artifacts that you can upload:

  • Log files and core dumps
  • Test results, failures, and screenshots
  • Binary or compressed files
  • Stress test performance output and code coverage results

Storing artifacts uses storage space on GitHub. GitHub Actions 사용량은 퍼블릭 리포지토리의 표준 GitHub호스팅된 실행기 및 자체 호스팅 실행기에서 무료입니다. 프라이빗 리포지토리에서 각 GitHub 계정은 계정 계획에 따라 특정한 양의 남은 시간(분)과 GitHub호스팅 실행기에 사용할 수 있는 스토리지를 받습니다. 포함된 금액을 초과하는 모든 사용량은 지출 한도에 따라 제어됩니다. For more information, see "GitHub Actions 요금 청구 관리."

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 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.

GitHub provides two actions that you can use to upload and download build artifacts. For more information, see the upload-artifact and download-artifact actions.

To share data between jobs:

  • Uploading files: Give the uploaded file a name and upload the data before the job ends.
  • 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.

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 "GitHub Actions에 대한 메타데이터 구문."

아티팩트 및 종속성 캐싱 비교

아티팩트 및 캐싱은 GitHub에 파일을 저장할 수 있는 기능을 제공하지만 각 기능은 서로 다른 사용 사례를 제공하므로 서로 바꿔서 사용할 수 없습니다.

  • 패키지 관리 시스템의 빌드 종속성 등 작업 또는 워크플로 실행 간에 자주 변경되지 않는 파일을 다시 사용하려는 경우 캐싱을 사용합니다.
  • 빌드된 이진 파일 또는 빌드 로그와 같이 워크플로 실행이 종료된 후 볼 작업에서 생성된 파일을 저장하려는 경우 아티팩트를 사용합니다.

For more information on dependency caching, see "워크플로 속도를 높이기 위한 종속성 캐싱."

Uploading build and test artifacts

You can create a continuous integration (CI) workflow to build and test your code. For more information about using GitHub Actions to perform CI, see "About continuous integration with GitHub Actions."

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 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 actions/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 the dist directory, you would deploy the files in the dist 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 the src directory and runs the tests in the tests directory. You can assume that running npm test produces a code coverage report named code-coverage.html stored in the output/test/ directory.

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

YAML
name: Node CI

on: [push]

jobs:
  build_and_test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - 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

Generating artifact attestations for builds

아티팩트 증명을 사용하면 빌드한 소프트웨어에 대해 수정할 수 없는 출처 및 무결성 보장을 생성할 수 있습니다. 따라서 소프트웨어를 사용하는 사용자는 소프트웨어가 빌드된 위치와 방법을 확인할 수 있습니다.

소프트웨어를 사용하여 아티팩트 증명을 생성하는 경우 빌드의 출처를 설정하고 다음 정보가 포함된 암호화 서명된 클레임을 만듭니다.

  • 아티팩트와 연결된 워크플로의 링크입니다.
  • 아티팩트의 리포지토리, 조직, 환경, 커밋 SHA 및 트리거 이벤트입니다.
  • 출처를 설정하는 데 사용되는 OIDC 토큰의 기타 정보입니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.

관련 SBOM(소프트웨어 자료 청구서)을 포함하는 아티팩트 증명을 생성할 수도 있습니다. 빌드에 사용되는 오픈 소스 종속성 목록과 빌드를 연결하면 투명성을 보장하고 소비자가 데이터 보호 표준을 준수하도록 할 수 있습니다.

You can access attestations after a build run, underneath the list of the artifacts the build produced.

For more information, see "아티팩트 증명을 사용하여 빌드의 출처 설정."

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 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:

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

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

Downloading or deleting artifacts

During a workflow run, you can use the download-artifact action to download artifacts that were previously uploaded in the same workflow run.

After a workflow run has been completed, you can download or delete artifacts on GitHub or using the REST API. For more information, see "워크플로 아티팩트 다운로드," "워크플로 아티팩트 제거," and "GitHub Actions 아티팩트에 대한 REST API 엔드포인트."

Downloading artifacts during a workflow run

The actions/download-artifact action can be used to download previously uploaded artifacts during a workflow run.

Note: You can only download artifacts in a workflow that were uploaded during the same workflow run.

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

- name: Download a single artifact
  uses: actions/download-artifact@v4
  with:
    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: Download all workflow run artifacts
  uses: actions/download-artifact@v4

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

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

Passing data between jobs in a workflow

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 actions/upload-artifact and download-artifact actions.

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

Job 1 performs these steps:

  • Performs a math calculation and saves the result to a text file called math-homework.txt.
  • Uses the upload-artifact action to upload the math-homework.txt file with the artifact name homework_pre.

Job 2 uses the result in the previous job:

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

Job 3 displays the result uploaded in the previous job:

  • Downloads the homework_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.

YAML
name: Share data between jobs

on: [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@v4
        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@v4
        with:
          name: homework_final
      - name: Print the final result
        shell: bash
        run: |
          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, see "워크플로 아티팩트 다운로드."

Further reading