워크스페이스 템플릿
워크스페이스에서 커스텀 템플릿을 작성하고 등록하는 방법
워크스페이스 템플릿은 팀에서 자주 사용하는 Job 구성을 재사용 가능한 형태로 정의하는 기능입니다. Git 저장소에 템플릿 파일을 push하면 자동으로 등록되며, Workflow에서 include로 참조하여 사용합니다.
워크스페이스 템플릿은 Job 레벨에서 포함됩니다. Step 레벨의 uses(시스템 템플릿)와는 다른 메커니즘입니다.
시스템 템플릿과의 차이
| 구분 | 시스템 템플릿 | 워크스페이스 템플릿 |
|---|---|---|
| 범위 | 전체 공유 (빌트인) | 워크스페이스 내에서만 사용 |
| 참조 방식 | Step-level uses: "collabops/name@version" | Job-level include: "workspace/repo/name@version" |
| 단위 | Step (하나의 실행 단위) | Job (이미지, 환경 변수, Step 목록 포함) |
| 버전 관리 | @version 지정 | @version 지정 (생략 시 v1) |
| 등록 방법 | CollabOps 제공 | Git push 시 자동 등록 |
등록 방법
Git 저장소의 .collabops/template/ 디렉토리에 템플릿 파일을 추가하고 push하면 자동으로 등록됩니다. 템플릿은 \{이름\}/\{버전\}/ 단위로 구성됩니다.
.collabops/
template/
deploy-k8s/
v1/
template.yml
v2/
template.yml
build-image/
v1/
template.yml각 템플릿은 .collabops/template/{템플릿이름}/{버전}/template.yml 경로에 위치해야 합니다. 파일 이름은 반드시 template.yml이어야 하고, 버전 디렉토리(예: v1)가 필수입니다.
push 시 .collabops/template/ 하위 파일 변경이 감지되면 자동으로 등록됩니다.
템플릿 파일을 삭제하고 push하면 자동으로 등록 해제됩니다.
같은 push에서 Workflow 파일과 템플릿이 함께 변경되면, 템플릿 등록이 먼저 완료된 후 Workflow가 실행됩니다.
버전 관리
같은 이름의 템플릿을 여러 버전(v1, v2, ...)으로 동시에 유지할 수 있습니다.
Workflow에서 @version으로 특정 버전을 고정 참조할 수 있어, 템플릿 변경이 기존 Workflow에 영향을 주지 않습니다.
버전을 생략한 참조(include: "ws/repo/name")는 v1로 해석됩니다.
template.yml 구조
워크스페이스 템플릿은 Job 구성을 정의합니다. Workflow의 Job과 동일한 구조를 따릅니다.
# 템플릿 메타데이터
name: deploy-k8s
description: "Kubernetes 클러스터에 배포합니다."
# Job 구성
job:
# 기본 컨테이너 이미지
image: "bitnami/kubectl:latest"
# 환경 변수
env:
KUBECONFIG: /workspace/.kube/config
# Step 목록
steps:
- name: setup-context
run: |
kubectl config use-context $CLUSTER_NAME
- name: deploy
run: |
kubectl set image deployment/$APP_NAME \
app=$IMAGE_TAG \
-n $NAMESPACE
kubectl rollout status deployment/$APP_NAME \
-n $NAMESPACE \
--timeout=300s
# 보조 서비스 (필요 시)
services:
- dockerTemplate Schema
| Field | Required | Type | Description |
|---|---|---|---|
name | YES | string | 템플릿 이름 |
description | YES | string | 템플릿 설명 |
job | YES | object | Job 구성 |
job.image | NO | string | 기본 컨테이너 이미지 |
job.env | NO | object | Job 레벨 환경 변수 |
job.steps | YES | list | Step 목록 (최소 1개) |
job.services | NO | list | 보조 서비스 |
Step Schema
템플릿의 Step은 Workflow Step과 동일한 구조입니다.
| Field | Required | Type | Description |
|---|---|---|---|
name | YES | string | Step 이름 |
run | NO | string | 실행할 셸 명령 |
image | NO | string | Step별 컨테이너 이미지 (job.image 덮어씀) |
env | NO | object | Step 레벨 환경 변수 |
uses | NO | string | 시스템 템플릿 참조 (collabops/name@version) |
with | NO | object | 시스템 템플릿 입력 파라미터 |
템플릿의 Step에서도 시스템 템플릿을 uses로 참조할 수 있습니다. 템플릿 포함(include) 후 시스템 템플릿 확장(uses)이 순서대로 처리됩니다.
Workflow에서 사용
워크스페이스 템플릿은 Job 레벨의 include 필드로 참조합니다.
참조 형식
include: "{workspace}/{repo}/{template_name}@{version}"\{workspace\}: 워크스페이스 이름
\{repo\}: 템플릿이 등록된 저장소 이름
\{template_name\}: .collabops/template/ 하위 디렉토리 이름
\{version\}: 템플릿 버전 (예: v1, v2). 생략 시 v1
# 버전 명시
include: "my-workspace/infra-repo/deploy-k8s@v1"
# 버전 생략 → v1으로 해석
include: "my-workspace/infra-repo/deploy-k8s"
# 다른 버전 참조
include: "my-workspace/infra-repo/deploy-k8s@v2"기본 사용법
name: deploy-workflow
triggers:
push:
branches: [main]
jobs:
deploy:
# 워크스페이스 템플릿 포함 (버전 명시 권장)
include: "my-workspace/infra-repo/deploy-k8s@v1"
# Job 레벨에서 환경 변수 추가/덮어쓰기 가능
env:
CLUSTER_NAME: production
APP_NAME: my-app
NAMESPACE: production
IMAGE_TAG: my-app:latestinclude 병합 규칙
include로 템플릿을 포함할 때, Job에 직접 정의한 값이 템플릿 값보다 우선합니다.
| 필드 | 병합 규칙 |
|---|---|
image | Job 값 > 템플릿 값 |
env | Job env가 템플릿 env를 덮어씀 (동일 키) |
steps | 템플릿 Steps가 앞에 추가됨, Job Steps가 뒤에 붙음 |
services | 합집합 (중복 제거) |
needs | Job 값 유지 |
if | Job 값 유지 |
phase | Job 값 유지 |
템플릿 Steps + Job Steps 결합
# template.yml의 steps:
# - setup-context
# - deploy
jobs:
deploy:
include: "my-workspace/infra-repo/deploy-k8s@v1"
env:
CLUSTER_NAME: production
steps:
# 템플릿의 setup-context, deploy가 먼저 실행
# 아래 Step이 그 뒤에 추가됨
- name: notify
uses: "collabops/slack-notify@v1"
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK }}
message: "배포 완료"실행 순서: setup-context → deploy → notify
예제: 커스텀 배포 템플릿
1. 템플릿 파일 작성
저장소에 .collabops/template/deploy-k8s/v1/template.yml 생성:
name: deploy-k8s
description: "Kubernetes 클러스터에 배포합니다."
job:
image: "bitnami/kubectl:latest"
env:
DEPLOY_TIMEOUT: "300s"
steps:
# 소스코드 체크아웃
- name: checkout
uses: "collabops/checkout@v2"
with:
repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
# kubectl 배포
- name: deploy
run: |
kubectl set image deployment/$APP_NAME \
app=$IMAGE_TAG \
-n $NAMESPACE
kubectl rollout status deployment/$APP_NAME \
-n $NAMESPACE \
--timeout=$DEPLOY_TIMEOUT2. Workflow에서 사용
name: production-deploy
triggers:
push:
branches: [main]
jobs:
deploy-staging:
include: "my-workspace/infra-repo/deploy-k8s@v1"
phase: deploy
env:
APP_NAME: my-app
NAMESPACE: staging
IMAGE_TAG: "my-app:${{ collabops.sha }}"
deploy-production:
include: "my-workspace/infra-repo/deploy-k8s@v1"
needs: [deploy-staging]
phase: deploy
if: "collabops.ref == 'refs/heads/main'"
env:
APP_NAME: my-app
NAMESPACE: production
IMAGE_TAG: "my-app:${{ collabops.sha }}"
steps:
# 템플릿 Steps(checkout + deploy) 뒤에 알림 추가
- name: notify
uses: "collabops/slack-notify@v1"
with:
webhook-url: ${{ secrets.SLACK_WEBHOOK }}
message: "프로덕션 배포 완료: ${{ collabops.sha }}"예제: 조직 표준 빌드 템플릿 (multi-module)
조직 안에 비슷한 구조 프로젝트가 수십~수백 개 있을 때, 워크스페이스 템플릿 1개를 정의하면 모든 프로젝트가 같은 빌드 흐름을 공유할 수 있습니다. 아래는 Java/Spring multi-module (api/domain/common) 표준 빌드 시나리오입니다.
- 플랫폼 팀이 워크스페이스 어딘가의 저장소 .collabops/template/org-standard-build/v1/template.yml 에 표준 빌드 정의를 둡니다.
name: org-standard-build
description: 조직 표준 Java/Spring multi-module 빌드
runs:
image: maven:3.9-eclipse-temurin-17
steps:
- name: maven-verify
run: |
cd /workspace/source
mvn -B -ntp verify- 각 서비스 프로젝트는 본인 저장소의 pipeline.yaml 에서 이 템플릿을 include 합니다.
name: build
triggers:
push:
branches: [main]
jobs:
build:
# 워크스페이스 표준 빌드 템플릿을 그대로 include — 모든 프로젝트가 동일 흐름.
include: "<workspace>/<template-repo>/org-standard-build@v1"
# 프로젝트별 환경변수만 덮어쓴다
env:
SERVICE_NAME: "my-api"이 패턴으로 N개 프로젝트가 같은 빌드 정책을 공유합니다. 빌드 옵션(JDK 버전, Maven 옵션, 캐시 정책 등)은 템플릿에서 한 번만 바꾸면 됩니다. Marketplace 의 java-spring-boot-multimodule starter-workflow 가 같은 multi-module 빌드 흐름의 참고 예시입니다.
사내 Git 서버에서 사용 (GitLab CE / Bitbucket Server)
워크스페이스 템플릿은 git URL 이 아니라 collabops 워크스페이스의 식별자(workspace/repo/name@version)로 참조합니다. 사내 GitLab CE / Bitbucket Server / Gitea 의 저장소가 collabops 워크스페이스에 통합되어 있다면, 그 저장소의 .collabops/template/ 디렉토리가 자동으로 등록되어 같은 방식으로 사용할 수 있습니다.
jobs:
build:
# workspace template 은 collabops 워크스페이스 내부 식별자로 참조한다.
# 사내 GitLab CE / Bitbucket Server 의 저장소가 workspace 에 통합되어
# 있다면, 그 저장소의 .collabops/template/ 가 자동 등록되어 같은 방식
# 으로 include 할 수 있다.
include: "platform-team/build-templates/org-standard-build@v1"
# └ workspace slug └ repo slug └ template name @ version망분리 환경에서는 외부 마켓플레이스(GitHub Actions 같은 외부 레지스트리)의 include 가 동작하지 않습니다. workspace 안에 등록된 템플릿만 참조 가능 — 사내 git 통합이 전제입니다.
버전 관리 + 영향 프로젝트 추적
템플릿은 @v1, @v2 같은 메이저 버전으로 발행합니다. 새 버전을 발행해도 기존 프로젝트는 명시적으로 업그레이드할 때까지 이전 버전을 계속 사용 — 한꺼번에 깨지지 않습니다.
# 새 버전(v2) 발행 — 기존 프로젝트는 명시적으로 업그레이드할 때까지 v1 유지
jobs:
build:
include: "<workspace>/<template-repo>/org-standard-build@v2" # ← v1 → v2 로 변경 시점 통제어느 프로젝트가 특정 템플릿을 include 하는지 확인하려면 collabops UI 의 템플릿 상세에서 '사용처' 를 확인하거나, 워크스페이스 전체에서 include: "<workspace>/<template-repo>/<template-name>" 패턴을 검색합니다. breaking change 는 같은 버전을 덮어쓰지 말고 새 메이저 버전(v2)으로 발행하는 것이 권장됩니다.
같은 버전(v1)을 덮어쓰면 그 버전을 include 한 모든 프로젝트가 다음 빌드부터 영향을 받습니다. 호환되지 않는 변경은 반드시 새 메이저 버전으로 발행하세요.
제약 사항
워크스페이스 템플릿은 해당 워크스페이스 내에서만 사용할 수 있습니다. 다른 워크스페이스의 템플릿은 참조할 수 없습니다.
include 형식은 workspace/repo/template_name 또는 workspace/repo/template_name@version (슬래시 2개 구분)이어야 합니다.
버전을 생략하면 v1으로 해석됩니다. 명시적 버전 지정을 권장합니다.
같은 이름의 템플릿은 여러 버전을 동시에 유지할 수 있으며, 각 버전은 독립된 디렉토리(v1/, v2/, ...)에 배치합니다.
Job에 include를 설정하면 steps를 비워둘 수 있습니다 (템플릿이 Steps를 제공).