gaji 0.3.2

# Getting Started

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

## Installation

Install gaji using npm (recommended):

```bash
npm install -D gaji
```

Or using other methods:

```bash
# Using cargo
cargo install gaji

# Using pnpm
pnpm add -D gaji

# Using yarn
yarn add -D gaji
```

See [Installation](./installation.md) for more options.

## Initialize Your Project

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

```bash
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:

```bash
gaji init add actions/checkout@v5
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`:

```ts twoslash
// @filename: workflows/example.ts
// ---cut---
import { getAction, Job, Workflow } from "../generated/index.js";

// Get actions with full type safety
const checkout = getAction("actions/checkout@v5");
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

```bash
# Generate types for actions found in workflows
gaji init dev

# Build workflows to YAML
gaji init build
```

### Option 2: Watch mode (Recommended)

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

In another terminal:

```bash
# Build workflows
gaji init build
```

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

```yaml
# 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@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
```

## Recommended Development Workflow

Follow this workflow for the best experience:

1. **Start watch mode**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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

::: warning 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`](https://github.com/dodok8/gaji/blob/main/workflows/update-workflows.ts) for a working example.
:::

## Next Steps

- Learn more about [Writing Workflows](./writing-workflows.md)
- Explore the [CLI Reference](/reference/cli)
- Check out [Examples](/examples/simple-ci)