액션 레퍼런스

gaji와 함께 GitHub Actions를 사용하는 방법입니다.

액션 추가

워크플로우에서 액션을 사용하려면 액션의 action.yml을 가져와 TypeScript 타입을 생성합니다.

gaji add actions/checkout@v5

gaji dev --watch 를 실행한 다음, 바로 다음 스텝으로 넘어가도 됩니다.

액션 사용

getAction()으로 액션을 가져와 사용하세요:

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

const checkout = getAction("actions/checkout@v5");
const setupNode = getAction("actions/setup-node@v4");

// 워크플로우에서 사용
const job = new Job("ubuntu-latest")
  .steps(s => s
    .add(checkout({}))
    .add(setupNode({
      with: {
        "node-version": "20",  // ✅ 타입 안전!
      },
    }))
  );

액션 참조 형식

액션은 표준 GitHub 형식으로 참조합니다:

owner/repo@version

예시:

• actions/checkout@v5
• actions/setup-node@v4
• docker/setup-buildx-action@v3
• softprops/action-gh-release@v1

버전

다음을 사용할 수 있습니다:

• 태그: @v4, @v1.2.3
• 브랜치: @main, @develop
• 커밋: @a1b2c3d

타입 안전성

gaji는 액션의 action.yml에서 타입을 생성하여 다음을 제공합니다:

자동완성

에디터가 사용 가능한 모든 입력을 표시합니다:

setupNode({
  with: {
  },
})

타입 체크

잘못된 입력은 즉시 잡힙니다:

// ❌ 타입 오류 - 알 수 없는 속성
setupNode({
  with: {
    "node-versoin": "20",  // 오타!
  },
})

// ✅ 올바름
setupNode({
  with: {
    "node-version": "20",
  },
})

문서

입력 위에 마우스를 올리면 설명과 기본값을 볼 수 있습니다.

setupNode({
  with: {
    "node-version": "20",  // 📝 호버 시 설명 표시
  },
})

제한사항

gaji는 속성 키와 타입에 대한 타입 안전성을 제공하지만, 문자열 값(예: cache: "npn" vs cache: "npm")은 컴파일 시점에 검증할 수 없습니다. 이러한 오타를 잡으려면 항상 생성된 YAML을 검토하세요.

일반 액션

actions/checkout

저장소 체크아웃:

gaji add actions/checkout@v5

const checkout = getAction("actions/checkout@v5");

// 기본 사용
.add(checkout({}))

// 옵션과 함께
.add(checkout({
  with: {
    repository: "owner/repo",
    ref: "main",
    token: "${{ secrets.GITHUB_TOKEN }}",
    "fetch-depth": 0,
  },
}))

actions/setup-node

Node.js 설정:

gaji add actions/setup-node@v4

const setupNode = getAction("actions/setup-node@v4");

.add(setupNode({
  with: {
    "node-version": "20",
    cache: "npm",
  },
}))

actions/cache

의존성 캐시:

gaji add actions/cache@v4

const cache = getAction("actions/cache@v4");

.add(cache({
  with: {
    path: "node_modules",
    key: "${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}",
    "restore-keys": "${{ runner.os }}-node-",
  },
}))

actions/upload-artifact

빌드 아티팩트 업로드:

gaji add actions/upload-artifact@v4

const uploadArtifact = getAction("actions/upload-artifact@v4");

.add(uploadArtifact({
  with: {
    name: "build-output",
    path: "dist/",
  },
}))

actions/download-artifact

아티팩트 다운로드:

gaji add actions/download-artifact@v4

const downloadArtifact = getAction("actions/download-artifact@v4");

.add(downloadArtifact({
  with: {
    name: "build-output",
    path: "dist/",
  },
}))

서드파티 액션

gaji는 모든 GitHub Action과 호환됩니다:

# Docker
gaji add docker/setup-buildx-action@v3
gaji add docker/build-push-action@v5

# Rust
gaji add dtolnay/rust-toolchain@stable

# GitHub
gaji add softprops/action-gh-release@v1

예제:

const setupBuildx = getAction("docker/setup-buildx-action@v3");
const buildPush = getAction("docker/build-push-action@v5");

const job = new Job("ubuntu-latest")
  .steps(s => s
    .add(checkout({}))
    .add(setupBuildx({}))
    .add(buildPush({
      with: {
        context: ".",
        push: true,
        tags: "user/app:latest",
      },
    }))
  );

로컬 액션

로컬 컴포지트 액션 참조:

const myAction = getAction("./my-action");

.add(myAction({
  with: {
    input: "value",
  },
}))

먼저 액션을 생성해야 합니다. Action을 참조하세요.

액션 출력

액션 스텝에 id를 제공하면, gaji는 타입이 지정된 출력 참조를 자동으로 생성합니다:

const step = checkout({ id: "my-checkout" });
step.outputs.ref     // "${{ steps.my-checkout.outputs.ref }}"
step.outputs.commit  // "${{ steps.my-checkout.outputs.commit }}"

jobOutputs()를 사용한 Job 간 출력 전달에 대해서는 출력을 참조하세요.

액션 업데이트

액션 타입을 업데이트하려면 캐시를 지우고 재생성하세요.

# 캐시 정리 후 재생성
gaji clean --cache
gaji dev

문제 해결

"Action not found"

액션을 추가했는지 확인하세요.

gaji add actions/checkout@v5
gaji dev

"Types not updated"

캐시를 지우고 재생성하세요.

gaji clean --cache
gaji dev

"Rate limit exceeded"

GitHub 토큰을 설정하세요.

export GITHUB_TOKEN=ghp_your_token_here
gaji dev

다음 단계

• 예제 보기
• CLI 레퍼런스 확인