Add action template engine (#48)

Generate flat, self-contained release actions from templates.

## Why

This repo ships composite actions that other SDK repos pin by **SHA**.
GitHub
resolves a `./actions/...` path against the **calling** repo's workspace
— so a
composite action fetched by SHA that internally calls a sibling action
fails:

```
Can't find 'action.yml' under '.../braintrust-sdk-ruby/actions/release/lang/ruby/rubygems-push'
```

Our release pipeline nested 4–5 levels of `uses: ./actions/...`, so it
broke for
every external consumer. There's no "group `if:`" or sub-action trick
that avoids
this (confirmed against the GitHub Actions docs) — the only fix is to
**not nest**.

## What changed

`actions/` is now **generated, flat output**. Source lives in
`templates/`; a
small ERB generator inlines reusable **steps** into each **action**, so
every
shipped `action.yml` is self-contained — no intra-repo `uses:`, only
`run:` steps
and marketplace actions. A single SHA pin now pulls in the whole chain,
no
transitive bumping.

**Before** — `publish` delegated to siblings (breaks when pinned
externally):

```yaml
- uses: ./actions/release/lang/ruby/rubygems-push      # ← resolves in the CALLER's repo → 404
- uses: ./actions/release/create-github-release
- uses: ./actions/release/lang/ruby/notify-published
```

**After** — `publish` is one flat action, and its template reads like
the pipeline:

```erb
- uses: actions/checkout@...
  if: ${{ inputs.checkout == 'true' }}
<%= render_step('lang/ruby/setup') %>
<%= render_step('release/lang/ruby/rubygems-push') %>
<%= render_step('release/create-github-release') %>
<%= render_step('release/lang/ruby/notify-published') %>
<%= render_step('release/lang/ruby/on-failure', if: "${{ failure() }}") %>
```

`render_step` inlines each step's YAML. Control flow stays in the
action: pure
"do" steps, then one terminal `on-failure`. Since GitHub can't guard a
*group* of
steps, `render_step(if:)` **stamps the condition onto every step it
expands** —
so the generated `on-failure` fans out to `env-dump` + `notify-failure`,
each
carrying `if: ${{ failure() }}`. Everything else a step decides ("Slack
configured?", "dry run?") is a shell `exit 0` self-guard, so there's
never a
condition to merge.

Result: **4 flat actions** composed from **11 reusable steps**, zero
intra-repo
`uses:`.

## Usage

- **Consumers** copy the canonical workflow (`release-ruby.yml`) into
their repo,
  adapt the marked sections, and pin the actions by SHA. (README)
- **Contributors** edit `templates/`, run `rake generate` (renders +
validates
YAML *and* the GitHub Action schema), and commit `templates/` +
`actions/`
  together. CI (`rake ci:actions`) fails if they drift. Toolchain is one
  `mise install`. (CONTRIBUTING)

## Validation

End-to-end dry run of the generated actions against the `bt-fake` gem
(`release-ruby.yml`) **passes** on this branch.

Author: delner

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # Regenerates actions/ from templates/, validates them (YAML + schema), and
+  # fails if the committed actions/ is out of sync. actions/ is generated output
+  # and must always match `rake generate`. Least-privilege: no secrets in scope.
+  #
+  # Tool versions come from mise.toml (single source of truth). Ruby is installed
+  # prebuilt by setup-ruby (fast) rather than compiled by mise; everything else
+  # (Python, check-jsonschema) comes from mise via mise.toml.
+  check-generated:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    env:
+      MISE_DISABLE_TOOLS: ruby   # Ruby comes prebuilt from setup-ruby; don't let mise compile it
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Ruby (prebuilt; version read from mise.toml)
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        with:
+          ruby-version: mise.toml
+
+      - name: Set up Python + check-jsonschema (from mise.toml)
+        uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+
+      - name: Regenerate, validate, and verify in sync
+        run: rake ci:actions

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing
+
+## Setup
+
+This repo uses [mise](https://mise.jdx.dev) to manage its toolchain. `mise.toml`
+is the single source of truth for tool versions (Ruby, Python, and
+`check-jsonschema`) — CI reads it too. With mise installed:
+
+```sh
+git clone https://github.com/braintrustdata/sdk-actions && cd sdk-actions
+mise install      # ruby, python, check-jsonschema — versions from mise.toml
+rake generate     # render templates/ → actions/, then validate
+```
+
+## Adding or changing actions
+
+`actions/` is generated output. **Do not edit it by hand** — edit `templates/`
+and regenerate:
+
+- **A new step:** add `templates/steps/<scope>/<name>.yml.erb` (one or more
+  steps; document its params in a leading `<%# … %>` comment), then compose it
+  with `render_step` where needed.
+- **A new action:** add `templates/actions/<path>.yml(.erb)` and run
+  `rake generate`. It appears at `actions/<path>/action.yml`.
+
+After any change, run `rake generate` and commit `templates/` and the regenerated
+`actions/` **together**. CI fails if they drift.
+
+### Commands
+
+| command | what it does |
+|---|---|
+| `rake` / `rake generate` | render `templates/` → `actions/`, then validate (YAML + schema) |
+| `rake render` | render only (no validation) |
+| `rake validate` | `validate:yaml` + `validate:schema` |
+| `rake validate:yaml` | every generated action parses as YAML (stdlib, no extra deps) |
+| `rake validate:schema` | every generated action conforms to the GitHub Action schema |
+| `rake ci:actions` | what CI runs: regenerate, validate, and fail if `actions/` is out of sync |
+
+## Design
+
+### Why generated, and why flat
+
+GitHub resolves a `./actions/...` path relative to the **calling workflow's**
+workspace, not the repo the action was fetched from. So a composite action that
+another repo pins by SHA **cannot** call a sibling action in this repo via `./`
+— it just won't be found. (And GitHub has no mechanism to guard a *group* of
+steps, so you can't nest your way around it either.)
+
+The template system sidesteps this by **inlining everything at generation time**:
+each shipped action is one self-contained `action.yml` with no intra-repo
+`uses:` — only `run:` steps and external (marketplace) actions. That makes every
+action safely referenceable by SHA from any repo.
+
+### Layout
+
+```
+templates/
+  actions/                     # The actions a workflow calls (→ actions/<path>/action.yml)
+    release/                   # Language-agnostic actions for releases
+    release/lang/<LANG>/       # Language-specific actions for releases go here
+  steps/                       # Reusable steps composed INTO actions (never shipped standalone)
+    slack/                     # Slack functions
+    release/                   # Release functions
+    lang/<LANG>/               # Language functions
+    release/lang/<LANG>/       # Language-specific release functions
+scripts/
+  generate.rb                  # Renders templates/ → actions/
+  github-action.schema.json    # Vendored SchemaStore schema (used by `rake validate:schema`)
+actions/                       # GENERATED — do not edit
+Rakefile
+```
+
+#### actions vs. steps
+
+- **`templates/actions/`** — entrypoints a workflow `uses:`. Generated flat, no
+  intra-repo `uses:`. These are the public, SHA-referenceable surface.
+- **`templates/steps/`** — reusable fragments (one or more steps) composed into
+  actions with `<%= render_step('<name>', ...) %>`. A step may compose other
+  steps. Steps are *not* referenced by a workflow directly. They're grouped by
+  scope: `release/` (language-agnostic release logic), `lang/<lang>/`
+  (language-specific, release-neutral), and `release/lang/<lang>/` (both).
+
+### How templates work
+
+A `.yml.erb` template is plain YAML plus `render_step` calls; a `.yml` template is
+copied verbatim. `render_step(name, indent: 4, **locals)`:
+
+- inlines `templates/steps/<name>.yml.erb`;
+- exposes keyword args to the step as a `locals` hash, read with
+  `locals.fetch(:x) { default }`;
+- **`if:`** is the composing action's one control-flow knob — it's stamped onto
+  *every* top-level step in the fragment (GitHub has no group-level `if:`), so a
+  terminal `on-failure`'s `if: failure()` lands on each of its steps;
+- nested calls (a step composing another step) pass `indent: 0`.
+
+#### Conventions
+
+- **Control flow lives in the action.** Compose pure "do" steps, then a terminal
+  failure handler: `… → render_step('on-failure', if: "${{ failure() }}")`.
+- **Non-control conditions are shell self-guards, not `if:`.** "Slack
+  configured?", "dry run?", "create a GitHub release?" are handled with an early
+  `exit 0` inside the step's own `run:` — so there's never an `if:` for the
+  generator to merge, and control flow stays readable at the call site.
+
+

README.md

@@ -1,2 +1,49 @@
 # sdk-actions
-Shared actions for braintrust SDKs.
+
+Shared GitHub actions and workflows for Braintrust SDK repositories.
+
+## Releases
+
+**Copy the canonical release workflow template** from `.github/workflows/release-<LANG>.yml` and adapt it for your repository. Using it as an upstream source will enable the implemented release process to receive improvements in the future.
+
+### Adopting the release workflow
+
+1. **Copy the canonical template** for your language into your repo's
+   `.github/workflows/`. For Ruby that's
+   [`release-ruby.yml`](.github/workflows/release-ruby.yml) — it doubles as this
+   repo's end-to-end test and the reference implementation.
+2. **Adapt the marked sections** — version source, gem name, working directory,
+   and so on. The template's comments flag exactly what changes per repo;
+   everything else is provided by the pinned actions.
+3. **Record the upstream version you based it on** — the sdk-actions ref (commit
+   SHA or tag) your copy was adapted from, e.g. in a header comment. Tracking it
+   lets you (or an agent) diff your copy against a newer upstream template and
+   sync changes deliberately as this repo evolves.
+4. **Bump the pinned SHA** to pick up action changes. Because each action is
+   self-contained, one SHA bump pulls in the whole updated chain.
+
+### Available release actions
+
+The release workflow is composed from these actions. You normally get them via
+the template, but they're listed here as a reference for customizing it — each is
+**self-contained** (calls no other action in this repo), so a single SHA pin
+pulls in everything it needs.
+
+| Action | Purpose |
+|---|---|
+| `release/lang/ruby/publish` | Push the gem to RubyGems, create the GitHub release, and notify |
+| `release/lang/ruby/validate` | Check out the SHA, set up Ruby, read the version, validate the release (tag/branch/metadata), lint + build |
+| `release/notify-pending` | Post the pre-approval job summary and Slack notification |
+| `release/prepare` | Fetch the PR list and release notes |
+
+Inputs and outputs are documented in each `action.yml`. Reference an action by
+commit SHA:
+
+```yaml
+- uses: braintrustdata/sdk-actions/actions/release/prepare@<sha>
+```
+
+## Developing
+
+`actions/` is **generated** from `templates/` — never edit it by hand. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the template system and workflow.

Rakefile

@@ -0,0 +1,50 @@
+ACTIONS  = FileList['actions/**/action.yml']
+SCHEMA   = 'scripts/github-action.schema.json'
+
+task default: :generate
+
+desc 'Render actions/ from templates/, then validate them (YAML + schema)'
+task generate: %i[render validate]
+
+desc 'Render actions/ from templates/ (no validation)'
+task :render do
+  ruby 'scripts/generate.rb'
+end
+
+desc 'Run all checks on the generated actions (YAML + schema)'
+task validate: %w[validate:yaml validate:schema]
+
+namespace :validate do
+  desc 'Check that every generated action parses as YAML (stdlib, no extra deps)'
+  task :yaml do
+    require 'yaml'
+    errors = ACTIONS.sort.filter_map do |file|
+      YAML.safe_load_file(file)
+      nil
+    rescue Psych::SyntaxError => e
+      "  #{file}:#{e.line}:#{e.column}: #{e.problem}"
+    end
+    abort "Malformed YAML in generated actions:\n#{errors.join("\n")}" unless errors.empty?
+  end
+
+  desc 'Validate every generated action against the GitHub Action schema (needs check-jsonschema)'
+  task :schema do
+    on_path = ENV['PATH'].to_s.split(File::PATH_SEPARATOR)
+                         .any? { |dir| File.executable?(File.join(dir, 'check-jsonschema')) }
+    unless on_path
+      abort <<~MSG.strip
+        check-jsonschema not found on PATH. Install the toolchain with `mise install`
+        (or `pipx install check-jsonschema`), then re-run. To skip schema validation,
+        use `rake render` or `rake validate:yaml`.
+      MSG
+    end
+    sh 'check-jsonschema', '--schemafile', SCHEMA, *ACTIONS
+  end
+end
+
+namespace :ci do
+  desc 'CI guard: regenerate + validate, then fail if committed actions/ is out of sync with templates/'
+  task actions: :generate do
+    sh 'git', 'diff', '--exit-code', 'actions/'
+  end
+end