Serialization

The GitHub Actions lexicon serializes resources into .github/workflows/*.yml YAML files. Keys use kebab-case for job properties and snake_case for trigger event names.

Building

Run chant build to produce workflow YAML from your declarations:

chant build src/ --output .github/workflows/ci.yml
# Or build all workflow files
chant build

The generated file includes:

• name: — workflow display name
• on: — trigger events (push, pull_request, schedule, workflow_dispatch, etc.)
• permissions: — workflow-level GITHUB_TOKEN permissions
• jobs: — job definitions with kebab-case keys

Key conversions

Chant (TypeScript)	YAML output	Rule
export const buildApp = new Job({...})	jobs: build-app:	Export name → kebab-case job key
"runs-on": "ubuntu-latest"	runs-on: ubuntu-latest	Property names match GitHub spec
timeoutMinutes: 15	timeout-minutes: 15	camelCase → kebab-case for job properties
new Step({ uses: "actions/checkout@v7" })	- uses: actions/checkout@v7	Steps serialize as sequence entries

Comments

Workflow, Job and Step take a comment. It is not a workflow key: the serializer writes it as # lines, one per line of the string, so the reasons a hand-written workflow keeps as YAML comments stay in the file a reader opens on GitHub. A workflow’s comment is the file’s header, above name:; a job’s goes above its key and a step’s above its - . The Forgejo lexicon renders the same declarations, so its files carry them too.

export const publish = new Workflow({
  comment: "Publishes on a version tag.\nKeep the file name: npm's trusted publisher names it.",
  name: "Publish",
  on: { push: { tags: ["v*"] } },
  jobs: {
    publish: new Job({
      "runs-on": "ubuntu-latest",
      steps: [new Step({ comment: "The registry times out now and then; retry once.", run: "npm publish || npm publish" })],
    }),
  },
});

# Publishes on a version tag.
# Keep the file name: npm's trusted publisher names it.

name: Publish

on:
  push:
    tags:
      - v*

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      # The registry times out now and then; retry once.
      - run: npm publish || npm publish

Validating locally

The output is standard GitHub Actions YAML. Validate locally with act or push to GitHub:

# Using act for local testing
act -W .github/workflows/ci.yml

# Using GitHub's workflow validation (requires push)
git add .github/workflows/ci.yml
git push

Compatibility

The output is compatible with:

• GitHub Actions (any GitHub.com or GitHub Enterprise Server)
• act local runner
• VS Code GitHub Actions extension
• Any tool that processes .github/workflows/*.yml files