Jobs

Job 스키마, DAG 의존성(needs), 조건부 실행(if), 보조 서비스(services)

jobs는 Workflow에서 실행할 작업 집합입니다. 각 Job은 기본적으로 병렬 실행되며, needs를 통해 순서를 제어합니다.

Job Schema

jobs:
  # Job ID: 고유 식별자 (영문, 숫자, _, - 허용)
  build:
    # 의존 Job — build는 test가 완료된 후 실행
    needs: [test]

    # 조건부 실행 — 이전 Job이 성공했을 때만 실행
    if: "success()"

    # 메타데이터 — 대시보드에서 단계 구분용
    phase: build

    # Job 레벨 환경 변수
    env:
      NODE_ENV: production

    # 보조 서비스 (예: Docker)
    services:
      - docker

    # Step 목록 (최소 1개 필수)
    steps:
      - name: compile
        run: npm run build
        image: node:18

Job 필드

Field	Required	Type	Description
`steps`	YES	list	Step 목록 (`include` 사용 시 생략 가능)
`include`	NO	string	워크스페이스 템플릿 참조 (`workspace/repo/name` 형식)
`needs`	NO	list[string]	의존 Job ID 목록
`if`	NO	string	조건부 실행 표현식
`phase`	NO	string	메타데이터. `source`, `deps`, `build`, `test`, `security`, `deploy` 중 택1
`env`	NO	object	Job 레벨 환경 변수
`services`	NO	list	보조 서비스 목록
`timeout-minutes`	NO	int	Job 타임아웃 (분 단위, 양수)

Job ID 규칙

허용 문자: [a-zA-Z0-9_-]

최대 255자

대소문자 구분 없음 (Build와 build는 같은 ID)

공백, 특수문자 사용 불가

Workflow 내에서 고유해야 함

needs (DAG 의존성)

needs로 Job 간 실행 순서를 정의합니다. 지정하지 않은 Job은 병렬로 실행됩니다.

순차 실행

jobs:
  # 1단계: lint (의존 없음 → 즉시 실행)
  lint:
    steps:
      - name: eslint
        run: npm run lint
        image: node:18

  # 2단계: test (lint 완료 후 실행)
  test:
    needs: [lint]
    steps:
      - name: unit-test
        run: npm test
        image: node:18

  # 3단계: deploy (test 완료 후 실행)
  deploy:
    needs: [test]
    steps:
      - name: deploy
        run: ./deploy.sh

병렬 + 합류 (Fan-out / Fan-in)

jobs:
  # 1단계: checkout (공통)
  checkout:
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

  # 2단계: lint와 test가 병렬 실행
  lint:
    needs: [checkout]
    steps:
      - name: eslint
        run: npm run lint
        image: node:18

  test:
    needs: [checkout]
    steps:
      - name: unit-test
        run: npm test
        image: node:18

  # 3단계: lint와 test 모두 완료 후 deploy
  deploy:
    needs: [lint, test]
    steps:
      - name: deploy
        run: ./deploy.sh

예시 Pipeline DAG

DAG 규칙

순환 의존성(Cycle) 허용되지 않음 — a → b → a 불가

자기 자신 참조 불가 — needs: [self] 불가

존재하지 않는 Job ID 참조 불가

needs에 지정된 모든 Job이 성공해야 다음 Job이 실행됨

Conditional Execution (if)

if는 Job 단위에서만 지원됩니다. Step 레벨에서는 사용할 수 없습니다.

Status Functions

jobs:
  deploy:
    needs: [build]
    # 이전 Job(build)이 성공했을 때만 실행 (기본 동작)
    if: "success()"
    steps: [...]

  cleanup:
    needs: [build]
    # 성공/실패 관계없이 항상 실행
    if: "always()"
    steps: [...]

  rollback:
    needs: [deploy]
    # deploy Job이 실패했을 때만 실행
    if: "failure()"
    steps: [...]

Function	Description
`success()`	이전 Job이 모두 성공했을 때 (기본 동작)
`failure()`	이전 Job(`needs`에 지정된)이 실패했을 때
`always()`	이전 Job의 성공/실패와 관계없이 항상 실행

failure()는 모니터링할 Job을 지정하기 위해 needs가 필수입니다. 의존 Job 중 하나라도 실패하면 실행됩니다.

cancelled()는 현재 미지원입니다.

비교 연산자

jobs:
  deploy:
    # main 브랜치 push일 때만 배포
    if: "collabops.ref == 'refs/heads/main'"
    steps: [...]

  skip-cr:
    # change_request가 아닐 때만 실행
    if: "collabops.event_name != 'change_request'"
    steps: [...]

지원 연산자: ==, !=

String Functions

Function	Description	Example
`contains(string, substring)`	부분 문자열 포함 여부	`contains(collabops.ref, 'release')`
`startsWith(string, prefix)`	접두사 일치 여부	`startsWith(collabops.ref_name, 'feature/')`
`endsWith(string, suffix)`	접미사 일치 여부	`endsWith(collabops.ref_name, '-hotfix')`

jobs:
  release:
    # 브랜치 이름에 'release'가 포함된 경우에만 실행
    if: "contains(collabops.ref, 'release')"
    steps: [...]

  feature-test:
    # feature/ 브랜치에서만 추가 테스트 실행
    if: "startsWith(collabops.ref_name, 'feature/')"
    steps: [...]

Logical Operators

&& (AND), || (OR), ! (NOT) 및 괄호 그룹을 지원합니다.

jobs:
  deploy-prod:
    # main 브랜치 push이고 이전 Job이 성공했을 때만 배포
    if: "success() && collabops.ref == 'refs/heads/main' && collabops.event_name == 'push'"
    steps: [...]

  deploy-staging:
    # main 또는 develop 브랜치 push일 때 스테이징 배포
    if: "(collabops.ref == 'refs/heads/main' || collabops.ref == 'refs/heads/develop') && collabops.event_name == 'push'"
    steps: [...]

미지원 기능

❌ cancelled() — 향후 지원 예정

❌ Step-level if — Job-level if 또는 run 내부 스크립트로 대체

services

Job 실행 시 함께 구동되는 보조 서비스를 선언합니다. 현재 Docker 서비스를 지원합니다.

Sugar Syntax

jobs:
  build:
    # Docker 서비스를 간단히 선언
    services:
      - docker
    steps:
      - name: build-image
        run: docker build -t my-app .

services에 docker를 선언하면 Docker 서비스가 자동으로 활성화됩니다. docker-build-push 템플릿은 내부적으로 이를 자동 설정합니다.

phase

phase는 대시보드에서 Job의 단계를 시각적으로 구분하기 위한 메타데이터입니다.

phase는 순수한 메타데이터로, 실행 동작에는 영향을 주지 않습니다. 대시보드에서 시각적 구분 용도로만 사용됩니다.

Phase	용도
`source`	소스코드 체크아웃
`deps`	의존성 설치
`build`	빌드
`test`	테스트, 린트
`security`	보안 스캔
`deploy`	배포

jobs:
  lint:
    phase: test        # 대시보드에서 "테스트" 단계로 표시
    steps: [...]

  build:
    phase: build       # 대시보드에서 "빌드" 단계로 표시
    steps: [...]

  deploy:
    phase: deploy      # 대시보드에서 "배포" 단계로 표시
    steps: [...]

목차