upload artifact

@actions/upload-artifact

경고

actions/upload-artifact@v3은 2024년 11월 30일 에 지원 중단될 예정입니다. 자세히 알아보세요. 마찬가지로 v1/v2도 2024년 6월 30일 에 지원 중단될 예정입니다. v4 아티팩트 작업을 사용하려면 워크플로를 업데이트하세요. 이번 지원 중단은 고객이 사용하는 기존 GitHub Enterprise Server 버전에 영향을 미치지 않습니다.

워크플로 실행에서 작업 아티팩트를 업로드합니다. @actions/artifact 패키지로 내부적으로 구동됩니다.

다운로드 아티팩트도 참조하세요.

• @actions/upload-artifact
  • v4 - 새로운 기능
    • 개량
    • 주요 변경 사항
  • 용법
    • 입력
    • 출력
  • 예
    • 개별 파일 업로드
    • 전체 디렉토리 업로드
    • 와일드카드 패턴을 사용하여 업로드
    • 다중 경로 및 제외를 사용하여 업로드
    • 압축 수준 변경(속도 대 크기)
    • 파일을 찾을 수 없는 경우 사용자 정의
    • (아님) 동일한 아티팩트에 업로드
    • 환경 변수 및 물결표 확장
    • 보유기간
    • 출력 사용
      • 단계 간 출력 예시
      • 작업 간 출력 예시
    • 아티팩트 덮어쓰기
  • 제한 사항
    • 유물 수
    • 우편 아카이브
    • 권한 상실
  • 업로드는 어디로 가나요?

v4 - 새로운 기능

중요한

upload-artifact@v4+는 현재 GHES에서 지원되지 않습니다. GHES를 사용하는 경우 v3를 사용해야 합니다.

upload-artifact@v4 및 download-artifact@v4의 릴리스는 Artifacts의 백엔드 아키텍처에 대한 주요 변경 사항입니다. 성능과 행동이 많이 개선되었습니다.

자세한 내용은 @actions/artifact 문서를 참조하세요.

또한 새로운 하위 작업인 actions/upload-artifact/merge 도 있습니다. 자세한 내용은 해당 작업의 README를 확인하세요.

개량

1. 최악의 시나리오에서 업로드 속도가 90% 이상 향상되어 훨씬 더 빨라졌습니다.
2. 업로드되면 아티팩트 ID가 반환되고 UI 및 REST API에서 아티팩트를 즉시 사용할 수 있습니다. 이전에는 ID를 사용할 수 있거나 API를 활용하려면 실행이 완료될 때까지 기다려야 했습니다.
3. 아티팩트의 콘텐츠는 불변의 아카이브에 함께 업로드됩니다. 아티팩트를 삭제하고 다시 생성하지 않는 한(새 ID를 갖게 됨) 후속 작업에서 변경할 수 없습니다. 이 두 가지 요인 모두 실수로 아티팩트 파일을 손상시킬 가능성을 줄이는 데 도움이 됩니다.
4. 아티팩트의 압축 수준은 속도나 크기 감소를 위해 수동으로 조정할 수 있습니다.

주요 변경 사항

1. 자체 호스팅 실행기에서는 추가 방화벽 규칙이 필요할 수 있습니다.

2. 동일한 이름의 Artifact에 여러 번 업로드합니다.

   이 새 버전에서는 아티팩트가 생성되는 방식으로 인해 더 이상 동일한 이름의 아티팩트에 여러 번 업로드할 수 없습니다. 업로드를 이름이 다른 여러 아티팩트로 분할하거나 한 번만 업로드해야 합니다. 그렇지 않으면 오류가 발생 합니다 .

3. 개별 작업에 대한 아티팩트 제한입니다. 이제 워크플로 실행의 각 작업에는 아티팩트가 500개로 제한됩니다.

4. v4.4 이상에서는 기본적으로 숨김 파일이 제외됩니다.

주요 변경 사항에 대한 지원은 MIGRATION.md를 참조하세요.

용법

입력

- uses : actions/upload-artifact@v4
  with :
    # Name of the artifact to upload.
    # Optional. Default is 'artifact'
    name :

    # A file, directory or wildcard pattern that describes what to upload
    # Required.
    path :

    # The desired behavior if no files are found using the provided path.
    # Available Options:
    #   warn: Output a warning but do not fail the action
    #   error: Fail the action with an error message
    #   ignore: Do not output any warnings or errors, the action does not fail
    # Optional. Default is 'warn'
    if-no-files-found :

    # Duration after which artifact will expire in days. 0 means using default retention.
    # Minimum 1 day.
    # Maximum 90 days unless changed from the repository settings page.
    # Optional. Defaults to repository settings.
    retention-days :

    # The level of compression for Zlib to be applied to the artifact archive.
    # The value can range from 0 to 9.
    # For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
    # Optional. Default is '6'
    compression-level :

    # If true, an artifact with a matching name will be deleted before a new one is uploaded.
    # If false, the action will fail if an artifact for the given name already exists.
    # Does not fail if the artifact does not exist.
    # Optional. Default is 'false'
    overwrite :

    # Whether to include hidden files in the provided path in the artifact
    # The file contents of any hidden files in the path should be validated before
    # enabled this to avoid uploading sensitive information.
    # Optional. Default is 'false'
    include-hidden-files :

출력

이름	설명	예
artifact-id	아티팩트의 GitHub ID는 REST API에서 사용할 수 있습니다.	1234
artifact-url	아티팩트를 다운로드하기 위한 URL입니다. 이슈 또는 끌어오기 요청의 아티팩트에 연결하는 등 다양한 시나리오에서 사용할 수 있습니다. 이 URL이 작동하려면 사용자가 로그인해야 합니다. 이 URL은 아티팩트가 만료되지 않았거나 아티팩트, 실행 또는 저장소가 삭제되지 않은 한 유효합니다.	https://github.com/example-org/example-repo/actions/runs/1/artifacts/1234

예

개별 파일 업로드

 steps :
- run : mkdir -p path/to/artifact
- run : echo hello > path/to/artifact/world.txt
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/world.txt

전체 디렉토리 업로드

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/ # or path/to/artifact

와일드카드 패턴을 사용하여 업로드

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/**/[abc]rtifac?/*

다중 경로 및 제외를 사용하여 업로드

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : |
      path/output/bin/
      path/output/test-results
      !path/**/*.tmp

동작 및 문서와 함께 지원되는 와일드카드를 보려면 내부적으로 파일을 검색하는 데 사용되는 @actions/glob을 참조하세요.

와일드카드 패턴을 사용하는 경우 경로 계층 구조는 첫 번째 와일드카드 패턴 이후에 유지됩니다.

 path/to/*/directory/foo?.txt =>
    ∟ path/to/some/directory/foo1.txt
    ∟ path/to/some/directory/foo2.txt
    ∟ path/to/other/directory/foo1.txt

would be flattened and uploaded as =>
    ∟ some/directory/foo1.txt
    ∟ some/directory/foo2.txt
    ∟ other/directory/foo1.txt

여러 경로가 입력으로 제공되는 경우 모든 검색 경로의 최소 공통 조상이 아티팩트의 루트 디렉터리로 사용됩니다. 제외 경로는 디렉터리 구조에 영향을 주지 않습니다.

상대 및 절대 파일 경로가 모두 허용됩니다. 상대 경로는 현재 작업 디렉터리를 기준으로 합니다. YAML 별칭으로 해석되는 것을 방지하려면 와일드카드 문자로 시작하는 경로를 따옴표로 묶어야 합니다.

압축 수준 변경(속도 대 크기)

크거나 쉽게 압축할 수 있는 데이터를 아티팩트에 업로드하는 경우 압축 수준을 조정하면 이점을 얻을 수 있습니다. 기본적으로 압축 수준은 GNU Gzip과 동일한 6 입니다.

값의 범위는 0에서 9까지입니다.

• 0: 압축하지 않음
• 1: 최고 속도
• 6: 기본 압축(GNU Gzip과 동일)
• 9: 최고의 압축

수준이 높을수록 압축 성능이 향상되지만 완료하는 데 시간이 더 오래 걸립니다. 쉽게 압축되지 않는 대용량 파일의 경우 훨씬 빠른 업로드를 위해 값 0 을 권장합니다.

예를 들어 임의의 바이너리 데이터를 업로드하는 경우 압축을 완전히 선택 해제하면 다음과 같은 이점이 없으므로 많은 시간을 절약할 수 있습니다.

- name : Make a 1GB random binary file
  run : |
    dd if=/dev/urandom of=my-1gb-file bs=1M count=1000
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : my-1gb-file
    compression-level : 0 # no compression

그러나 쉽게 압축되는 데이터(예: 일반 텍스트, 코드 등)를 업로드하는 경우 압축 수준을 높여 공간과 비용을 절약할 수 있습니다. 그러나 이는 CPU에 부담을 주어 업로드 속도가 느려집니다.

- name : Make a file with a lot of repeated text
  run : |
    for i in {1..100000}; do echo -n 'foobar' >> foobar.txt; done
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : foobar.txt
    compression-level : 9 # maximum compression

파일을 찾을 수 없는 경우 사용자 정의

경로로 인해 아티팩트에 대한 파일이 발견되지 않으면 작업은 성공하지만 경고가 인쇄됩니다. 특정 시나리오에서는 작업을 실패하거나 경고를 표시하지 않는 것이 바람직할 수 있습니다. if-no-files-found 옵션을 사용하면 파일이 발견되지 않은 경우 작업 동작을 사용자 정의할 수 있습니다.

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/
    if-no-files-found : error # 'warn' or 'ignore' are also available, defaults to `warn`

(아님) 동일한 아티팩트에 업로드

이전 버전의 upload-artifact 와 달리 v4 에서는 여러 작업을 통해 동일한 아티팩트에 업로드하는 것이 지원되지 않습니다 .

- run : echo hi > world.txt
- uses : actions/upload-artifact@v4
  with :
    # implicitly named as 'artifact'
    path : world.txt

- run : echo howdy > extra-file.txt
- uses : actions/upload-artifact@v4
  with :
    # also implicitly named as 'artifact', will fail here!
    path : extra-file.txt

생성된 각 아티팩트는 멱등성이 있으므로 여러 작업이 동일한 아티팩트를 수정할 수 없으므로 아티팩트 이름은 고유해야 합니다.

매트릭스 시나리오에서는 동일한 아티팩트에 실수로 업로드하지 않도록 주의하세요. 그렇지 않으면 충돌 오류가 발생합니다. 매트릭스의 접두사 또는 접미사를 사용하여 아티팩트의 이름을 지정하는 것이 가장 좋습니다.

 jobs :
  upload :
    name : Generate Build Artifacts

    strategy :
      matrix :
        os : [ubuntu-latest, windows-latest]
        version : [a, b, c]

    runs-on : ${{ matrix.os }}

    steps :
    - name : Build
      run : ./some-script --version=${{ matrix.version }} > my-binary
    - name : Upload
      uses : actions/upload-artifact@v4
      with :
        name : binary-${{ matrix.os }}-${{ matrix.version }}
        path : my-binary

이로 인해 binary-ubuntu-latest-a , binary-windows-latest-b 등과 같은 아티팩트가 생성됩니다.

이전에는 아티팩트 이름이 동일하도록 허용되어 예상치 못한 변형과 ​​우발적인 손상이 발생했습니다. upload-artifact@v4로 생성된 아티팩트는 변경할 수 없습니다.

환경 변수 및 물결표 확장

$HOME 대신 경로 입력에 ~ 사용할 수 있습니다. 기본 물결표 확장이 지원됩니다.

  - run : |
      mkdir -p ~/new/artifact
      echo hello > ~/new/artifact/world.txt
  - uses : actions/upload-artifact@v4
    with :
      name : my-artifacts
      path : ~/new/**/*

컨텍스트 표현식과 함께 환경 변수를 입력에 사용할 수도 있습니다. 문서를 보려면 컨텍스트 및 표현식 구문을 참조하세요.

    env :
      name : my-artifact
    steps :
    - run : |
        mkdir -p ${{ github.workspace }}/artifact
        echo hello > ${{ github.workspace }}/artifact/world.txt
    - uses : actions/upload-artifact@v4
      with :
        name : ${{ env.name }}-name
        path : ${{ github.workspace }}/artifact/**/*

다른 단계에서 생성된 환경 변수의 경우 env 표현식 구문을 사용해야 합니다.

    steps :
    - run : |
        mkdir testing
        echo "This is a file to upload" > testing/file.txt
        echo "artifactPath=testing/file.txt" >> $GITHUB_ENV
    - uses : actions/upload-artifact@v4
      with :
        name : artifact
        path : ${{ env.artifactPath }} # this will resolve to testing/file.txt at runtime

보유기간

아티팩트는 기본적으로 90일 동안 보관됩니다. retention-days 입력을 사용하여 더 짧은 보유 기간을 지정할 수 있습니다.

  - name : Create a file
    run : echo "I won't live long" > my_file.txt

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

보존 기간은 1에서 90 사이여야 합니다. 자세한 내용은 아티팩트 및 로그 보존 정책을 참조하세요.

출력 사용

아티팩트 업로드가 성공하면 artifact-id 출력을 사용할 수 있습니다. 이 ID는 Artifact REST API와 함께 사용할 수 있는 고유 식별자입니다.

단계 간 출력 예시

    - uses : actions/upload-artifact@v4
      id : artifact-upload-step
      with :
        name : my-artifact
        path : path/to/artifact/content/

    - name : Output artifact ID
      run :  echo 'Artifact ID is ${{ steps.artifact-upload-step.outputs.artifact-id }}' 

작업 간 출력 예시

 jobs :
  job1 :
    runs-on : ubuntu-latest
    outputs :
      output1 : ${{ steps.artifact-upload-step.outputs.artifact-id }}
    steps :
      - uses : actions/upload-artifact@v4
        id : artifact-upload-step
        with :
          name : my-artifact
          path : path/to/artifact/content/
  job2 :
    runs-on : ubuntu-latest
    needs : job1
    steps :
      - env :
          OUTPUT1 : ${{needs.job1.outputs.output1}}
        run : echo "Artifact ID from previous job is $OUTPUT1"

아티팩트 덮어쓰기

아티팩트를 변경하는 것은 불가능하지만 완전히 덮어쓸 수 있습니다. 하지만 이렇게 하면 아티팩트에 새 ID가 부여되며 이전 ID는 더 이상 존재하지 않습니다.

 jobs :
  upload :
    runs-on : ubuntu-latest
    steps :
      - name : Create a file
        run : echo "hello world" > my-file.txt
      - name : Upload Artifact
        uses : actions/upload-artifact@v4
        with :
          name : my-artifact # NOTE: same artifact name
          path : my-file.txt
  upload-again :
    needs : upload
    runs-on : ubuntu-latest
    steps :
      - name : Create a different file
        run : echo "goodbye world" > my-file.txt
      - name : Upload Artifact
        uses : actions/upload-artifact@v4
        with :
          name : my-artifact # NOTE: same artifact name
          path : my-file.txt
          overwrite : true

숨겨진 파일 업로드

기본적으로 이 작업에서는 숨겨진 파일을 무시하여 실수로 민감한 정보를 업로드하는 것을 방지합니다.

숨겨진 파일을 업로드해야 하는 경우 include-hidden-files 입력을 사용할 수 있습니다. 업로드된 아티팩트에 있어서는 안 되는 중요한 정보가 포함된 모든 파일은 path 사용하여 제외할 수 있습니다.

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    include-hidden-files : true
    path : |
      path/output/
      !path/output/.production.env

숨겨진 파일은 . 또는 .로 시작하는 폴더 내의 파일 . . Windows에서는 숨겨진 속성이 있는 파일과 디렉터리에 . 접두사.

제한 사항

유물 수

개별 작업 내에서 해당 작업에 대해 생성할 수 있는 아티팩트는 500개로 제한됩니다.

공유 저장소 할당량을 초과한 경우 아티팩트에 의해 제한될 수도 있습니다. 저장용량은 6~12시간마다 계산됩니다. 자세한 내용은 설명서를 참조하세요.

우편 아카이브

아티팩트가 업로드되면 모든 파일이 불변의 Zip 아카이브로 통합됩니다. 현재로서는 Zip 이외의 형식으로 아티팩트를 다운로드하거나 개별 아티팩트 콘텐츠를 다운로드할 수 있는 방법이 없습니다.

권한 상실

아티팩트 업로드 중에는 파일 권한이 유지되지 않습니다. 모든 디렉토리에는 755 있고 모든 파일에는 644 있습니다. 예를 들어, chmod 사용하여 파일을 실행 가능하게 만든 다음 해당 파일을 업로드하면 다운로드 후 파일이 더 이상 실행 파일로 설정된다는 보장이 없습니다.

권한을 유지해야 하는 경우 아티팩트를 업로드하기 전에 모든 파일을 함께 tar 할 수 있습니다. 다운로드 후 tar 파일은 파일 권한과 대소문자 구분을 유지합니다.

- name : ' Tar files '
  run : tar -cvf my_files.tar /path/to/my/directory

- name : ' Upload Artifact '
  uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : my_files.tar 

업로드는 어디로 가나요?

워크플로 요약 페이지 하단에는 아티팩트 전용 섹션이 있습니다. 다음은 볼 수 있는 내용의 스크린샷입니다.

아티팩트를 삭제하는 데 사용할 수 있는 휴지통 아이콘이 있습니다. 이 아이콘은 저장소에 대한 쓰기 권한이 있는 사용자에게만 표시됩니다.

아티팩트의 크기는 바이트 단위로 표시됩니다. 표시된 아티팩트 크기는 업로드 중에 upload-artifact 생성하는 zip의 크기를 나타냅니다.