워크플로에서 데이터 저장 및 공유

Artifacts를 사용하면 워크플로의 작업 간에 데이터를 공유하고 워크플로가 완료되면 데이터를 저장할 수 있습니다.

이 문서의 내용

워크플로 아티팩트 정보

아티팩트를 통해 작업을 완료한 후 데이터를 보관하고 동일한 워크플로의 다른 작업과 공유할 수 있습니다. 아티팩트가 워크플로 실행 중에 생성된 파일 또는 파일 컬렉션입니다. 예를 들어 아티팩트를 사용하여 워크플로 실행이 종료된 후 빌드 및 테스트 출력을 저장할 수 있습니다. 실행 중 호출되는 모든 작업 및 워크플로는 실행 중인 아티팩트에 대한 쓰기 액세스 권한을 갖습니다.

기본적으로 GitHub는 90일 동안 빌드 로그 및 아티팩트를 저장하며 보존 기간은 사용자 지정할 수 있습니다. 자세한 내용은 "사용 제한, 청구, 관리"을(를) 참조하세요. 끌어오기 요청에 대한 보존 기간은 누군가가 끌어오기 요청에 새 커밋을 푸시할 때마다 다시 시작됩니다.

다음은 업로드할 수 있는 몇 가지 일반적인 아티팩트입니다.

  • 로그 파일 및 코어 덤프
  • 테스트 결과, 실패, 스크린샷
  • 이진 파일 또는 압축 파일
  • 스트레스 테스트 성능 출력 및 코드 검사 결과

아티팩트 저장은 GitHub에 스토리지 공간을 사용합니다. GitHub Actions 사용량은 퍼블릭 리포지토리의 표준 GitHub호스팅된 실행기 및 자체 호스팅 실행기에서 무료입니다. 프라이빗 리포지토리에서 각 GitHub 계정은 계정 계획에 따라 특정한 양의 남은 시간(분)과 GitHub호스팅 실행기에 사용할 수 있는 스토리지를 받습니다. 포함된 금액을 초과하는 모든 사용량은 지출 한도에 따라 제어됩니다. 자세한 내용은 "GitHub Actions 요금 청구 관리"을 참조하세요.

아티팩트는 워크플로 실행 중에 업로드되며 UI에서 아티팩트의 이름과 크기를 볼 수 있습니다. GitHub UI를 사용하여 아티팩트를 다운로드하면 아티팩트의 일부로 개별적으로 업로드된 모든 파일이 단일 파일로 압축됩니다. 즉, Zip 파일의 크기가 아닌 업로드된 아티팩트 크기에 따라 청구 금액이 계산됩니다.

GitHub는 빌드 아티팩트 업로드 및 다운로드에 사용할 수 있는 두 가지 작업을 제공합니다. 자세한 내용은 upload-artifact와 download-artifact 작업.

작업 간에 데이터를 공유하려면 다음을 수행합니다.

  • 파일 업로드: 업로드된 파일에 이름을 지정하고 작업이 끝나기 전에 데이터를 업로드합니다.
  • 파일 다운로드: 동일한 워크플로 실행 중에 업로드된 아티팩트만 다운로드할 수 있습니다. 파일을 다운로드할 때 이름으로 참조할 수 있습니다.

작업 단계는 실행기 컴퓨터에서 동일한 환경을 공유하지만 고유한 개별 프로세스에서 실행됩니다. 작업의 단계 간에 데이터를 전달하려면 입력 및 출력을 사용할 수 있습니다. 입력 및 출력에 대한 자세한 내용은 "GitHub Actions에 대한 메타데이터 구문" 항목을 참조하세요.

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

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

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

종속성 코칭에 대한 자세한 내용은 “워크플로 속도를 높이기 위한 종속성 캐싱” 항목을 참조하세요.

빌드 및 테스트 아티팩트 업로드

CI(연속 통합) 워크플로를 만들어 코드를 빌드하고 테스트할 수 있습니다. GitHub Actions를 사용하여 CI를 수행하는 방법에 대한 자세한 내용은 "GitHub Actions를 사용한 연속 통합 정보" 항목을 참조하세요.

코드를 빌드하고 테스트하는 출력은 종종 배포할 수 있는 테스트 실패 및 프로덕션 코드를 디버그하는 데 사용할 수 있는 파일을 생성합니다. 리포지토리에 푸시된 코드를 빌드 및 테스트하고 성공 또는 실패 상태를 보고하도록 워크플로를 구성할 수 있습니다. 배포에 사용할 빌드 및 테스트 출력을 업로드하고, 실패한 테스트 또는 크래시를 디버그하고, 테스트 도구 모음 검사를 볼 수 있습니다.

이 upload-artifact 작업을 사용하여 아티팩트를 업로드할 수 있습니다. 아티팩트를 업로드할 때 단일 파일이나 디렉터리 또는 여러 파일이나 디렉터리를 지정할 수 있습니다. 특정 파일 또는 디렉터리를 제외하고 와일드카드 패턴을 사용할 수도 있습니다. 아티팩트 이름을 제공하는 것이 좋지만 이름이 제공되지 않으면 artifact가 기본 이름으로 사용됩니다. 구문에 대한 자세한 내용은 actions/upload-artifact 작업.

예시

예를 들어 리포지토리 또는 웹 애플리케이션에는 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 보고서를 다른 아티팩트로 업로드합니다.

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

빌드의 아티팩트 증명 생성

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

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

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

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

빌드가 실행되고 나면 빌드에서 생성된 아티팩트 목록 아래에서 증명에 액세스할 수 있습니다.

자세한 내용은 "아티팩트 증명을 사용하여 빌드의 출처 설정"을(를) 참조하세요.

사용자 지정 아티팩트 보존 기간 구성

워크플로에서 만든 개별 아티팩트에 대한 사용자 지정 보존 기간을 정의할 수 있습니다. 워크플로를 사용하여 새 아티팩트를 만들 때 upload-artifact 작업에 retention-days를 사용할 수 있습니다. 이 예시에서는 my-artifact라는 이름의 아티팩트에 대한 사용자 지정 보존 기간을 5일로 설정하는 방법을 보여 줍니다.

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

retention-days 값은 리포지토리, 조직 또는 엔터프라이즈에서 설정한 보존 한도를 초과할 수 없습니다.

아티팩트 다운로드 또는 삭제

워크플로를 실행하는 동안 download-artifact 작업을 사용하여 이전에 동일한 워크플로 실행에서 업로드된 아티팩트를 다운로드할 수 있습니다.

워크플로 실행이 완료되면 GitHub에서 또는 REST API를 사용하여 아티팩트를 다운로드 또는 삭제할 수 있습니다. 자세한 내용은 "워크플로 아티팩트 다운로드," "워크플로 아티팩트 제거" 및 "GitHub Actions 아티팩트에 대한 REST API 엔드포인트"을(를) 참조하세요.

워크플로 실행 중 아티팩트 다운로드

actions/download-artifact 작업은 워크플로 실행 중 이전에 업로드한 아티팩트 다운로드에 사용할 수 있습니다.

참고: 동일한 워크플로 실행 중에 업로드된 워크플로 내 아티팩트만 다운로드할 수 있습니다.

아티팩트의 이름을 지정하여 개별 아티팩트를 다운로드합니다. 이름을 지정하지 않고 아티팩트를 업로드한 경우 기본 이름은 artifact입니다.

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

이름을 지정하지 않고 워크플로 실행의 모든 아티팩트를 다운로드할 수도 있습니다. 이 기능은 많은 아티팩트로 작업하는 경우에 유용할 수 있습니다.

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

모든 워크플로 실행의 아티팩트가 다운로드되면 각 아티팩트의 디렉터리가 해당 이름을 사용하여 만들어집니다.

구문에 대한 자세한 내용은 actions/download-artifact 작업.

워크플로의 작업 간 데이터 전달

upload-artifact 및 download-artifact 작업을 사용하여 워크플로의 작업 간에 데이터를 공유할 수 있습니다. 이 예시 워크플로에서는 동일한 워크플로의 작업 간에 데이터를 전달하는 방법을 보여 줍니다. 자세한 내용은 actions/upload-artifact and download-artifact와 download-artifact 작업.

이전 작업의 아티팩트에 종속된 작업은 종속 작업이 성공적으로 완료될 때까지 기다려야 합니다. 이 워크플로는 needs 키워드를 사용하여 job_1, job_2, job_3가 순차적으로 실행되도록 합니다. 예를 들어 job_2에는 needs: job_1 구문을 사용하는 job_1이 필요합니다.

작업 1은 다음 단계를 수행합니다.

  • 수학 계산을 수행하고 결과를 math-homework.txt라는 텍스트 파일에 저장합니다.
  • upload-artifact 작업을 사용하여 math-homework.txt 파일을 아티팩트 이름 homework_pre으로 업로드합니다.

작업 2는 이전 작업의 결과를 사용합니다.

  • 이전 작업에서 업로드한 homework_pre 아티팩트가 다운로드됩니다. 기본적으로 download-artifact 작업은 단계가 실행 중인 작업 영역 디렉터리에 아티팩트 다운로드합니다. path 입력 매개 변수를 사용하여 다른 다운로드 디렉터리를 지정할 수 있습니다.
  • math-homework.txt 파일의 값을 읽고, 수학 계산을 수행하고, 결과를 math-homework.txt에 다시 저장하여 내용을 덮어씁니다.
  • math-homework.txt 파일을 업로드합니다. v4에서는 아티팩트가 변경 불가능한 것으로 간주되므로 아티팩트에 다른 입력인 homework_final이 이름으로 전달됩니다.{ % else %}이 업로드는 동일한 이름을 공유하므로 이전에 업로드한 아티팩트를 덮어씁니다.

작업 3는 이전 작업에 업로드된 결과를 표시합니다.

  • 작업 2의 homework_final 아티팩트{ %else %}homework 아티팩트를 다운로드합니다.
  • 수학 수식의 결과를 로그에 출력합니다.

이 워크플로 예시에서 수행되는 전체 수학 연산은 (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

워크플로 실행은 생성한 모든 아티팩트를 보관합니다. 보관된 아티팩트 다운로드에 대한 자세한 내용은 "워크플로 아티팩트 다운로드"을 참조하세요.

추가 참고 자료