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 — the bot's commit re-triggers it.

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, 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:
          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
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. Pass a bot PAT to re-trigger dependent workflows
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 output-dir/<name>.
• 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)

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.

The action works out of the box on GITHUB_TOKEN (no secret needed).

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. (Optional) Create a bot GitHub account and a PAT with the repo scope and add it as the BOT_TOKEN secret in each client repo. A bot PAT makes the bot's commits/tags re-trigger the repos' existing test.yml/docs.yml workflows — pushes made with GITHUB_TOKEN do not.
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