Actions & Composites

Composites are functions that return typed GitHub Actions steps, jobs and workflows, from single-action wrappers to multi-job pipelines.

Action wrappers

Checkout

Wraps actions/checkout@v7. Clones the repository.

import { Checkout } from "@intentius/chant-lexicon-github";

Checkout({}).step                              // Default checkout
Checkout({ fetchDepth: 0 }).step               // Full history
Checkout({ ref: "develop" }).step              // Specific branch
Checkout({ submodules: "recursive" }).step     // With submodules
Checkout({ pin: "sha" }).step                  // Pinned to a commit SHA

Props: ref?, repository?, fetchDepth?, token?, submodules?, sshKey?, pin?

pin: "sha" emits actions/checkout@<sha> # v7.0.1, the commit the lexicon’s pin table records for the release, with the version as a YAML comment. GHA021, GHA029 and GHA059 accept that form. The table is ACTION_PINS, exported from the package, and the same pin prop is on SetupNode.

SetupNode

Wraps actions/setup-node@v7. Installs Node.js with optional dependency caching.

import { SetupNode } from "@intentius/chant-lexicon-github";

SetupNode({ nodeVersion: "22" }).step              // Node 22
SetupNode({ nodeVersion: "22", cache: "npm" }).step // With npm cache
SetupNode({ nodeVersion: "20", cache: "pnpm" }).step // pnpm cache
SetupNode({ nodeVersion: "22", pin: "sha" }).step  // Pinned to a commit SHA

Props: nodeVersion?, cache? ("npm" | "pnpm" | "yarn"), registryUrl?, pin?

SetupGo

Wraps actions/setup-go@v5. Installs Go.

import { SetupGo } from "@intentius/chant-lexicon-github";

SetupGo({ goVersion: "1.22" }).step
SetupGo({ goVersion: "stable" }).step

Props: goVersion?, cache?

SetupPython

Wraps actions/setup-python@v5. Installs Python.

import { SetupPython } from "@intentius/chant-lexicon-github";

SetupPython({ pythonVersion: "3.12" }).step
SetupPython({ pythonVersion: "3.12", cache: "pip" }).step

Props: pythonVersion?, cache? ("pip" | "pipenv" | "poetry"), architecture?

CacheAction

Wraps actions/cache@v4. Caches files between workflow runs.

import { CacheAction } from "@intentius/chant-lexicon-github";

CacheAction({
  path: "~/.npm",
  key: "npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}",
  restoreKeys: ["npm-${{ runner.os }}-"],
}).step

Props: path, key, restoreKeys?

UploadArtifact

Wraps actions/upload-artifact@v4. Uploads files as workflow artifacts.

import { UploadArtifact } from "@intentius/chant-lexicon-github";

UploadArtifact({
  name: "build-output",
  path: "dist/",
  retentionDays: 7,
}).step

Props: name, path, retentionDays?, ifNoFilesFound?

DownloadArtifact

Wraps actions/download-artifact@v4. Downloads previously uploaded artifacts.

import { DownloadArtifact } from "@intentius/chant-lexicon-github";

DownloadArtifact({
  name: "build-output",
  path: "dist/",
}).step

Props: name, path?

CI pipeline composites

NodeCI

Returns a CI Workflow (push + PR on main) and a Job with checkout, setup-node, install, build, and test steps.

import { NodeCI } from "@intentius/chant-lexicon-github";

// Default: Node 22, npm, "build" + "test" scripts
const { workflow, job } = NodeCI({});

// Customized
const { workflow: w, job: j } = NodeCI({
  nodeVersion: "20",
  packageManager: "pnpm",
  buildScript: "compile",
  testScript: "test:ci",
});

Props: nodeVersion?, packageManager? ("npm" | "pnpm" | "yarn" | "bun"), buildScript?, testScript?, installCommand?

Export the returned workflow and job directly:

const ci = NodeCI({ nodeVersion: "22", packageManager: "npm" });
export const workflow = ci.workflow;
export const build = ci.job;

NodePipeline

A Node pipeline with separate build and test jobs that pass artifacts. The build job uploads artifacts; the test job downloads them and runs tests with needs: ["build"].

import { NodePipeline } from "@intentius/chant-lexicon-github";

const { workflow, buildJob, testJob } = NodePipeline({
  nodeVersion: "22",
  packageManager: "pnpm",
  buildScript: "build",
  testScript: "test:ci",
  buildArtifactPaths: ["dist/", "lib/"],
});

Props: nodeVersion?, packageManager?, buildScript?, testScript?, installCommand?, buildArtifactPaths?, artifactName?, artifactRetentionDays?, runsOn?

Pipeline presets

import { BunPipeline, PnpmPipeline, YarnPipeline } from "@intentius/chant-lexicon-github";

const bun = BunPipeline({});         // packageManager: "bun", uses oven-sh/setup-bun@v2
const pnpm = PnpmPipeline({});       // packageManager: "pnpm"
const yarn = YarnPipeline({});       // packageManager: "yarn"

PythonCI

Python CI with test and optional lint jobs. Supports pip and Poetry workflows.

import { PythonCI } from "@intentius/chant-lexicon-github";

const { workflow, testJob, lintJob } = PythonCI({
  pythonVersion: "3.12",
  testCommand: "pytest --junitxml=report.xml --cov",
  lintCommand: "ruff check .",
});

// Omit lint job
const { workflow: w, testJob: t } = PythonCI({ lintCommand: null });

// Poetry mode
const poetry = PythonCI({ usePoetry: true });

Props: pythonVersion?, testCommand?, lintCommand? (null to omit), requirementsFile?, usePoetry?, runsOn?

DockerBuild

Docker build and push using official Docker actions (login, setup-buildx, metadata, build-push). Configured for GitHub Container Registry by default.

import { DockerBuild } from "@intentius/chant-lexicon-github";

const { workflow, job } = DockerBuild({
  registry: "ghcr.io",
  imageName: "ghcr.io/my-org/my-app",
  dockerfile: "Dockerfile",
  platforms: ["linux/amd64", "linux/arm64"],
});

Props: tag?, dockerfile?, context?, registry?, imageName?, tagLatest?, buildArgs?, push?, platforms?, runsOn?

DeployEnvironment

Deploy and cleanup job pair using GitHub Environments with concurrency control.

import { DeployEnvironment } from "@intentius/chant-lexicon-github";

const { deployJob, cleanupJob } = DeployEnvironment({
  name: "staging",
  deployScript: ["npm run build", "npm run deploy"],
  cleanupScript: "npm run teardown",
  url: "https://staging.example.com",
});

Props: name (required), deployScript (required), cleanupScript?, url?, concurrencyGroup?, cancelInProgress?, runsOn?

GoCI

Go CI with build, test, and optional lint jobs. Uses golangci-lint-action for linting.

import { GoCI } from "@intentius/chant-lexicon-github";

const { workflow, buildJob, testJob, lintJob } = GoCI({
  goVersion: "1.22",
  buildCommand: "go build ./...",
  testCommand: "go test ./... -v -race",
});

// Without lint
const noLint = GoCI({ lintCommand: null });

Props: goVersion?, testCommand?, buildCommand?, lintCommand? (null to omit), runsOn?

Combining composites in a job

Composites return objects with a .step property. Combine them freely in any job:

import {
  Job, Step,
  Checkout, SetupNode, CacheAction, UploadArtifact,
} from "@intentius/chant-lexicon-github";

export const build = new Job({
  "runs-on": "ubuntu-latest",
  timeoutMinutes: 15,
  steps: [
    Checkout({}).step,
    SetupNode({ nodeVersion: "22", cache: "npm" }).step,
    new Step({ name: "Install", run: "npm ci" }),
    new Step({ name: "Build", run: "npm run build" }),
    UploadArtifact({ name: "dist", path: "dist/" }).step,
  ],
});

Using raw action references

You can always use raw uses: strings for actions without a typed composite:

import { Step } from "@intentius/chant-lexicon-github";

new Step({
  name: "Deploy to Pages",
  uses: "actions/deploy-pages@v4",
  with: { artifact_name: "github-pages" },
});

The GHA001 lint rule will suggest a typed composite if one is available.