워크플로우에서 미리 작성된 빌딩 블록 사용하기

미리 작성된 액션을 사용하고 커스터마이즈해 워크플로우를 강화할 수 있어요.

출처: 문서

본문

미리 작성된 액션을 사용하고 커스터마이즈해 워크플로우를 강화할 수 있어요.

워크플로우 편집기에서 Marketplace 액션 둘러보기

저장소의 워크플로우 편집기에서 직접 액션을 검색하고 둘러볼 수 있어요. 사이드바에서 특정 액션을 검색하고, 추천 액션을 보고, 추천 카테고리를 둘러볼 수 있습니다. 또한 GitHub 커뮤니티에서 액션이 받은 별점 수를 볼 수 있어요.

저장소에서 편집하려는 워크플로우 파일로 이동하세요.
파일 보기 오른쪽 위 모서리에서 워크플로우 편집기를 열려면 을 클릭하세요.
편집기 오른쪽에서 GitHub Marketplace 사이드바를 사용해 액션을 둘러보세요. 배지가 있는 액션은 GitHub가 액션의 작성자를 파트너 조직으로 검증했음을 나타냅니다.

워크플로우에 액션 추가하기

워크플로우 파일에서 액션을 참조해 워크플로우에 액션을 추가할 수 있어요. 워크플로우에서 사용하는 액션은 다음에 정의할 수 있습니다:

워크플로우 파일과 같은 저장소
모든 공개 저장소
Docker Hub에 게시된 Docker 컨테이너 이미지

GitHub Actions 워크플로우에서 참조된 액션을 워크플로우가 포함된 저장소의 종속성 그래프에서 종속성으로 볼 수 있습니다. 자세한 내용은 "Dependency graph."을 참고하세요.

[!NOTE] 보안을 강화하기 위해 GitHub Actions는 액션이나 재사용 가능한 워크플로우에 대한 리다이렉트를 지원하지 않습니다. 즉 액션 저장소의 소유자, 이름 또는 액션의 이름이 변경되면 이전 이름으로 해당 액션을 사용하는 모든 워크플로우가 실패합니다.

GitHub Marketplace에서 액션 추가하기

액션의 목록 페이지에는 액션의 버전과 액션을 사용하는 데 필요한 워크플로우 구문이 포함되어 있어요. 액션에 업데이트가 이루어져도 워크플로우를 안정적으로 유지하려면 워크플로우 파일에서 Git 또는 Docker 태그 번호를 지정해 사용할 액션의 버전을 참조할 수 있어요.

워크플로우에서 사용하려는 액션으로 이동하세요.
액션의 전체 마켓플레이스 목록을 보려면 클릭하세요.
"Installation" 아래에서 을 클릭해 워크플로우 구문을 복사하세요.
구문을 워크플로우의 새 단계로 붙여넣으세요. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.
액션에 입력을 제공해야 한다면 워크플로우에서 설정하세요. 액션이 필요로 할 수 있는 입력에 대한 정보는 Using pre-written building blocks in your workflow를 참고하세요.

워크플로우에 추가하는 액션에 대해 Dependabot 버전 업데이트를 활성화할 수도 있어요. 자세한 내용은 Keeping your actions up to date with Dependabot을 참고하세요.

같은 저장소에서 액션 추가하기

액션이 워크플로우 파일이 액션을 사용하는 같은 저장소에 정의되어 있다면, 워크플로우 파일에서 $/path/to/dir 자기 저장소 참조 또는 {owner}/{repo}@{ref} 또는 ./path/to/dir 구문으로 액션을 참조할 수 있어요. $/ 구문은 GitHub Enterprise Server에서 사용할 수 없습니다.

예시 저장소 파일 구조:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

$/path/to/dir 자기 저장소 참조로 액션을 참조하는 것을 권장합니다. 이것은 실행 중인 커밋의 같은 저장소로 해석되므로 먼저 저장소를 체크아웃할 필요가 없어요. $/이 {owner}/{repo}@{ref} 및 ./와 어떻게 비교되는지에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

$/을 사용하는 예시 워크플로우 파일:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step references an action in the same repository at the
      # running commit. No repository checkout is required.
      - name: Use hello-world-action
        uses: $/.github/actions/hello-world-action

상대 ./path/to/dir 구문으로 액션을 참조할 수도 있지만 더 오류가 발생하기 쉽습니다. 경로는 기본 작업 디렉토리(github.workspace, $GITHUB_WORKSPACE)를 기준(./)으로 하므로 체크아웃 단계가 필요하고, 액션이 저장소를 워크플로우와 다른 위치로 체크아웃하면 상대 경로를 업데이트해야 합니다.

./을 사용하는 예시 워크플로우 파일:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v6
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

action.yml 파일은 액션에 대한 메타데이터를 제공하는 데 사용됩니다. 이 파일의 내용에 대해서는 Metadata syntax reference에서 알아보세요.

다른 저장소에서 액션 추가하기

액션이 워크플로우 파일과 다른 저장소에 정의되어 있다면, 워크플로우 파일에서 {owner}/{repo}@{ref} 구문으로 액션을 참조할 수 있어요.

액션은 공개 저장소에 저장되어야 합니다.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v7

Docker Hub의 컨테이너 참조하기

액션이 Docker Hub에 게시된 Docker 컨테이너 이미지에 정의되어 있다면, 워크플로우 파일에서 docker://{image}:{tag} 구문으로 액션을 참조해야 합니다. 코드와 데이터를 보호하기 위해 워크플로우에서 사용하기 전에 Docker Hub의 Docker 컨테이너 이미지 무결성을 검증할 것을 강력히 권장합니다.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Docker 액션의 몇 가지 예는 Docker-image.yml workflow과 Creating a Docker container action을 참고하세요.

워크플로우에서 액션 사용을 위한 보안 강화

GitHub는 워크플로우의 보안을 높이는 데 사용할 수 있는 보안 기능을 제공합니다. GitHub의 기본 제공 기능을 사용해 소비하는 액션의 취약점에 대한 알림을 받거나, 워크플로우의 액션을 최신 상태로 유지하는 프로세스를 자동화할 수 있어요. 자세한 내용은 Secure use reference를 참고하세요.

커스텀 액션에 릴리스 관리 사용하기

커뮤니티 액션의 작성자는 태그, 브랜치 또는 SHA 값을 사용해 액션의 릴리스를 관리할 수 있습니다. 다른 종속성과 마찬가지로 액션에 대한 업데이트를 자동으로 수락하는 것에 대한 편안함에 기반해 사용하려는 액션의 버전을 지정해야 합니다.

워크플로우 파일에서 액션의 버전을 지정하게 됩니다. 릴리스 관리 접근 방식과 사용할 태그, 브랜치 또는 SHA 값에 대한 정보는 액션의 문서를 확인하세요.

[!NOTE] 타사 액션을 사용할 때는 SHA 값을 사용할 것을 권장합니다. 그러나 Dependabot은 의미론적 버전 관리를 사용하는 취약한 GitHub Actions에 대해서만 Dependabot 알림을 생성한다는 점에 유의하는 것이 중요합니다. 자세한 내용은 Secure use reference와 Dependabot alerts를 참고하세요.

태그 사용하기

태그는 주요 및 부 버전 간에 전환할 시기를 결정하는 데 유용하지만 더 일시적이며 유지 관리자가 이동하거나 삭제할 수 있어요. 이 예시는 v1.0.1로 태그된 액션을 대상으로 하는 방법을 보여줍니다:

steps:
  - uses: actions/[email protected]

SHA 사용하기

더 안정적인 버전 관리를 원한다면 액션 버전과 연결된 SHA 값을 사용해야 합니다. SHA는 불변이므로 태그나 브랜치보다 더 안정적입니다. 그러나 이 접근 방식은 중요한 버그 수정과 보안 업데이트를 포함해 액션에 대한 업데이트를 자동으로 받지 못한다는 의미입니다. 커밋의 전체 SHA 값을 사용해야 하며 축약된 값은 안 됩니다. SHA를 선택할 때는 액션의 저장소에서 온 것인지 저장소 포크가 아닌지 확인해야 합니다. 이 예시는 액션의 SHA를 대상으로 합니다:

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

브랜치 사용하기

액션에 대한 대상 브랜치를 지정하면 항상 해당 브랜치의 현재 버전이 실행됩니다. 이 접근 방식은 브랜치 업데이트에 호환성이 깨지는 변경이 포함되면 문제가 발생할 수 있습니다. 이 예시는 @main이라는 브랜치를 대상으로 합니다:

steps:
  - uses: actions/javascript-action@main

자세한 내용은 Managing custom actions을 참고하세요.

액션과 함께 입력 및 출력 사용하기

액션은 종종 입력을 수락하거나 요구하고 사용할 수 있는 출력을 생성합니다. 예를 들어 액션이 파일 경로, 라벨 이름 또는 액션 처리의 일부로 사용할 다른 데이터를 지정하도록 요구할 수 있어요.

액션의 입력과 출력을 보려면 저장소의 루트 디렉토리에 있는 action.yml을 확인하세요.

이 예시 action.yml에서 inputs 키워드는 file-path라는 필수 입력을 정의하고, 지정되지 않은 경우 사용될 기본값을 포함합니다. outputs 키워드는 결과를 찾을 위치를 알려주는 results-file이라는 출력을 정의합니다.

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

워크플로우에서 미리 작성된 빌딩 블록 사용하기