Run and integrate

GitHub Action

Generate and check data in CI, free in the runner or as a hosted run.

On this page

Local mode
Masking
Hosted mode
Inputs
Outputs
Self-hosted runners

The DOGM action generates a spec's data in a workflow, validates it, uploads report.junit.xml as an artifact, and fails the step when a check fails. It has two modes:

Mode	What runs	Cost
`local` (the default)	The `dogm` CLI in the runner: `dogm generate`, then `dogm validate`. No API call	Free on every plan
`hosted`	A hosted run of an approved spec version, started with a project API key that has `runs:write` and `runs:read`	Pro and Team (every beta workspace has Pro limits)

Local mode#

GitHub workflow

# .github/workflows/data.yml
permissions:
  contents: read

jobs:
  data:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: newmachinesph/dogm/dogm-action@<commit-sha>
        with:
          spec: specs/ecommerce.yaml
          seed: 4242
          rows: customers=48
          version: 0.1.0 # pin it: output bytes are stable within an engine minor version

The action downloads the release for the runner (Linux x64 and arm64, macOS x64 and arm64, Windows x64), checks it against the release's SHA256SUMS, and puts dogm on PATH, so later steps can call it too.

The data lands in out (default dogm-out): the part files, manifest.json, report.json, report.junit.xml and report.sarif. The job summary shows the verdict, output_sha256, the check counts and, when checks fail, which rules failed and on which rows. The seed is required, so the workflow file alone tells you how to rebuild the data.

Masking#

Masking is local mode only. mask_key and mask_key_version have no effect in hosted mode, and hosted runs started from the action aren't masked.

If the spec has a mask block, pass a key from a secret. Without one, the data is written unmasked (--no-mask) and the summary says so. The secret is the base64 of the 32-byte file dogm keygen writes:

Shell

dogm keygen --out key.bin && base64 -w0 key.bin   # store the output as the secret DOGM_MASK_KEY

GitHub workflow

      - uses: newmachinesph/dogm/dogm-action@<commit-sha>
        with:
          spec: specs/ecommerce.yaml
          seed: 4242
          mask_key: ${{ secrets.DOGM_MASK_KEY }}

mask_key_version (default 1) is recorded on the run; a new version is a new mapping. Masked personal data is still personal data under the Philippine Data Privacy Act, so treat the artifacts that way.

Hosted mode#

GitHub workflow

      - uses: newmachinesph/dogm/dogm-action@<commit-sha>
        with:
          mode: hosted
          spec_version_id: 3f1c...  # an approved spec version (Run > Reproduce shows it)
          spec_hash: 9f2c...        # optional: fail if the version isn't this one
          seed: 4242
          api_key: ${{ secrets.DOGM_API_KEY }}

Create the key under Settings > API keys for the version's project, with the runs:write and runs:read scopes, and store it as a secret. The action then:

calls POST /v1/runs with an Idempotency-Key that is unique per workflow run attempt and step, so a retried request never starts a second run;
polls GET /v1/runs/{run_id} every 10 seconds, for up to an hour;
downloads report.junit.xml through the signed URL from GET /v1/runs/{run_id}/artifacts/{artifact_id};
fails if any check failed.

API errors fail the step with their code: E_KEY_PAUSED when the org's plan has no API keys, E_KEY_REVOKED, E_SCOPE. The key is masked in the log, sent only in a header read from a temporary file, and never sent to the signed download URL. Hosted mode needs curl and jq, which GitHub-hosted runners have.

On a Free org, API keys are paused, and local mode is the way to run in CI.

Inputs#

Generated from dogm-action/action.yml.

Input	Default	Description
`mode`	`local`	`local` runs the dogm CLI in the runner (free). `hosted` runs on the DOGM.ai API with a project API key (Pro and Team).
`spec`	None	Path to the spec file (local mode).
`seed`	None	Unsigned 64-bit seed. Required, so every run is reproducible from the workflow file.
`rows`	None	Row overrides for root tables, `table=count`, separated by spaces, commas or newlines.
`format`	`csv`	Output format, csv, jsonl, sql or parquet. In local mode, sql output is checked by dogm generate only (dogm validate reads csv, jsonl and parquet).
`out`	`dogm-out`	Output directory, relative to the workspace. report.junit.xml is written here.
`version`	`latest`	dogm CLI version to install (local mode), e.g. 0.1.0, or `latest` for the newest cli-v* release.
`mask_key`	None	Base64 of a 32-byte mask key (`dogm keygen`), from a secret. Local mode only; hosted runs from the Action are not masked. Empty runs with --no-mask.
`mask_key_version`	`1`	The mask key's version, recorded on the run (local mode).
`spec_version_id`	None	ID of the approved spec version to run (hosted mode). The API key's project must own it.
`spec_hash`	None	Optional pin (hosted mode). The step fails if the version's spec_hash is not this one.
`api_key`	None	Project API key, dogm_live_..., with the runs:write and runs:read scopes (hosted mode). Pass it from a secret.
`api_url`	`https://api.dogm.ai`	DOGM.ai API base URL (hosted mode).
`github_token`	`${{ github.token }}`	Token used to download the CLI release (local mode). Needs read access to the release repository.
`artifact_name`	`dogm-report-${{ github.job }}`	Name of the uploaded report artifact. Set a distinct one per matrix leg or per use in a job.

Outputs#

Output	Description
`exit_code`	0 passed, 1 failed checks, 2 compile errors, 3 input, I/O or API errors.
`output_sha256`	SHA-256 of the run's manifest.json.
`report`	Path of report.junit.xml.
`cli_version`	The dogm CLI version installed (local mode).
`run_id`	The hosted run's ID (hosted mode).

exit_code follows the CLI's exit codes, with API errors as 3.

Self-hosted runners#

They need bash and gh, plus unzip on Windows or tar on Linux and macOS. The logic lives in install.sh, local.sh and hosted.sh next to action.yml, so you can run and test it outside Actions.