Steps

Step 스키마, 셸 명령(run), 실행 이미지(image), 템플릿 참조(uses/with)

Step은 Job 내부에서 순차적으로 실행되는 최소 단위입니다. 각 Step은 셸 명령(run) 또는 템플릿 참조(uses)로 정의합니다.

아래는 Step 실행 로그 예시입니다.

아래는 실패한 Step의 에러 로그 예시입니다.

Step Schema

Field	Required	Type	Description
`name`	YES (object form)	string	Step 이름 (1~255자, `[a-zA-Z0-9_-]`)
`run`	NO	string	실행할 셸 명령. `uses`와 동시 사용 불가
`image`	NO	string	명령을 실행할 이미지
`env`	NO	object	Step 레벨 환경 변수
`uses`	NO	string	템플릿 참조 (`\{owner\}/\{name\}@\{version\}` 형식). `run`과 동시 사용 불가
`with`	NO	object	템플릿에 전달할 입력 파라미터 (`uses` 사용 시)
`id`	NO	string	Step 출력을 참조하기 위한 식별자
`working-directory`	NO	string	작업 디렉토리 지정 (상대 경로, `..` 불가)
`timeout-minutes`	NO	int	Step 타임아웃 (분 단위, 양수, `run`에서만 지원)

Shorthand 문법

간단한 명령은 문자열로 축약할 수 있습니다.

steps:
  # Shorthand — 문자열만 작성하면 run으로 처리
  - npm install
  - npm test
  - npm run build

위 코드는 아래와 동일합니다:

steps:
  - name: npm-install
    run: npm install
  - name: npm-test
    run: npm test
  - name: npm-run-build
    run: npm run build

run (셸 명령 실행)

run은 셸 명령을 실행합니다. 단일 명령 또는 멀티라인 스크립트를 지원합니다.

각 Step은 독립된 환경에서 실행되므로, 지정한 이미지에 설치되어 있는 모든 셸 명령을 사용할 수 있습니다. npm, python, go, make, curl, wget 등 이미지에 포함된 도구라면 제한 없이 실행 가능합니다.

셸은 /bin/sh (POSIX sh)를 사용합니다. Bash 전용 문법([[ ]], 배열 등)이 필요한 경우 이미지에 Bash가 설치되어 있다면 스크립트 상단에 #!/bin/bash를 추가하세요.

단일 명령

steps:
  - name: install
    run: npm ci
    image: node:18

멀티라인 스크립트

YAML의 | (리터럴 블록)을 사용하여 여러 줄의 스크립트를 작성합니다.

steps:
  - name: build-and-test
    image: node:18
    run: |
      # 의존성 설치
      npm ci

      # 린트 검사
      npm run lint

      # 단위 테스트 실행
      npm test

      # 프로덕션 빌드
      npm run build

다양한 도구 사용 예시

이미지에 포함된 도구라면 어떤 명령이든 실행할 수 있습니다.

steps:
  # Go 빌드
  - name: build-go
    image: golang:1.22
    run: |
      go mod download
      go build -o app ./cmd/server

  # Python 테스트
  - name: test-python
    image: python:3.12
    run: |
      pip install -r requirements.txt
      pytest tests/ --cov=src

  # cURL로 API 호출
  - name: health-check
    image: alpine:3.19
    run: |
      apk add --no-cache curl
      curl -f https://api.example.com/health

  # 셸 스크립트 직접 실행
  - name: custom-script
    image: ubuntu:24.04
    run: |
      chmod +x ./scripts/deploy.sh
      ./scripts/deploy.sh

환경 변수 사용

steps:
  - name: deploy
    image: alpine:3.19
    env:
      DEPLOY_ENV: production
      API_URL: "https://api.example.com"
    run: |
      echo "Deploying to $DEPLOY_ENV"
      echo "API: $API_URL"
      ./deploy.sh

image (실행 이미지)

각 Step은 지정한 이미지 환경에서 독립적으로 실행됩니다. image로 사용할 이미지를 지정합니다.

steps:
  # Node.js 18 이미지에서 빌드
  - name: build
    run: npm run build
    image: node:18

  # Python 3.11 이미지에서 테스트
  - name: test-python
    run: pytest tests/
    image: python:3.11

  # 공식 Docker 이미지 (특정 레지스트리)
  - name: custom
    run: ./run.sh
    image: asia-northeast3-docker.pkg.dev/my-project/my-repo/my-image:latest

image를 생략하면 기본 이미지 ubuntu:24.04가 사용됩니다. 필요한 도구가 포함된 이미지를 명시적으로 지정하는 것을 권장합니다.

uses (템플릿 참조)

uses는 미리 정의된 템플릿을 참조하여 Step을 실행합니다. with로 입력 파라미터를 전달합니다.

형식

uses: "{owner}/{name}@{version}"

예제: 소스코드 체크아웃

steps:
  - name: checkout
    uses: "collabops/checkout@v2"
    with:
      # HTTPS URL을 사용하면 플랫폼이 주입한 Job Token으로 자동 인증됩니다.
      repo-url: "https://<collabops-host>/<workspace>/<repository>.git"
      # 특정 브랜치 체크아웃 (생략 시 트리거 브랜치)
      ref: main

예제: Docker 이미지 빌드 및 푸시

steps:
  - name: build-push
    uses: "collabops/docker-build-push@v1"
    with:
      # 멀티 태그 지정 (줄바꿈으로 구분)
      tags: |
        my-registry/my-app:latest
        my-registry/my-app:${{ collabops.sha }}
      # 빌드 인자 전달
      build-args: |
        NODE_ENV=production
        API_URL=https://api.example.com

예제: Slack 알림

steps:
  - name: notify
    uses: "collabops/slack-notify@v1"
    with:
      # Webhook URL (secrets에 등록)
      webhook-url: ${{ secrets.SLACK_WEBHOOK }}
      # 알림 메시지
      message: "배포 완료: ${{ collabops.ref_name }} (${{ collabops.sha }})"
      title: "Deploy Success"
      color: good

run과 uses는 상호 배타적

하나의 Step에서 run과 uses를 동시에 사용할 수 없습니다.

run과 uses는 동시에 사용할 수 없습니다. 하나의 Step에는 반드시 둘 중 하나만 지정해야 합니다.

# ✅ 올바른 사용
- name: checkout
  uses: "collabops/checkout@v2"
  with:
    repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

- name: build
  run: npm run build
  image: node:18

# ❌ 잘못된 사용 — run과 uses 동시 사용 불가
- name: invalid
  uses: "collabops/checkout@v2"
  run: npm run build

id (Step 출력 참조)

id를 지정하면 해당 Step의 출력값을 다른 Step에서 참조할 수 있습니다.

steps:
  # 1. 버전 정보를 출력에 저장
  - name: prepare-version
    id: version
    image: node:18
    run: |
      # package.json에서 버전 추출
      VERSION=$(node -p "require('./package.json').version")
      # $COLLABOPS_OUTPUT에 키=값 형태로 저장
      echo "app_version=${VERSION}" >> $COLLABOPS_OUTPUT
      echo "build_date=$(date -u +%Y%m%d)" >> $COLLABOPS_OUTPUT

  # 2. 저장된 출력값을 다른 Step에서 사용
  - name: build-image
    run: |
      echo "Building version: ${{ steps.version.outputs.app_version }}"
      echo "Build date: ${{ steps.version.outputs.build_date }}"
      docker build \
        --build-arg VERSION=${{ steps.version.outputs.app_version }} \
        -t my-app:${{ steps.version.outputs.app_version }} .

Step 이름 규칙

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

길이: 1~255자

동일 Job 내에서 중복 불가

working-directory

Step의 작업 디렉토리를 지정합니다. 상대 경로만 허용됩니다.

steps:
  - name: test-frontend
    run: npm test
    image: node:18
    working-directory: frontend

  - name: test-backend
    run: npm test
    image: node:18
    working-directory: backend

working-directory는 상대 경로여야 하며 ..를 포함할 수 없습니다.

timeout-minutes

Step 또는 Job의 타임아웃을 설정합니다. 지정 시간을 초과하면 자동으로 종료됩니다.

steps:
  - name: long-test
    run: npm run test:e2e
    image: node:18
    timeout-minutes: 30

timeout-minutes는 run에서만 지원됩니다. uses와 함께 사용할 수 없습니다.

미지원 기능

Feature	대안
Step-level `if`	Job-level `if` 또는 `run` 내부에서 셸 조건문 사용

Step-level 조건 대안

Step-level if가 지원되지 않으므로, run 내부에서 셸 조건문을 사용하여 동일한 효과를 구현할 수 있습니다.

steps:
  - name: conditional-deploy
    run: |
      # 셸 조건문으로 Step-level 조건 구현
      if [ "$DEPLOY_ENV" = "production" ]; then
        echo "Deploying to production..."
        ./deploy-prod.sh
      else
        echo "Skipping production deploy"
      fi
    env:
      DEPLOY_ENV: ${{ vars.DEPLOY_ENV }}

Steps

목차