빠른 시작

이 가이드는 초기 설정과 첫 워크플로우 작성을 다룹니다.

설치

Node 계열 프로젝트는 자신의 패키지 매니저에 맞게, 다른 언어나 환경을 사용하는 경우 cargo나 npm install --global을 사용해서 설치해주세요.

npm install -D gaji

# pnpm 사용
pnpm add -D gaji

# yarn 사용
yarn add -D gaji

# cargo 사용
cargo install gaji

더 많은 옵션은 설치를 참조하세요.

프로젝트 초기화

init 명령을 실행하여 프로젝트에서 gaji 설정:

gaji init init

이것은:

• TypeScript 워크플로우를 위한 workflows/ 디렉토리 생성
• 자동 생성된 타입을 위한 generated/ 디렉토리 생성
• 컴파일된 YAML을 위한 .github/workflows/ 디렉토리 생성
• 예제 워크플로우 생성 (선택 사항)
• .gitignore 업데이트

액션 추가

사용하려는 GitHub Actions 추가:

gaji init add actions/checkout@v5
gaji init add actions/setup-node@v4

이것은:

• GitHub에서 action.yml 가져오기
• TypeScript 타입 생성
• generated/ 디렉토리에 저장

첫 번째 워크플로우 작성

workflows/ci.ts 생성:

import { getAction, Job, Workflow } from "../generated/index.js";

// 완전한 타입 안전성으로 액션 가져오기
const checkout = getAction("actions/checkout@v5");
const setupNode = getAction("actions/setup-node@v4");

// 콜백 빌더 API로 워크플로우 생성
new Workflow({
  name: "CI",
  on: {
    push: { branches: ["main"] },
    pull_request: { branches: ["main"] },
  },
}).jobs(j => j
  .add("build",
    new Job("ubuntu-latest")
      .steps(s => s
        .add(checkout({ name: "Checkout code" }))
        .add(setupNode({
          name: "Setup Node.js",
          with: { "node-version": "20" },  // ✅ 자동완성 사용 가능!
        }))
        .add({ name: "Install dependencies", run: "npm ci" })
        .add({ name: "Run tests", run: "npm test" })
      )
  )
).build("ci");

타입 생성 및 빌드

방법 1: 일회성 빌드

# 워크플로우에서 찾은 액션에 대한 타입 생성
gaji init dev

# 워크플로우를 YAML로 빌드
gaji init build

방법 2: 감시 모드 (권장)

# 감시 모드 시작 - 새 액션을 추가하면 자동으로 타입 생성
gaji init dev --watch

다른 터미널에서:

# 워크플로우 빌드
gaji init build

생성된 YAML은 .github/workflows/ci.yml에 있습니다:

# gaji에 의해 자동 생성됨 - 수동으로 편집하지 마세요
name: CI
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

권장 개발 워크플로우

최상의 경험을 위해 다음 워크플로우를 따르세요:

1. 감시 모드 시작:

   gaji init dev --watch

   터미널에서 계속 실행 상태로 두세요.

2. 워크플로우 편집:

   • 에디터에서 workflows/ci.ts 열기
   • 단계 추가 또는 수정
   • getAction()으로 새 액션을 추가하면 gaji가 자동으로 타입을 가져와 생성합니다

3. YAML로 빌드:

   gaji init build

4. 생성된 YAML 검토:

   • .github/workflows/ci.yml 열기
   • 명령이 올바른지 확인
   • 모든 필수 필드가 있는지 확인

5. 두 파일 모두 커밋:

   git add workflows/ci.ts .github/workflows/ci.yml
   git commit -m "CI 워크플로우 추가"

왜 TypeScript와 YAML 모두 커밋해야 하나요?

TypeScript 소스와 생성된 YAML을 모두 커밋해야 합니다:

• TypeScript (workflows/*.ts): 소스 코드, 버전 관리
• YAML (.github/workflows/*.yml): GitHub Actions가 실행하는 파일

중요

push 시 TypeScript를 YAML로 자동 컴파일하는 워크플로우를 만들 수 있지만, 권장하지 않습니다. 항상 로컬에서 컴파일하고 검토한 후 커밋하세요.

GitHub Actions 트리거의 복잡성(예: paths 필터링, PAT 토큰 관리, 무한 루프 방지)을 감수할 의향이 있다면, 자동 컴파일 워크플로우를 구성할 수 있습니다. 동작하는 예시는 workflows/update-workflows.ts를 참고하세요.

다음 단계

• 워크플로우 작성에 대해 자세히 알아보기
• CLI 레퍼런스 살펴보기
• 예제 확인하기