Actions Reference

How to use GitHub Actions with gaji.

Adding Actions

To use an action in your workflow, fetch its action.yml and generate TypeScript types.

gaji add actions/checkout@v5

You can also run gaji dev --watch and skip straight to the next step.

Using Actions

Import and use actions with getAction():

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

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

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

Action Reference Format

Actions are referenced using the standard GitHub format:

owner/repo@version

Examples:

• actions/checkout@v5
• 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: {
  },
})

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
  },
})

Limitations

While gaji provides type safety for property keys and types, it cannot validate string values (e.g., cache: "npn" vs cache: "npm") at compile time. Always review generated YAML to catch such typos.

Common Actions

actions/checkout

Checkout your repository:

gaji add actions/checkout@v5

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

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

// With options
.add(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");

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

actions/cache

Cache dependencies:

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

Upload build artifacts:

gaji add actions/upload-artifact@v4

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

.add(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");

.add(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")
  .steps(s => s
    .add(checkout({}))
    .add(setupBuildx({}))
    .add(buildPush({
      with: {
        context: ".",
        push: true,
        tags: "user/app:latest",
      },
    }))
  );

Local Actions

Reference local composite actions:

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

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

Make sure to create the action first. See Action.

Action Outputs

When you provide an id to an action step, gaji automatically generates typed output references:

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

For passing outputs between jobs with jobOutputs(), see Outputs.

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@v5
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