NimbaseBot

A composite GitHub Action that regenerates and releases Nim HTTP client packages built with the Nimbase CLI.

Whenever a repo's OpenAPI specs change (or on a schedule / manual dispatch), the bot:

1. installs the Nim toolchain and the Nimbase CLI,
2. regenerates the client(s) from the specs,
3. determines the next version from the latest git tag (starting at 0.1.0 when there are none) and writes it into the root *.nimble,
4. commits, pushes, tags (vX.Y.Z) and creates a GitHub release.

Testing is left to each repo's own test workflow — it re-runs after the bot via a workflow_run trigger on the nimbase workflow (see Setup). No BOT_TOKEN secret is needed.

Settings

The Nimbase CLI can also take additional generator settings from a nimbase.oapi.config.yaml file. It is optional and lives at the repo root, next to the *.nimble file — nimbase oapi.gen auto-loads it from the working directory, so the bot picks it up automatically. Repos that commit it should add nimbase.oapi.config.yaml to the workflow trigger paths (see below).

Supported settings: description, author, license, licenseUrl, url, version, id, baseUri, source, repo, generator, skipComponentSchemas, verbose, generateTests, prefilters.routePrefix, prefilters.stripPrefixModule. See the Nimbase README for details.

Usage

Add .github/workflows/nimbase.yml to each client repo. See examples/nimbase.yml for a full annotated copy.

name: nimbase
on:
  push:
    branches: [main]
    paths: ['specs/**', '.github/workflows/nimbase.yml']
  workflow_dispatch:
concurrency:
  group: nimbase
  cancel-in-progress: false
jobs:
  regenerate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: nimbase/nimbase-bot@v1
        with:
          token: ${{ secrets.BOT_TOKEN }}   # bot PAT, required to re-trigger test.yml
          gen-command: scripts/gen.sh   # optional, see below

Inputs

Input	Default	Description
nim-version	stable	Nim version for jiro4989/setup-nim-action
nimbase-ref	#head	Nimbase git ref to install, e.g. #head or #v0.2.0
gen-command	(empty)	Command to regenerate clients. Empty → default loop over specs-dir
specs-dir	specs	Spec directory for the default loop
output-dir	.	Destination for the default loop
config	(empty)	nimbase.oapi.config.yaml passed to nimbase oapi.gen
spec-source	(empty)	Spec to monitor on scheduled runs: a URL or an apis.guru id (e.g. hetzner.cloud). Compared via nimbase oapi.diff against spec-file; unchanged → generation/release skipped
spec-file	(empty)	Committed spec baseline compared against spec-source (e.g. specs/hetzner.cloud.json); regeneration should update it (via --save-spec:<path>)
bump	patch	Version written to the root *.nimble: bump from the latest git tag (patch | minor | major) or none to keep the last tag; starts at 0.1.0 when there are no tags
token	GITHUB_TOKEN (github.token)	Token for push/tag/release. No secret needed; dependent workflows re-run via workflow_run
git-user / git-email	nimbase-bot[bot] / …@users.noreply.github.com	Bot commit identity

Generation strategies

• Default loop — repos with a specs/ directory and plain nimbase oapi.gen output. Each spec file is generated into a temporary directory and its src//tests/ are copied into output-dir — regeneration only ever replaces those two directories; every other file in the repo is left intact.
• Custom pipeline — set gen-command. Examples:
  • scripts/gen.sh (paypal-api, runs kapsis prescripts/postscripts)
  • nimbase oapi.gurugen "hetzner:1.0" ./src (repos without local specs)

Scheduling & spec-change checks

On scheduled (cron) runs, the bot first checks whether the upstream spec actually changed before doing anything:

1. It runs nimbase oapi.diff <spec-source> <spec-file> (spec-source may be a URL or an apis.guru id like hetzner.cloud).
2. If the spec is unchanged (or the baseline file doesn't exist yet, and no spec-source is configured) → generation, version bump and release are all skipped; the run exits cleanly with no release.
3. If it changed → the normal flow runs: regenerate, bump from the latest git tag, commit, tag, release — and the updated spec is committed as the new baseline (use nimbase oapi.gen/gurugen --save-spec:<spec-file> in the gen-command).

Generation is deterministic (no embedded timestamps), so even repos without spec-source never release when the specs are unchanged. Push/PR and manual (workflow_dispatch) runs regenerate as usual.

All bot commits/tags use the GitHub bot identity nimbase-bot[bot] <nimbase-bot[bot]@users.noreply.github.com> so commits show as made by the bot.

Setup

1. Push this action to nimbase/nimbase-bot and tag it v1 (git tag v1 && git push origin v1). Client workflows reference nimbase/nimbase-bot@v1.
2. No secrets required — the bot pushes with the per-run GITHUB_TOKEN. To re-run the repo's test.yml/docs.yml after the bot regenerates, add a workflow_run trigger to them (GitHub's GITHUB_TOKEN pushes don't trigger workflow runs, so a plain push trigger isn't enough):

   on:
     workflow_run:
       workflows: ['nimbase']
       types: [completed]

   Keep actions/checkout@v4 at its default (do not pin github.event.workflow_run.head_sha — that SHA predates the bot's commit; the default checkout picks up the bot's commit on the default branch).
3. Make sure each client repo has an initial tag matching its root *.nimble version (e.g. v0.1.0) so the first release diffs cleanly.

Notes

• The bot expects exactly one *.nimble at the repo root (nested package trees are fine, e.g. src/paypal/paypal_orders/paypal_orders.nimble).
• No changes after regeneration → the action exits without bumping or releasing.
• Loose multi-package workspaces (e.g. a packages/ dir with no top-level git repo) are out of scope; give each service its own repo.

License

MIT