여러 워크플로우에서 반복되는 step 3~4개를 하나의 action으로 묶은 이유

문제 발생

여러 워크플로우 파일에서 "pnpm 설치 → 의존성 캐시 복원 → pnpm install"이라는 똑같은 3단계가 반복됐습니다. Job 전체를 재사용하는 reusable workflow로 만들기엔 너무 작은 단위였고, 그렇다고 계속 복붙하기엔 셋 중 하나만 바뀌어도 모든 파일을 손대야 했습니다.

원인 분석

github-actions-reusable-workflows.json의 사례가 "job 전체(여러 step)를 재사용"하는 큰 단위였다면, 이번 상황은 그보다 작은 "step 몇 개짜리 묶음"입니다. Reusable workflow는 jobs: 전체를 대체하는 방식이라, 이미 다른 로직이 있는 job의 일부 step만 재사용하고 싶은 경우에는 오히려 구조가 맞지 않습니다.

해결 방안

Composite action으로 여러 step을 하나의 커스텀 action처럼 묶습니다.

# .github/actions/setup-pnpm/action.yml
name: "Setup pnpm and install"
description: "pnpm 설치, 캐시 복원, 의존성 설치를 한 번에"
runs:
  using: "composite"
  steps:
    - uses: pnpm/action-setup@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 24
        cache: pnpm
    - run: pnpm install --frozen-lockfile
      shell: bash

# 각 워크플로우 파일에서
steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup-pnpm   # 3단계가 한 줄로 대체됨
  - run: pnpm build

1. Composite action의 각 run step에는 shell:을 명시적으로 지정해야 합니다 — 일반 워크플로우의 run step과 달리, composite action 안에서는 기본 셸이 자동으로 추론되지 않습니다. 이걸 빠뜨리면 action 자체가 실패합니다.
2. inputs/outputs를 정의해 매개변수를 받거나 결과를 다음 step에 넘길 수 있습니다 — 일반 GitHub Action(marketplace의 서드파티 action들)과 동일한 인터페이스입니다.
3. 선택 기준: 재사용하려는 범위가 "job 하나 전체"(여러 job, 조건 분기 등 복잡한 구조 포함)라면 reusable workflow, "몇 개의 연속된 step"(다른 job의 일부로 자연스럽게 끼워 넣고 싶은 것)이라면 composite action이 적합합니다. 이번 사례처럼 "기존 job 안에 끼워 넣을 준비 단계"는 전형적인 composite action의 용도입니다.
4. 같은 저장소 안에서만 쓸 계획이라면 .github/actions/ 아래 두고 상대 경로(./)로 참조하는 것으로 충분하지만, 여러 저장소에서 공유하고 싶다면 별도의 공개(또는 내부) 저장소로 만들어 owner/repo@ref 형태로 참조합니다.

공식 문서

• GitHub Actions Docs: Creating a composite action