Core

체크아웃, Docker 빌드, 캐시, 아티팩트 — 파이프라인의 기본 빌딩 블록

collabops/checkout@v2

On-Premise: ✅ airgapped 호환

Git repository를 체크아웃합니다. repo-url의 scheme에 따라 SSH/HTTPS로 자동 분기합니다. HTTPS 사용 시 플랫폼이 주입한 Job Token으로 인증되므로 별도의 인증 설정이 필요 없습니다.

권장: HTTPS repo-url + JobToken 자동 인증. ssh-key는 외부 호스트나 SSH 전용 환경에서만 사용하고, 개인 SSH 키 대신 저장소 단위 Deploy Key를 사용하세요. 배경과 마이그레이션 절차는 인증 문서를 참고하세요.

Input	Required	Default	Description
`repo-url`	YES	-	Git repository URL. SSH(`git@host:ns/repo.git`, `ssh://...`) 또는 HTTPS(`https://host/ns/repo.git`)
`ref`	NO	`$\{\{ collabops.ref_name \}\}`	체크아웃할 Git ref (branch, tag, SHA)
`event-name`	NO	`$\{\{ collabops.event_name \}\}`	이벤트 타입. `change_request` 시 `head-ref`를 자동 사용
`head-ref`	NO	`$\{\{ collabops.head_ref \}\}`	`change_request` 이벤트의 source(head) 브랜치명
`sha`	NO	`$\{\{ collabops.sha \}\}`	체크아웃할 정확한 커밋 SHA
`ssh-key`	NO	`""`	SSH 개인 키 (base64 인코딩). SSH URL 사용 시 필수
`fetch-depth`	NO	`"1"`	히스토리 깊이 (0 = 전체, 1 = shallow)
`clean`	NO	`"true"`	기존 소스 디렉토리 정리 후 clone
`path`	NO	`"/workspace/source"`	체크아웃 대상 경로

예시

기본 — HTTPS + JobToken (가장 권장)

jobs:
  build:
    steps:
      # 가장 일반적인 형태. JobToken 이 자동 주입되어 별도 인증 설정 없음.
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
        image: node:22-alpine

Change Request — head 브랜치 자동

# CR(Change Request) 이벤트 — change_request 트리거 사용.
triggers:
  change_request:
    branches: [main]

jobs:
  test:
    steps:
      # event-name 기본값이 collabops.event_name. change_request 이면
      # head-ref(원본 브랜치) 가 자동으로 사용됨 — 따로 ref 를 줄 필요 없음.
      - name: checkout-pr-head
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
        image: node:22-alpine

전체 히스토리 + 커스텀 경로

jobs:
  release-notes:
    steps:
      - name: checkout-full-history
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
          fetch-depth: "0"            # git log / diff 가 전 히스토리 필요할 때
          path: "/workspace/src"      # 기본 /workspace/source 대신 별도 경로 지정
        image: alpine/git:2.45.2
      - name: generate-changelog
        run: |
          cd /workspace/src
          git log --oneline --no-merges \
            $(git describe --tags --abbrev=0)..HEAD > /workspace/source/CHANGELOG.txt
        image: alpine/git:2.45.2

외부 호스트 — SSH Deploy Key

jobs:
  mirror:
    steps:
      # 외부 SaaS(예: GitHub.com) 등 SSH 가 필요한 경우.
      # 개인 SSH 키 대신 저장소 단위 Deploy Key 를 base64 로 secret 등록.
      - name: checkout-external
        uses: "collabops/checkout@v2"
        with:
          repo-url: "git@github.com:my-org/private-repo.git"
          ref: main
          ssh-key: ${{ secrets.MIRROR_DEPLOY_KEY_B64 }}
        image: alpine/git:2.45.2

포인트 — HTTPS + JobToken 이 기본값이자 권장. SSH 는 외부 호스트 전용. change_request 이벤트에서는 추가 설정 없이 head 브랜치가 잡힘. 전 히스토리가 필요한 작업(git log, semantic-release 등)만 fetch-depth: 0. 여러 리포를 한 Job 에서 체크아웃할 때는 path 로 충돌을 피함.

collabops/docker-login@v1

On-Premise: ✅ airgapped 호환

범용 Docker 레지스트리 인증입니다. username/password 로 .docker/config.json 을 생성하여 docker-build-push 의 push 인증에 사용합니다. registry 미지정 시 Docker Hub. GCP Artifact Registry는 gcloud-docker-auth, AWS ECR은 aws-ecr-auth 를 사용하세요.

Input	Required	Default	Description
`registry`	NO	`"docker.io"`	Docker 레지스트리 호스트 (예: `ghcr.io`). 미지정 시 Docker Hub
`username`	YES	-	레지스트리 사용자명
`password`	YES	-	레지스트리 비밀번호 또는 액세스 토큰. `$\{\{ secrets.* \}\}` 로 전달
`config-path`	NO	`"/workspace/source"`	`.docker/config.json` 생성 기준 경로. `docker-build-push` 의 `docker-config` 와 같은 위치를 가리켜야 함

예시

GHCR (GitHub Container Registry)

jobs:
  publish:
    services:
      - docker
    steps:
      - name: docker-login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USER }}
          # PAT 또는 GHCR 토큰. read:packages / write:packages 권한 필요.
          password: ${{ secrets.GHCR_TOKEN }}
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          tags: "ghcr.io/my-org/api:${{ collabops.sha }}"

Docker Hub (registry 생략)

jobs:
  publish:
    services:
      - docker
    steps:
      - name: docker-login
        # registry 미지정 → docker.io (Docker Hub) 가 기본.
        uses: "collabops/docker-login@v1"
        with:
          username: ${{ secrets.DOCKERHUB_USER }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          tags: "my-org/api:latest"

사설 레지스트리 + 커스텀 config-path

jobs:
  publish:
    services:
      - docker
    steps:
      - name: login-internal-registry
        uses: "collabops/docker-login@v1"
        with:
          registry: registry.internal.example.com
          username: ${{ secrets.INTERNAL_REG_USER }}
          password: ${{ secrets.INTERNAL_REG_TOKEN }}
          # docker-build-push 의 docker-config 와 동일 디렉토리를 가리켜야 인증이 전달됨.
          config-path: /workspace/source/.ci
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          tags: "registry.internal.example.com/team/api:${{ collabops.sha }}"
          docker-config: /workspace/source/.ci/.docker/config.json

포인트 — username/password 는 항상 secret 으로 주입. ECR/Artifact Registry 는 전용 템플릿(aws-ecr-auth, gcloud-docker-auth) 사용 — docker-login 으로 직접 처리하지 않음. config-path 를 변경했다면 docker-build-push 의 docker-config 도 같은 경로로 맞춰야 함.

collabops/docker-build-push@v1

On-Premise: ✅ airgapped 호환

Docker 이미지 빌드 및 멀티 태그 푸시입니다. 이미지를 push 하려면 docker-login · gcloud-docker-auth · aws-ecr-auth 등 인증 템플릿을 먼저 실행해야 합니다.

Input	Required	Default	Description
`tags`	YES	-	이미지 태그 목록 (줄바꿈 구분)
`context`	NO	`"/workspace/source"`	빌드 컨텍스트 경로
`file`	NO	`"Dockerfile"`	Dockerfile 경로 (context 기준 상대 경로)
`push`	NO	`"true"`	빌드 후 푸시 여부
`build-args`	NO	`""`	빌드 인자 (`KEY=VALUE`, 줄바꿈 구분)
`target`	NO	`""`	멀티스테이지 빌드 시 타겟 스테이지
`platform`	NO	`""`	타겟 플랫폼 (예: `linux/amd64`). 단일 플랫폼만 지원 — 멀티아치는 buildx 필요
`cache-from`	NO	`""`	캐시 소스
`cache-to`	NO	`""`	캐시 대상 (`type=inline`). `type=registry,mode=max` 는 buildx 필요
`extra-args`	NO	`""`	추가 docker build 인자
`docker-config`	NO	`"/workspace/source/.docker/config.json"`	인증 config.json 경로. `docker-login` 등 인증 템플릿이 생성한 파일

예시

단일 태그 빌드+push

jobs:
  build:
    services:
      - docker
    steps:
      - name: login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USER }}
          password: ${{ secrets.GHCR_TOKEN }}
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          # 커밋 SHA 1개만 태깅 — 가장 단순한 형태.
          tags: "ghcr.io/my-org/api:${{ collabops.sha }}"

멀티태그 (SHA + latest + 브랜치)

jobs:
  build:
    services:
      - docker
    steps:
      - name: login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USER }}
          password: ${{ secrets.GHCR_TOKEN }}
      - name: build-push-multi
        uses: "collabops/docker-build-push@v1"
        with:
          # 줄바꿈 구분으로 여러 태그를 한 번에 push. ref_name 은 브랜치명.
          tags: |
            ghcr.io/my-org/api:${{ collabops.sha }}
            ghcr.io/my-org/api:${{ collabops.ref_name }}
            ghcr.io/my-org/api:latest

멀티스테이지 target + build-args + platform

jobs:
  build:
    services:
      - docker
    steps:
      - name: login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USER }}
          password: ${{ secrets.GHCR_TOKEN }}
      - name: build-runner-stage
        uses: "collabops/docker-build-push@v1"
        with:
          tags: "ghcr.io/my-org/web:${{ collabops.sha }}"
          file: Dockerfile
          target: runner               # 멀티스테이지 Dockerfile 의 최종 stage 이름
          platform: linux/amd64        # 단일 플랫폼만 지원(멀티아치는 buildx 필요)
          build-args: |
            NODE_ENV=production
            BUILD_REVISION=${{ collabops.sha }}

Inline 캐시로 재빌드 가속

jobs:
  build:
    services:
      - docker
    steps:
      - name: login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USER }}
          password: ${{ secrets.GHCR_TOKEN }}
      - name: build-with-inline-cache
        uses: "collabops/docker-build-push@v1"
        with:
          tags: |
            ghcr.io/my-org/api:${{ collabops.sha }}
            ghcr.io/my-org/api:cache
          # type=inline 은 buildx 없이도 동작. 이전 빌드의 :cache 태그를 캐시 소스로 사용.
          cache-from: type=registry,ref=ghcr.io/my-org/api:cache
          cache-to: type=inline

포인트 — 인증 Step 을 항상 먼저 실행하고 같은 Job 안에 둘 것. tags 는 줄바꿈으로 여러 태그를 한 번에 push 가능. type=registry,mode=max 같은 buildx 전용 캐시는 buildx 환경에서만 동작 — 일반 docker:27.1 이미지에서는 type=inline 을 사용. 멀티아치가 필요하면 buildx 가 활성화된 이미지로 변경.

collabops/cache@v2

On-Premise: ✅ airgapped 호환

플랫폼 스토리지 기반 의존성 캐시를 저장하고 복원합니다. restore와 save를 별도 Step으로 분리하여 사용합니다. airgapped On-Premise 호환 — minio/mc 이미지에서 바이너리를 워크스페이스로 복사해 런타임 외부 다운로드가 없습니다.

Input	Required	Default	Description
`action`	YES	-	캐시 동작 (`restore` 또는 `save`)
`path`	YES	-	캐시할 디렉토리 경로 (상대경로는 `/workspace/source` 기준)
`key`	YES	-	캐시 키 (고유 식별자)
`restore-keys`	NO	`""`	폴백 캐시 키 prefix (줄바꿈으로 구분, `restore` 시에만 사용)

예시

pnpm node_modules — restore→build→save 흐름

# 캐시 키는 lockfile 파일명 + 브랜치명으로 구성. hashFiles() 는 미지원.
# 동일 브랜치에서 lockfile 변경이 없으면 같은 키 → 캐시 적중.
jobs:
  install:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
      - name: cache-restore
        uses: "collabops/cache@v2"
        with:
          action: restore
          path: node_modules
          key: "pnpm-${{ collabops.ref_name }}"
      - name: install-deps
        run: |
          corepack enable
          pnpm install --frozen-lockfile
        image: node:22-alpine
      - name: build
        run: pnpm build
        image: node:22-alpine
      - name: cache-save
        uses: "collabops/cache@v2"
        with:
          action: save
          path: node_modules
          key: "pnpm-${{ collabops.ref_name }}"

restore-keys 폴백 — lockfile 변경 직후에도 부분 캐시 활용

jobs:
  install:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
      - name: cache-restore-with-fallbacks
        uses: "collabops/cache@v2"
        with:
          action: restore
          path: node_modules
          key: "pnpm-${{ collabops.ref_name }}-${{ collabops.sha }}"
          # 정확한 키가 없으면 prefix 매칭으로 가장 최근 캐시 사용.
          # 위에서 아래로 시도 — 매칭되는 첫 prefix 의 최신 캐시를 가져옴.
          restore-keys: |
            pnpm-${{ collabops.ref_name }}-
            pnpm-main-
            pnpm-

포인트 — restore 와 save 는 반드시 별도 Step. hashFiles() 는 현재 미지원이므로 키는 collabops.ref_name(브랜치) 같은 결정적 변수로 구성. Lockfile 갱신 후 cold start 가 부담이면 restore-keys 로 더 일반적인 prefix 를 폴백 지정. Step-level if 는 미지원이므로 빌드 실패 시 캐시 오염을 막으려면 캐시 save 를 별도 Job 으로 분리하고 그 Job 에 if: "success()" 를 거는 방식을 사용.

collabops/upload-artifact@v2

On-Premise: ✅ airgapped 호환

빌드 산출물을 플랫폼 스토리지에 업로드합니다. Job 간 파일 전달에 사용합니다. airgapped On-Premise 호환.

Input	Required	Default	Description
`name`	YES	-	아티팩트 이름 (예: `build-output`, `dist`)
`path`	YES	-	업로드할 파일 또는 디렉토리 경로 (상대경로는 `/workspace/source` 기준)

예시

단일 디렉토리 업로드

jobs:
  build:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
      - name: build
        run: |
          npm ci
          npm run build       # → /workspace/source/dist 생성
        image: node:22-alpine
      # 빌드 산출물을 다른 Job 에 넘기기 위해 업로드.
      - name: upload-dist
        uses: "collabops/upload-artifact@v2"
        with:
          name: web-dist
          path: dist           # 상대경로는 /workspace/source 기준

포인트 — 한 Job 안에서 생성된 파일을 다른 Job 에 전달할 때 사용. name 은 같은 워크플로우에서 유일해야 함 — download-artifact 가 이 이름으로 식별. 단일 파일도 가능하나 디렉토리 단위로 묶어두면 파라미터화가 쉬움.

collabops/download-artifact@v2

On-Premise: ✅ airgapped 호환

플랫폼 스토리지에서 빌드 산출물을 다운로드합니다. 같은 워크플로우에서 upload-artifact로 업로드된 파일을 받을 때 사용합니다. airgapped On-Premise 호환.

Input	Required	Default	Description
`name`	YES	-	다운로드할 아티팩트 이름
`path`	NO	`""`	복원 경로 (상대경로는 `/workspace/source` 기준, 미지정 시 아티팩트 이름 사용)

예시

두 Job 흐름 — build 가 upload, deploy 가 download

jobs:
  build:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
      - name: build-app
        run: |
          npm ci
          npm run build
        image: node:22-alpine
      - name: upload-dist
        uses: "collabops/upload-artifact@v2"
        with:
          name: web-dist
          path: dist

  deploy:
    needs: [build]                # 같은 워크플로우의 build Job 완료 후 실행
    steps:
      # 동일 이름으로 산출물을 받는다. path 미지정 시 name 과 같은 디렉토리에 풀림.
      - name: pull-build-output
        uses: "collabops/download-artifact@v2"
        with:
          name: web-dist
          path: dist
      - name: list-dist
        run: ls -la /workspace/source/dist   # 이후 단계에서 그대로 사용
        image: alpine:3.20

포인트 — upload-artifact 의 name 과 정확히 일치해야 받음. needs 로 명시적인 Job 의존성을 잡지 않으면 download 가 upload 보다 먼저 실행될 수 있음. path 미지정 시 name 과 같은 디렉토리에 펼침 — 의도와 어긋나면 명시 권장.

목차