meta-verify-action

Catch metadata-vs-code drift in a MetaObjects project at PR time.

A composite GitHub Action wrapping meta verify from @metaobjectsdev/cli. Drop it into your workflow and any divergence between your metaobjects/*.yaml declarations and your generated code (or your database) fails the PR before merge.

Usage

# .github/workflows/meta-verify.yml
name: MetaObjects Verify

on:
  pull_request:

jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write   # for the drift-summary PR comment
    steps:
      - uses: actions/checkout@v6
      - uses: metaobjectsdev/meta-verify-action@v1

That's it. The action will:

1. Install @metaobjectsdev/cli at the pinned version (default next)
2. Run meta verify --strict
3. On failure: emit a GitHub annotation + (optionally) post a PR comment with the drift report
4. Exit non-zero so the workflow fails and blocks merge

With a database (DB-drift checks)

- uses: metaobjectsdev/meta-verify-action@v1
  with:
    database-url: ${{ secrets.DATABASE_URL }}

meta verify introspects the database and checks it matches the entity metadata. Catches "I added a column to the YAML but forgot to commit the migration" before review.

Pinning the CLI version

- uses: metaobjectsdev/meta-verify-action@v1
  with:
    cli-version: '0.7.0-rc.12'     # exact pin
    # cli-version: '^0.7.0'        # caret range
    # cli-version: 'next'          # dist-tag (default)

Useful when the project's package.json pins a specific @metaobjectsdev/cli version — pass the same range here so the verify run matches local-dev behavior.

Inputs

Input	Required	Default	Description
working-directory	no	${{ github.workspace }}	Project root containing metaobjects.config.ts.
cli-version	no	next	Version range of @metaobjectsdev/cli to install.
node-version	no	20	Node.js version on the runner. Anything Node 20+ works.
database-url	no	(unset)	DATABASE_URL for DB-drift checks. Typically a secret.
prompts-dir	no	(empty, uses CLI default ./prompts)	Directory holding provider-resolved template text. Pass to override.
comment-on-pr	no	true	Post drift summary as a PR comment on failure.
install-command	no	(empty)	Optional install command (e.g. npm ci, bun install). Skipped by default; the action only needs the CLI itself, not project deps.

Outputs

Output	Description
drift-summary	Markdown summary of detected drifts (empty when clean).
exit-code	meta verify's exit code (0 = clean, non-zero = drift).

What "drift" means

The action catches divergence between:

• Metadata declarations (your metaobjects/*.yaml files) and generated code (your src/<...>/generated/ output). If you edit a field name in the YAML but forget to meta gen, the action fails.
• Metadata declarations and live database schema (when database-url is supplied). If you add a column to the YAML and forget to commit the migration, the action fails.
• Prompt templates (template.prompt) and payload value-objects (the @payloadRef-bound object.value). Catches {{undefinedField}} in a template at build time, not at runtime.
• Output parsers (template.output, FR-006) and their target payload shapes.

See the MetaObjects feature docs for the full drift contract.

Companion: pre-commit hook

For local-dev feedback before commit (faster than waiting for CI), use the pre-commit recipe in the MetaObjects docs.

Versioning

• v1.0.0, v1.0.1, … — patch releases
• v1 — floating tag, always points at the latest v1.x. Pin to @v1 for auto-updates within v1.
• Breaking changes (input renames, behavior shifts) bump to v2.

License

Apache 2.0 — matches the MetaObjects framework.

See also

• MetaObjects framework
• @metaobjectsdev/cli on npm
• Pre-commit hook recipe