# CI
Gate pull requests with the Ptah GitHub Action or shell checks, and read exit codes correctly.
Source: https://docs.ptah.run/v0.8.0/testing/ci/
Run Ptah in CI to catch migration drift, destructive changes, hash mismatches,
and unsupported capabilities before merge. The source-neutral path invokes the
CLI directly and names the desired-schema source explicitly:
```bash
ptah schema validate --schema-file schema.sql --dialect postgres
ptah migrations plan \
--schema-file schema.sql \
--db-url "$PTAH_DATABASE_URL" \
--report json --check-destructive
ptah schema drift \
--schema-file schema.sql \
--db-url "$PTAH_DATABASE_URL"
```
Replace `--schema-file schema.sql` with the exact selector for another source.
Use a disposable database for the plan and a controlled long-lived environment
for the drift gate.
## GitHub Action
Ptah ships a Marketplace GitHub Action as `stokaro/ptah-action@v1`. On a pull
request it generates a migration plan, evaluates the safety verdict, optionally
lints the migration directory, updates one sticky pull request comment, and
writes a `Ptah destructive-change verdict` check run from the machine-readable
safety report.
The action takes the same desired-schema sources the CLI does. `dir` selects
Go annotation roots, `schema-file` selects SQL, YAML, HCL, DBML or `oci://`
sources, and `schema-cmd` with `schema-format` selects an external loader. Each
one forwards to the flag of the same meaning, and `dir` and `schema-file` take
one value per line and compose.
A run that selects no Go source installs no Go toolchain, even with the default
`setup-go: true`.
```yaml
name: Ptah
on:
pull_request:
permissions:
checks: write
contents: read
issues: write
pull-requests: write
jobs:
ptah:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: stokaro/ptah-action@v1
with:
dir: ./internal/models
db-url: ${{ secrets.PTAH_DATABASE_URL }}
dialect: postgres
migration-dir: ./migrations
lint: "true"
comment: "true"
```
Behind the scenes the action runs:
```bash
ptah migrations plan --report text
ptah migrations plan --report json --check-destructive
ptah migrations lint --format json
```
The text plan keeps the SQL in the pull request comment for reviewers; the
separate JSON safety run drives the destructive-change gate. With
`allow-destructive: "false"` (the default), a destructive plan fails the job
after the comment is posted; lint failures also fail the job after the comment
is posted.
### What the Action posts
The comment is assembled from the three commands above. On a pull request that
adds one table it reads:
````markdown
## Ptah migration plan
Safety: safe.
Plan command: exit 0.
Safety command: exit 0.
Lint command: exit 0.
Migration SQL and safety text
```sql
Generating migration from ./models to database sqlite://app.db
=== GENERATE MIGRATION SQL ===
Safety classification:
# severity subject reason
1 safe *ast.CreateTableNode does not remove data or tighten constraints
=== MIGRATION SQL ===
-- Migration generated from schema differences
-- Generated on: now
-- Source: ./models
-- Target: sqlite://app.db
CREATE TABLE "users" (
"id" INTEGER PRIMARY KEY,
"email" TEXT NOT NULL
);
Generated 1 migration statements.
⚠️ Review the SQL carefully before executing!
```
Safety JSON
```json
{
"highest": "safe",
"destructive": false,
"assessments": [
{
"index": 1,
"node_type": "*ast.CreateTableNode",
"statement": "CREATE TABLE \"users\" (\n \"id\" INTEGER PRIMARY KEY,\n \"email\" TEXT NOT NULL\n)",
"severity": "safe",
"reason": "does not remove data or tighten constraints"
}
]
}
```
Lint JSON (0 finding(s))
```json
{
"failed": false,
"failure_threshold": "error",
"dialect": "sqlite",
"dir": "./migrations",
"findings": []
}
```