Actions Reference

How to use GitHub Actions with gaji.

Adding Actions

To use an action in your workflows, first add it:

gaji add actions/checkout@v4

This fetches the action's action.yml and generates TypeScript types.

Using Actions

Import and use actions with getAction():

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

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

// Use in workflow
const job = new Job("ubuntu-latest")
  .addStep(checkout({}))
  .addStep(setupNode({
    with: {
      "node-version": "20",  // ✅ Type-safe!
    },
  }));

Action Reference Format

Actions are referenced using the standard GitHub format:

owner/repo@version

Examples:

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

Versions

You can use:

• Tags: @v4, @v1.2.3
• Branches: @main, @develop
• Commits: @a1b2c3d

Type Safety

gaji generates types from the action's action.yml, giving you:

Autocomplete

Your editor shows all available inputs:

setupNode({
  with: {
    // Press Ctrl+Space to see all options:
    // - node-version
    // - cache
    // - cache-dependency-path
    // - architecture
    // etc.
  },
})

Type Checking

Invalid inputs are caught immediately:

// ❌ Type error - "cache" expects "npm" | "yarn" | "pnpm"
setupNode({
  with: {
    cache: "npn",  // Typo!
  },
})

// ✅ Correct
setupNode({
  with: {
    cache: "npm",
  },
})

Documentation

Hover over inputs to see descriptions and default values:

setupNode({
  with: {
    "node-version": "20",  // 📝 Description appears on hover
  },
})

Common Actions

actions/checkout

Checkout your repository:

gaji add actions/checkout@v4

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

// Basic usage
.addStep(checkout({}))

// With options
.addStep(checkout({
  with: {
    repository: "owner/repo",
    ref: "main",
    token: "${{ secrets.GITHUB_TOKEN }}",
    "fetch-depth": 0,
  },
}))

actions/setup-node

Setup Node.js:

gaji add actions/setup-node@v4

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

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

actions/cache

Cache dependencies:

gaji add actions/cache@v4

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

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

actions/upload-artifact

Upload build artifacts:

gaji add actions/upload-artifact@v4

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

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

actions/download-artifact

Download artifacts:

gaji add actions/download-artifact@v4

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

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

Third-Party Actions

gaji works with any 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

Example:

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

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

Local Actions

Reference local composite actions:

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

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

Make sure to create the action first. See CompositeAction.

Action Outputs

Use action outputs in subsequent steps:

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

.addStep(setupNode({
  id: "setup-node",
  with: {
    "node-version": "20",
  },
}))
.addStep({
  run: "echo Node path: ${{ steps.setup-node.outputs.node-path }}",
})

Updating Actions

To update action types, clear the cache and regenerate:

# Clear cache and regenerate
gaji clean --cache
gaji dev

Troubleshooting

"Action not found"

Make sure you've added the action:

gaji add actions/checkout@v4
gaji dev

"Types not updated"

Clear cache and regenerate:

gaji clean
gaji dev

"Rate limit exceeded"

Set a GitHub token:

export GITHUB_TOKEN=ghp_your_token_here
gaji dev

Next Steps

• See Examples
• Check the CLI Reference