Skip to content
Rowsafe
Docs

GitHub Action

Every input and output of rowsafe/action, its checks, and how it verifies the CLI.

rowsafe/action saves a Mark before a deploy. Guide: Save a Mark before every deploy.

- uses: rowsafe/action@v1
  with:
    api-key: ${{ secrets.ROWSAFE_API_KEY }}
    database: app

What it does, in order

  1. Installs the CLI from the GitHub release, checks SHA256SUMS and SLSA provenance, and caches it (Verification).
  2. Finds the database: the database input, else ROWSAFE_DATABASE, else the nearest .rowsafe.json, else the organization's only database.
  3. Checks protection (rowsafe status): can the database be restored now? If not: a warning, or with require-protected: true the step fails.
  4. Previews migrations (with preview-sql, if the CLI has rowsafe preview): the new files run in order on a copy on your server; the report goes in the job summary. Verdict failed fails the step before the Mark (it would fail on production too). careful or dangerous: a warning, or a failure with fail-on.
  5. Saves the Mark (rowsafe mark). With wait: true, waits for your bucket to confirm it; not confirmed within wait-timeout-minutes fails the step.
  6. Writes the outputs and job summary.

Inputs

InputDefaultDescription
api-key(required)A read-write API key (rsk_...), from a secret. A read-only key can check protection but not save the Mark.
databasesee step 2The Rowsafe database name.
labelbefore-deploy-<sha>The Mark's name (<sha>: the commit's first 7 characters). Lowercased; runs of characters other than letters, digits, - and _ become -; cut to 63 characters. If the default is taken (a re-run), -2, -3, ... up to -20 is added. A taken label you set fails the step.
waittrueWait until your bucket confirms the Mark. false returns once requested.
require-protectedfalseFail when the database isn't protected, instead of warning.
preview-sqlGlob patterns (space or newline separated) relative to working-directory; ** crosses directories. If the preview can't run (e.g. no backup yet), the step warns and goes on.
preview-changed-onlytruePreview only files added or changed since github.event.before (push) or the pull request's base. If that's unknown (another event, or the base can't be fetched), the preview is skipped with a warning.
fail-onneverdangerous: fail on a dangerous verdict. careful: on careful or dangerous. never: warnings only. A migration that fails on the copy always fails the step.
wait-timeout-minutes10How long to wait for the Mark, and for the preview.
working-directory.Where .rowsafe.json and preview-sql are looked up.
versionlatestCLI version (0.4.0 or v0.4.0), or latest (newest GitHub release).
verify-provenanceautoauto: verify provenance if the GitHub CLI (2.49+) and a token are available, else warn. true: required. false: skip (the checksum is still checked).
api-urlhttps://api.rowsafe.shThe Rowsafe API.
cli-pathA rowsafe binary to use instead of downloading. Not verified by the action.
github-tokengithub.tokenUsed only by gh attestation verify to read the CLI's attestations.

Outputs

OutputDescription
markThe Mark's name.
restore-from-backupThe backup a rewind to this Mark starts from. Empty with wait: false.
dashboard-urlThe database's Marks in the dashboard, to rewind to one.
databaseThe database that was marked.
protectedtrue or false: could the database be restored when the step ran.
preview-verdictsafe, careful, dangerous or failed (fails on the copy). Empty if no preview ran.

The job summary

  • Success: the Mark and when it was confirmed, the database and whether it was protected, the backup a rewind starts from, the commit, the preview report (same as the CLI's pull request comment), a Rewind to this Mark link, and the CLI commands for this Mark (collapsed).
  • Failure: what stopped the deploy and what to do: why the database isn't protected, why the Mark wasn't confirmed, or which input is wrong.
  • Annotations on the run: a notice with the Mark, warnings (not protected, preview skipped), errors.

Verification

Every run checks the CLI twice before running it, even from the cache:

  1. Checksum: its SHA-256 must match the release's SHA256SUMS, fetched fresh. A mismatched cached copy is downloaded again.
  2. Build provenance: gh attestation verify checks the SLSA provenance: signed by rowsafe/rowsafe's release.yml workflow, at that version's tag, in the public Sigstore transparency log. Always runs on GitHub-hosted runners (the GitHub CLI is installed).

Cached with actions/cache (keyed by version and platform), and in the tool cache on self-hosted runners.

Runners

Linux and macOS, x64 and ARM64, GitHub-hosted or self-hosted. No Windows: use runs-on: ubuntu-latest for the deploy job. Needs bash, curl and git (for preview-changed-only).

Errors

SummaryWhat happened
no API keyapi-key is empty. On pull_request from a fork, secrets aren't available.
API key rejectedThe key is wrong or was revoked.
database not foundNo database with that name in the API key's organization.
can't reach RowsafeThe API didn't answer.
which database?No database input, no .rowsafe.json, and the organization has several databases.
database is not protectedWith require-protected: true. The summary lists why and links to the database.
the migration failsIt failed on the copy; the report has the SQL error and line. No Mark saved, production untouched.
migration looks careful / dangerousWith fail-on. No Mark saved, production untouched.
Mark not confirmedYour bucket didn't confirm it in time (usually archiving is failing), or the agent didn't pick it up within wait-timeout-minutes.
Mark not savedAnything else: a label that is taken, a read-only key.
Edit on GitHub