Getting Started

This guide will help you get started with gaji in just a few minutes.

Installation

Install gaji using npm (recommended):

npm install -D gaji

Or using other methods:

# Using cargo
cargo install gaji

# Using pnpm
pnpm add -D gaji

# Using yarn
yarn add -D gaji

See Installation for more options.

Initialize Your Project

Run the init command to set up gaji in your project:

gaji init init

This will:

• Create workflows/ directory for your TypeScript workflows
• Create generated/ directory for auto-generated types
• Create .github/workflows/ directory for compiled YAML
• Add example workflow (optional)
• Update .gitignore

Add Actions

Add GitHub Actions you want to use:

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

This will:

• Fetch action.yml from GitHub
• Generate TypeScript types
• Save to generated/ directory

Write Your First Workflow

Create workflows/ci.ts:

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

// Get actions with full type safety
const checkout = getAction("actions/checkout@v4");
const setupNode = getAction("actions/setup-node@v4");

// Define the build job
const build = new Job("ubuntu-latest")
  .addStep(checkout({
    name: "Checkout code",
  }))
  .addStep(setupNode({
    name: "Setup Node.js",
    with: {
      "node-version": "20",  // ✅ Autocomplete available!
    },
  }))
  .addStep({
    name: "Install dependencies",
    run: "npm ci",
  })
  .addStep({
    name: "Run tests",
    run: "npm test",
  });

// Create the workflow
const workflow = new Workflow({
  name: "CI",
  on: {
    push: { branches: ["main"] },
    pull_request: { branches: ["main"] },
  },
}).addJob("build", build);

// Build the YAML file
workflow.build("ci");

Generate Types and Build

Option 1: One-time build

# Generate types for actions found in workflows
gaji init dev

# Build workflows to YAML
gaji init build

Option 2: Watch mode (Recommended)

# Start watch mode - auto-generates types when you add new actions
gaji init dev --watch

In another terminal:

# Build workflows
gaji init build

The generated YAML will be in .github/workflows/ci.yml:

# Auto-generated by gaji - Do not edit manually
name: CI
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - 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

Recommended Development Workflow

Follow this workflow for the best experience:

1. Start watch mode:

   gaji init dev --watch

   Leave this running in a terminal.

2. Edit your workflow:

   • Open workflows/ci.ts in your editor
   • Add or modify steps
   • When you add a new action with getAction(), gaji automatically fetches and generates types

3. Build to YAML:

   gaji init build

4. Review the generated YAML:

   • Open .github/workflows/ci.yml
   • Verify that commands are correct
   • Check that all required fields are present

5. Commit both files:

   git add workflows/ci.ts .github/workflows/ci.yml
   git commit -m "Add CI workflow"

Why Commit Both TypeScript and YAML?

You should commit both the TypeScript source and the generated YAML:

• TypeScript (workflows/*.ts): Source of truth, version controlled
• YAML (.github/workflows/*.yml): What GitHub Actions executes

Important: Auto-compilation

Important

While you can create a workflow that auto-compiles TypeScript to YAML on push, this is NOT recommended. Always compile and review locally before committing.

If you're willing to handle the complexity of GitHub Actions triggers (e.g., filtering paths, managing PAT tokens, avoiding infinite loops), you can set up an auto-compilation workflow. See workflows/update-workflows.ts for a working example.

Next Steps

• Learn more about Writing Workflows
• Explore the CLI Reference
• Check out Examples