워크플로우 아티팩트로 데이터 저장 및 공유하기

아티팩트를 사용해서 워크플로우의 job 간에 데이터를 공유하고, 워크플로우가 완료된 후에는 데이터를 저장할 수 있어요. 이 가이드에서는 빌드·테스트 결과를 아티팩트로 업로드하고 다시 다운로드하는 방법을 알려드릴게요.

출처: 문서

본문

Prerequisites

이 튜토리얼을 완료하려면 워크플로우 아티팩트를 이해하고 있어야 해요. Workflow artifacts 문서를 참고하세요.

Uploading build and test artifacts

코드를 빌드하고 테스트한 출력은 테스트 실패를 디버깅하는 데 사용할 수 있는 파일과 배포할 수 있는 프로덕션 코드가 될 때가 많아요. 워크플로우를 구성해서 저장소에 푸시된 코드를 빌드하고 테스트하고, 성공 또는 실패 상태를 보고하도록 할 수 있어요. 빌드 및 테스트 출력을 업로드해서 배포, 실패한 테스트나 크래시 디버깅, 테스트 스위트 커버리지 확인에 사용할 수 있어요.

아티팩트를 업로드하려면 upload-artifact 액션을 사용할 수 있어요. 아티팩트를 업로드할 때 단일 파일 또는 디렉터리, 또는 여러 파일이나 디렉터리를 지정할 수 있어요. 특정 파일이나 디렉터리를 제외하거나 와일드카드 패턴을 사용할 수도 있어요. 아티팩트 이름을 제공하는 것이 좋지만, 이름을 제공하지 않으면 artifact가 기본 이름으로 사용돼요. 문법에 대한 자세한 내용은 actions/upload-artifact 액션을 참고하세요.

Example

예를 들어 저장소나 웹 애플리케이션에 CSS와 JavaScript로 변환해야 하는 SASS와 TypeScript 파일이 있을 수 있어요. 빌드 구성이 컴파일된 파일을 dist 디렉터리에 출력한다고 가정하면, 모든 테스트가 성공적으로 완료되면 dist 디렉터리의 파일을 웹 애플리케이션 서버에 배포할 거예요.

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

이 예시는 src 디렉터리의 코드를 빌드하고 tests 디렉터리의 테스트를 실행하는 Node.js 프로젝트용 워크플로우를 만드는 방법을 보여줍니다. npm test를 실행하면 output/test/ 디렉터리에 code-coverage.html이라는 코드 커버리지 보고서가 생성된다고 가정할 수 있어요.

이 워크플로우는 dist 디렉터리의 프로덕션 아티팩트를 업로드하되 markdown 파일은 제외해요. 또한 code-coverage.html 보고서를 다른 아티팩트로 업로드해요.

name: Node CI

on: [push]

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

[!TIP] 아티팩트를 다운로드하는 대신 풀 리퀘스트에 코드 커버리지 결과를 직접 표시하려면 Cobertura XML 커버리지 보고서를 Code Quality에 업로드할 수 있어요. Setting up code coverage for your repository 문서를 참고하세요.

Configuring a custom artifact retention period

워크플로우가 만든 개별 아티팩트에 대한 사용자 지정 보존 기간을 정의할 수 있어요. 워크플로우로 새 아티팩트를 만들 때 upload-artifact 액션과 함께 retention-days를 사용할 수 있어요. 이 예시는 my-artifact라는 아티팩트에 대해 5일의 사용자 지정 보존 기간을 설정하는 방법을 보여줍니다.

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

retention-days 값은 저장소, 조직 또는 엔터프라이즈가 설정한 보존 한도를 초과할 수 없어요.

Downloading artifacts during a workflow run

워크플로우 실행 중에 이전에 업로드된 아티팩트를 다운로드하려면 actions/download-artifact 액션을 사용할 수 있어요.

[!NOTE] 다른 워크플로우나 워크플로우 실행에서 아티팩트를 다운로드하려면 토큰과 실행 식별자를 제공해야 해요. download-artifact 액션 문서의 Download Artifacts from other Workflow Runs or Repositories 섹션을 참고하세요.

개별 아티팩트를 다운로드하려면 아티팩트의 이름을 지정하세요. 이름을 지정하지 않고 아티팩트를 업로드했다면 기본 이름은 artifact예요.

- name: Download a single artifact
  uses: actions/download-artifact@v5
  with:
    name: my-artifact

이름을 지정하지 않으면 워크플로우 실행의 모든 아티팩트를 다운로드할 수도 있어요. 아티팩트가 많을 때 유용할 수 있어요.

- name: Download all workflow run artifacts
  uses: actions/download-artifact@v5

워크플로우 실행의 모든 아티팩트를 다운로드하면 각 아티팩트에 대해 해당 이름을 사용한 디렉터리가 생성돼요.

문법에 대한 자세한 내용은 actions/download-artifact 액션을 참고하세요.

Passing data between jobs in a workflow

upload-artifact와 download-artifact 액션을 사용해서 워크플로우의 job 간에 데이터를 공유할 수 있어요. 이 예시 워크플로우는 같은 워크플로우의 job 간에 데이터를 전달하는 방법을 보여줍니다. 자세한 내용은 actions/upload-artifact 및 download-artifact 액션을 참고하세요.

이전 job의 아티팩트에 의존하는 job은 해당 job이 성공적으로 완료될 때까지 기다려야 해요. 이 워크플로우는 needs 키워드를 사용해서 job_1, job_2, job_3이 순차적으로 실행되도록 보장해요. 예를 들어 job_2는 needs: job_1 문법으로 job_1을 필요로 해요.

Job 1은 다음 단계를 수행해요.

수학 계산을 수행하고 결과를 math-homework.txt라는 텍스트 파일에 저장해요.
upload-artifact 액션을 사용해서 math-homework.txt 파일을 homework_pre 아티팩트 이름으로 업로드해요.

Job 2는 이전 job의 결과를 사용해요.

이전 job에서 업로드한 homework_pre 아티팩트를 다운로드해요. 기본적으로 download-artifact 액션은 단계가 실행 중인 워크스페이스 디렉터리에 아티팩트를 다운로드해요. path 입력 매개변수를 사용해서 다른 다운로드 디렉터리를 지정할 수 있어요.
math-homework.txt 파일의 값을 읽고 수학 계산을 수행한 다음, 내용을 덮어쓰며 결과를 다시 math-homework.txt에 저장해요.
math-homework.txt 파일을 업로드해요. v4에서 아티팩트는 불변(immutable)으로 간주되므로 아티팩트에 homework_final이라는 다른 입력이 이름으로 전달돼요.

Job 3은 이전 job에서 업로드한 결과를 표시해요.

Job 2에서 homework_final 아티팩트를 다운로드해요.
수학 방정식의 결과를 로그에 출력해요.

이 워크플로우 예시에서 수행되는 전체 수학 연산은 (3 + 7) x 9 = 90이에요.

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

워크플로우 실행은 생성한 모든 아티팩트를 보관해요. 보관된 아티팩트를 다운로드하는 방법에 대한 자세한 내용은 Downloading workflow artifacts 문서를 참고하세요.

Validating artifacts

upload-artifact 액션을 사용할 때마다 digest라는 출력이 반환돼요. 이는 워크플로우 실행 중 업로드한 아티팩트의 SHA256 요약(digest)이에요.

그 후 download-artifact 액션으로 해당 아티팩트를 다운로드하면 다운로드한 아티팩트의 요약을 자동으로 계산하고 upload-artifact 단계의 출력과 일치하는지 검증해요.

요약이 일치하지 않으면 실행은 UI와 job 로그에 경고를 표시해요.

SHA256 요약을 보려면 upload-artifact job의 로그를 열거나 워크플로우 실행 UI에 나타나는 Artifact 출력에서 확인하세요.

워크플로우 아티팩트로 데이터 저장 및 공유하기