Overview

Gleam builds, tests, and publishes one package directory at a time. Trellis is the workspace layer on top: it fans those commands across a whole repository and adds changelogs, versioning, and publishing, deriving its model of the workspace from the gleam.toml files already in it.

Throughout these docs, a package is one Gleam package — a directory with its own gleam.toml. A member is a package that belongs to the workspace; that word appears where membership itself is the point, as in the members key and the @members exclusion.

Derived, then verified

The member set, its topological order, change impact, and publish order all come from manifests that already exist. What can’t be derived has to be duplicated somewhere — locked versions, changelogs, tags, toolchain pins — and trellis doctor checks those, exiting non-zero when one breaks.

Some findings are mechanically fixable — a releasable package missing its CHANGELOG.md, a manifest.toml locked version that drifted from its package’s gleam.toml. For those, trellis doctor --fix writes the fix and re-reports whatever’s left. --dry-run lists the same fixes without touching a file.

Opinionated, but modular

Trellis has one way of doing each job: change fragments are TOML files in .changes/unreleased/, every releasable package gets its own git tag, and version bumps are derived from fragment kinds.

The jobs themselves are independent. Every capability is a plain command, and nothing requires the piece above it, so you can adopt trellis a layer at a time:

• Just the task runner. run, exec, list, and graph need no configuration at all — members are auto-discovered from git. Keep your existing changelog tool and CI untouched.
• Add changelogs and versioning. Fragments, version plan, and version apply manage bumps and changelogs without trellis owning your release workflow — or any CI at all.
• Add publishing. tag and publish push to Hex in dependency order, from your own scripts or workflows.
• The full pipeline. ci, changelog check, and release pr turn GitHub Actions workflows into thin triggers around trellis commands.

Commands that feed automation emit structured JSON (--json, trellis ci), so any single piece slots into whatever tooling already surrounds it — under a versioned guarantee you can assert on.

Getting started

1. Install trellis — a single prebuilt binary; shell installer, Homebrew, mise/asdf, or cargo.
2. Configure the workspace if you need to — with no configuration, members are auto-discovered from git; one optional [tools.trellis] table in gleam.toml covers everything else.
3. Run trellis doctor to verify the setup, then run tasks across the workspace.

What’s in these docs

Page	Covers
Installation	Install channels, pinning a version in CI, verifying the setup.
Configuration	The [tools.trellis] table: members, task-scoped exclusions, custom tasks, changelog and publish settings.
Task running	run and exec: built-in and custom tasks, graph-parallel scheduling, selecting packages with --since.
Changelog & versioning	TOML change fragments, PR enforcement, planning and applying version bumps.
Publishing	Release PRs, per-package tags, publishing to Hex in dependency order with path deps rewritten.
CI recipes	GitHub Actions shapes: affected-only matrices, PR gates, and the release pipeline.
JSON output	What the --json payloads guarantee: the schema field, what a stable shape permits, and where it stops.
CLI reference	Every command, flag, and argument, generated from the CLI itself.