MotherDuck Blueprints

MotherDuck Blueprints lets you manage MotherDuck resources the same way you manage application code: in a Git repository, reviewed through pull requests, and deployed by CI.

A blueprint is an independently deployable package with a blueprint.yml manifest next to its source. Typed roots make Flights, Dives, Guides, and RBAC roles easy to find; explicit inputs and outputs connect packages that share data. From there:

• Pull requests validate every blueprint, deploy branch-scoped previews, and leave a comment on the PR with the deployment plan and preview links.
• Merges to main deploy stable production resources through a protected GitHub Environment.
• Branch cleanup removes preview resources when the branch is deleted.

Dive governance travels with the code: previews are always draft, while production manifests can declare ready, endorsed, or archived. Deployment plans show live-to-desired status transitions before anything changes.

What's in this repository

This repository is the source for the Blueprints tooling. As a user, you interact with two versioned surfaces built from it:

| Artifact | What it is | | --- | --- | | motherduckdb/blueprints-template | A GitHub template repository — the fastest way to start. It is generated from this repository on each release, so don't open pull requests there. | | motherduckdb/motherduck-blueprints@v0.4.1 | The GitHub Action and CLI source for validating, planning, deploying, and migrating blueprints. Generated workflows and local setup use the same immutable release. |

Prerequisites

• Python 3.10 or newer.
• Git, used to install the versioned CLI source locally.
• Node.js 20 or newer (only needed to preview Dives locally).
• A GitHub repository with Actions enabled.
• A MotherDuck service account token for CI deployments, so deployed resources are owned by automation rather than by one person's account.

Quickstart

1. Create your repository

Use the template repository (recommended):

gh repo create <your-org>/motherduck-blueprints \
  --template motherduckdb/blueprints-template --private --clone
cd motherduck-blueprints

Or generate the same file set with the CLI:

python3 -m venv .venv
.venv/bin/python -m pip install "md-blueprints==0.4.1"
.venv/bin/md-blueprints init motherduck-blueprints
cd motherduck-blueprints

2. Try it locally, without a MotherDuck token

make setup
make validate
make preview-smoke wikipedia-pageviews

The repository ships with two working public-data examples:

• Wikipedia Pageviews demonstrates independently owned Flight producer and Dive consumer packages connected by a named output.
• NCS Field Recovery Explorer demonstrates a complete project whose Flight, share, and Dive deploy and roll back together.

3. Connect MotherDuck

• Add a GitHub Actions secret named MOTHERDUCK_TOKEN containing your service account token.
• Create a GitHub Environment named motherduck-production with required reviewers.
• Open a small pull request and confirm the preview deployment comment appears.
• Merge after review to deploy production through the protected environment.

See Set Up Your Repository for the full setup flow and GitHub Setup for the GitHub checklist.

Add a Blueprint

Use the root that matches the package's ownership boundary:

flights/   # producers, shares, and named outputs
dives/     # dashboards with declared inputs
guides/    # version-controlled agent context
roles/     # production RBAC roles and memberships
projects/  # resources that genuinely ship together
shared/    # human convention; no deployment behavior

Create a producer and consumer:

make new-flight events-ingest
make new-dive events-dashboard INPUT=events-ingest.data
make validate
make preview-smoke events-dashboard

Use make new-project revenue-overview when a Flight and Dive genuinely preview and roll back as one unit. Existing blueprints/<name>/ repositories remain supported indefinitely; no migration is required.

Guide packages can publish versioned Markdown with catalog, Dive, Flight, and Guide references. Role packages and share grants provide declarative RBAC; admin-only operations run a capability preflight before any mutation.

Create a Guide package and validate it without publishing:

make new-guide revenue-metrics
make validate

When the content is ready, follow Manage Guides as code to enable deployment, add branch-scoped previews, and attach resource references.

Once a MotherDuck token is configured, you can inspect live create/update/delete actions before applying them:

.venv/bin/md-blueprints plan --target preview --branch feature/example --blueprints events-dashboard
.venv/bin/md-blueprints cleanup --dry-run --target preview --branch feature/example --blueprints events-dashboard

How deployments work

Every pull request gets a comment with the deployment plan and preview links:

### Preview Blueprints
| Blueprint | Type | Key | Name | Action | | --- | --- | --- | --- | --- | | wikipedia-pageviews | flight | loader | wikipedia-pageviews:feature/example (Preview) | create |

• Preview deployments are branch-scoped: preview share and database names include the branch slug, Flight schedules are disabled, and resources are cleaned up when the branch goes away.
• Production deployments run only from main, through the motherduck-production GitHub Environment, so you can require manual approval before anything changes.
• Dive status is reconciled only when declared. Omitting it preserves the live status; setting endorsed requires an organization-admin deployment identity.
• Dependency selection expands both upstream and downstream for preview. Production expands downstream only, so a consumer-only change does not rerun an unchanged producer.

Versioning and upgrades

Your repository pins the tooling in two places: an exact action tag in .github/workflows/ and the matching exact CLI version in the generated Makefile. Upgrade both together; the scheduled Blueprints Doctor opens an issue when a newer release exists or the pins drift.

- uses: motherduckdb/motherduck-blueprints@v0.4.1
  with:
    command: validate

Every release requires an explicit action and CLI pin update so CI and local behavior cannot diverge. Major releases can also introduce a new manifest schemaVersion; run md-blueprints doctor and md-blueprints migrate --to latest first. See Tooling and Schema Versioning for the compatibility policy.

For live local plan, deploy, and cleanup commands, install the deploy extra from the pinned repository tag:

make install-deploy

Best practices

• Use typed roots for independently owned assets and projects/ only for resources that truly ship together.
• Declare same-repository dependencies through inputs and outputs; use literal share URLs across repositories.
• Use lowercase slug names such as account-360 or revenue-ops.
• Run a deployment plan before live deploys and use cleanup dry-runs before deleting previews.
• Deploy from CI with a service account token; store secrets in GitHub Actions, never in the repo.

Learn more

• Repository Reference: layout, targets, local commands, CI/CD, and context-layer notes.
• blueprint.yml Reference: complete field reference for blueprint manifests.
• Manage Guides as code: scaffold, preview, reference, and deploy version-controlled Guides.
• Tooling and Schema Versioning: CLI/action pinning, schema compatibility, and migrations.
• Wikipedia Pageviews example: the end-to-end example blueprint.
• NCS Field Recovery Explorer: a complete public-data project with a Flight, share, and Dive.
• MotherDuck documentation and the MotherDuck Community Slack for product questions and support.

Contributing

Issues and pull requests are welcome in this repository — see CONTRIBUTING.md. Don't open pull requests against blueprints-template; it is regenerated on each release. To report a security issue, see SECURITY.md.