Quickstart: the Assure GitHub Action

First run checklist. Tick all five before the first run.

• The collection role exists, with CONNECT on your database (section 2).
• The runner can read the server's configuration files, or has copies it can read (section 6). Managed PostgreSQL: skip this line.
• The connection string works from the runner: psql '<the connection string>' -c 'SELECT current_user' prints assure_collector (section 3).
• The job that runs Assure has id-token: write under permissions:, or an API key is stored as the repository secret ASSURE_API_KEY (section 1).
• profile is left at its default, postgresql-observed-baseline.

Served today: five profiles. postgresql-observed-baseline: intent-free, from a connection or an artefacts directory. postgresql-declared-model: an artefacts directory (raw/declaration.json) or a connection with .assure/declaration.json. http-observed-baseline: an artefacts folder holding an endpoint manifest and captured response heads; the Action produces the scope binding and passes the identity key by pipe. mysql-declared-model: a MySQL server, from a mysql:// connection plus your declaration file (declaration), or an artefacts directory holding raw/submission.json; reports are withheld (profile_unqualified) until the writer is qualified for MySQL. python-auth-declared-model: a Python (Flask) repository, free, from the checkout in one step; the Action proposes a drafted declaration in a pull request the merge accepts; FastAPI, Django and standard-library http.server repositories with your declaration.

Known-vulnerability scanners check your code against a list of what has broken before. Assure checks whether the way your code meets the foundational software it runs on stays inside a regime that can be shown safe and reliable, and says exactly what it could and could not establish.

Assure is the check that reads green only when nothing it examined is disproven. It tells you the bounds of what it has established, and why it matters. In an age where machines generate code at a volume nobody can read, Assure shows that each change maintains its baseline security and reliability, and stays true to any formalised requirements.

Supported PostgreSQL majors: 14 to 18. Real-run evidence: 17 and 18.

Rules the collector keeps, and rules it withholds. The collector this Action ships keeps a pg_hba.conf rule with a quoted name, an @file list or a regular-expression user (/^...) as written, and the check reads it. A rule or setting it still has to withhold, such as a rule with an unclosed quote, becomes a marker line that names its own line number and reason. The check reads that rule or setting as not observed, and the summary lists it as not observed: <file> line N (<the reason in plain words>).

Files collected earlier with the earlier collector, given as artefacts, still stop at such a rule with exit 3 (collector_refused): that collector withheld it whole, and Assure cannot read it. The message names the file and the line. Collect again with this Action. If you cannot: remove quotes a name does not need; write an @file list's names inline; use a +group role in place of a list; list a regular-expression user's roles by name. Otherwise, send Symbolia the file name and the line number through your Symbolia contact, so the shape is counted.

The Action collects facts in your GitHub Actions runner and sends them to api.symbolia.ai over TLS with a key: one it gets for this run from your workflow's GitHub identity, or your own API key. The check runs on Symbolia's server; the Action writes the verdict, job summary and annotations in your runner.

On a pull_request event the Action also posts the result as one comment on the pull request, "Assure: N rules broken by this change", with what is broken and the fix, what still holds, and what was not checked yet. It is rendered from the verdict, with no model. A run that is refused before a verdict posts the same comment with the refusal, one next step, and each promise of the requirements file it sent reading not established, the refusal named as the reason. Each later run on the pull request updates the same comment. The Action posts it with the workflow's own token, so the job needs pull-requests: write under permissions: (keep contents: read beside it); the jobs on this page grant it. Without that permission the comment is not posted, the job log carries one notice naming the line to add, and the verdict, the job summary and the exit code are unchanged.

What is sent, and what is never read

The Action sends the collector's output: catalog facts (roles, memberships, object ACLs, policies, functions, schemas, settings and similar) and, when the runner can read them, your configuration files. What leaves the runner:

• settings and rules as written, without comment text: every comment in your configuration files, including commented-out settings, is replaced in the runner with # <withheld comment>, and every line keeps its place. A line PostgreSQL cannot parse (an unclosed quote) becomes <withheld: a line PostgreSQL cannot parse>, which the check still counts as a broken line; if the check would read it as a working setting or rule, the Action stops, exits 2 (bad_input) and names the file and the line, and you fix the line and run again. A pg_hba.conf rule or postgresql.conf setting the collector had to withhold whole is a marker line the check reads as not observed, and the summary lists it as not observed: <file> line N (<reason>). A marker whose line number is not its own, or whose reason is not one the collector writes, stops the upload with exit 2 (bad_input), and a collection that mixes this collector's output with the earlier collector's stops with exit 3 (collector_refused). In files from the earlier collector, a rule or setting that collector withheld whole stops the upload with exit 3 (collector_refused) (section 9). The collector's record of which lines it withheld (COLLECTION-SIDECAR.json) must come with its output, with the REDACTION-MANIFEST.json from the same run: without them, a file that holds a withheld line cannot be checked, and the upload stops the same way;
• policy expressions with every string literal withheld: each quoted literal becomes '<withheld literal N>' in the runner, and so does each literal in your declaration's declared_predicate (raw/declaration.json in an artefacts directory, .assure/postgresql-declared-model.json or .assure/declaration.json with a connection); except a setting name written as a standard-quoted 'name' directly after current_setting(, which is sent as written;
• no secret-bearing value: the collector withholds every one whole before anything is written, and checks its own output for those values.

The job log and the job summary state how many comments and literals were withheld. For a profile whose inputs name no PostgreSQL configuration or pg_hba.conf file, such as the HTTP profile, nothing is withheld: the files are sent as read, and the line says "nothing to withhold — the withholding pass covers PostgreSQL configuration and pg_hba files and the SQL literals in the catalog snapshot and the declaration, and this profile's inputs name none of them". DATA.md lists every item, including what is still sent as written, such as role names and client addresses.

The collector never reads table contents, password hashes, key material or other sessions' statements. It reads the connection string of a subscription and withholds it whole before anything is written.

The Action sends only files the profile reads. It fetches each profile's list of file names and size limits from the API first, and checks every file against that list in the runner. A file with another name, or over its limit, stays in the runner.

The server deletes the collected facts when the check ends. On the Premium tier a sealed copy is kept for the formal shadow (see DATA.md). It keeps the verdict for 30 days.

Both data-sending inputs are opt-in: with no inputs the Action asks for no report, so no verdict record goes to a third-party model, and uploads no requirements.md; set report: true to ask for the report, and name the file in the requirements input (for example requirements: requirements.md) to send its text. In mode: api the Action sends the text of the file you name (within 65536 bytes, 256 lines and 8192 bytes per line), your repository name and the commit (on a pull request, its head commit); the server keeps them with the check for 30 days. Setting requirements to none stops the requirements text only: the repository and the commit are still sent and kept with the check for 30 days. The Action reads the requirements text from the files your workflow checked out; the commit it sends is a label for the run, not the source of the text. On pull_request the checkout is the merge commit GitHub made, and on pull_request_target it is the base branch, while the commit sent is the pull request's head commit.

The requirements text comes from the checked-out workspace, not fetched from the named commit. A pull request workflow may read a merge tree, and pull_request_target may read the base branch, while the metadata names the pull request head. Align the checkout with the commit you intend to check; caller/runner provenance is not a GitHub attestation.

What the runner needs

• Outbound HTTPS to api.symbolia.ai (port 443).
• A network path to your database, for a check with connection.
• Python 3.14 and, for connection, the PostgreSQL client (psql).

1. Get an API key

The Action can get one for each run itself, and you store nothing. Give the job that runs Assure the permission id-token: write. The Action then asks GitHub for this workflow's identity token, made for Assure, and exchanges it at POST /v1/auth/oidc for a key that lives for this run only (at most one hour). A sign-in key never rotates into a longer-lived key (POST /v1/keys/rotate refuses it rotate_too_early); the next run signs in again. Your Assure account is your GitHub owner (the user or organisation that owns the repository), on the free plan the first time it signs in. The key is masked in the job log before it is used.

Naming one permission sets every other permission to none, so keep contents: read beside it, or actions/checkout fails on a private repository. The permission lets the job ask GitHub for an identity token for this repository; it gives no write access to the repository.

The smallest job, for files you collected and committed in collected/ (section 9); put it under jobs: in a workflow that runs on pull_request and on push to your default branch:

    permissions:
      contents: read
      id-token: write
      pull-requests: write
    steps:
      - name: Check out the repository
        uses: actions/checkout@<full commit sha of the release you trust>

      - name: Set up Python 3.14
        uses: actions/setup-python@<full commit sha of the release you trust>
        with:
          python-version: "3.14"

      - name: Assure check
        uses: Symbolia-Assurance/assure-action@beta
        with:
          artefacts: collected

With no api-key and no id-token: write, the Action stops before it collects or sends anything, with bad_input (exit 2) and a reason that names the line to add. A sign-in the API refuses is unauthenticated (exit 2), and detail.identity in the failure file names the check that failed; run the job again.

Or store a key from Symbolia

Ask Symbolia for a key. It starts with asr_, and you receive it once. A key you pass is used, and the Action does not ask GitHub for an identity token.

In your repository, open Settings → Secrets and variables → Actions → New repository secret:

• Name: ASSURE_API_KEY
• Value: the key.

The Action masks the key in the job log before it prints anything. It sends the key only in the Authorization header to the API, over TLS, and never follows a redirect.

2. Create a collection role

The Action connects as a role you create for it. Give that role read access to settings and statistics, and nothing more.

Run this as a superuser or a role that can create roles:

CREATE ROLE assure_collector LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS
  PASSWORD '<choose a long random password>';
GRANT pg_read_all_settings, pg_read_all_stats TO assure_collector;
GRANT CONNECT ON DATABASE <your database> TO assure_collector;

In these statements <your database> is the name of the database to check, or postgres for a local server that holds no other database.

The CONNECT grant matters when your database revokes CONNECT from PUBLIC (for example REVOKE ALL ON DATABASE <your database> FROM PUBLIC). Without it, the first run stops with collector_cannot_connect and the reason permission denied for database. Where PUBLIC still has CONNECT, the grant changes nothing.

The collector also reads the catalog of each other database that allows connections, such as postgres and template1 (see DATA.md). Where PUBLIC has no CONNECT on one of them, that database is recorded as a gap (permission denied for database) and the collection is marked incomplete; to have it read, grant CONNECT ON DATABASE <that database> to the same role. On a server with thousands of databases, those past the pass's bounds (time and size, see DATA.md) are recorded as gaps the same way, without being read.

Then allow the role to log in from the runner. Add a line to pg_hba.conf and reload the server:

host  <your database>  assure_collector  <the runner's address>/32  scram-sha-256

Rules for this role:

• Create a new role. Use it for nothing else. The checker leaves the collection role out of every reading, so a role your site also uses would hide its own results.
• Grant it only these two roles. The collector refuses a broader role: pg_monitor or pg_stat_scan_tables in collection-privileges stops the Action with exit 2 (bad_input) before anything runs, and a role that belongs to either stops it with exit 3 (collector_refused). The collector also refuses to run if the role is a superuser, has CREATEDB, CREATEROLE, REPLICATION or BYPASSRLS, or belongs to any other role.
• Allow it to log in through pg_hba.conf from the runner's address.

The collector runs a fixed, published set of SELECT queries. It writes nothing to your database. The collector asks for a read-only session. A pooler may not pass the request on. The collector runs only fixed SELECT statements either way. The collector records whether the session was read-only, and the job summary says so (section 8).

3. Store the connection as a secret

Add a second repository secret:

• Name: ASSURE_PG_CONNECTION
• Value: a libpq connection string or URI, for example:

host=db.example.internal port=5432 dbname=app user=assure_collector password=<the password> sslmode=require

sslmode=require encrypts the connection but does not check the server's certificate. It works with the self-signed certificate that the Debian and Ubuntu packages set up. sslmode=verify-full also checks that the certificate is signed by an authority the runner trusts and names the host you connect to. It is the stronger choice. It needs a certificate the runner trusts: a self-signed server certificate fails it. Give the authority's certificate with sslrootcert:

host=db.example.internal port=5432 dbname=app user=assure_collector password=<the password> sslmode=verify-full sslrootcert=/path/to/root.crt

Test the string from the runner before the first run. Leave the password out and type it at the prompt, so it stays out of your shell history:

psql 'host=db.example.internal port=5432 dbname=app user=assure_collector sslmode=require' -c 'SELECT current_user'

It prints assure_collector. If it does not, the Action cannot connect either.

The Action passes the connection to psql through environment variables. The connection stays in your runner: it is never sent to the API, put on a command line or logged.

4. Add the workflow

Create .github/workflows/assure.yml:

name: Assure

on:
  pull_request:
  push:
    branches:
      - main
  workflow_dispatch:
  schedule:
    - cron: "0 3 * * 1"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write
    steps:
      - name: Set up Python 3.14
        uses: actions/setup-python@<full commit sha of the release you trust>
        with:
          python-version: "3.14"

      - name: Install the PostgreSQL client
        run: command -v psql || (sudo apt-get update && sudo apt-get install -y postgresql-client)

      - name: Assure check
        id: assure
        uses: Symbolia-Assurance/assure-action@beta
        with:
          profile: postgresql-observed-baseline
          connection: ${{ secrets.ASSURE_PG_CONNECTION }}
          collection-role: assure_collector
          collection-privileges: pg_read_all_settings,pg_read_all_stats
          fail-on: fails
          output: assure-verdict.json

      - name: Keep the verdict
        if: always()
        uses: actions/upload-artifact@<full commit sha of the release you trust>
        with:
          name: assure-verdict
          path: ${{ steps.assure.outputs.verdict-path }}

Use @beta on the Symbolia-Assurance/assure-action line. It moves to each new release when Symbolia publishes, so you get fixes without editing your workflow. A moving ref runs what Symbolia last published; every release is first served by production and reviewed before merge, and each release also has an immutable tag v0.1.0-beta.N.

To freeze, pin a full 40-character commit SHA of Symbolia-Assurance/assure-action in place of @beta; in a clone, git -C assure-action rev-parse HEAD prints it. Pin every third-party action to the full commit SHA of the release you trust. The source: line of skills/assure/VERSION names another commit: the Assure source commit the Action was built from. It is not a commit of the Action repository, so it never goes in a uses: line. The pin: line of skills/assure/VERSION says the same: the build cannot know which Action commit you pin, so it names none.

This workflow runs on every pull request, on every push to main, when you start it by hand, and once a week. Change main if your default branch has another name. A pull request from a fork gets no repository secrets from GitHub, so api-key is empty there and the Action stops with bad_input (exit 2). GitHub gives such a run no identity token either. With id-token: write under permissions: (section 1), you can leave out the api-key line. The template above already does: it signs in with the workflow's GitHub identity, so you store no key. To use a stored key instead, pass it to the step:

      - name: Assure check
        id: assure
        uses: Symbolia-Assurance/assure-action@beta
        with:
          api-key: ${{ secrets.ASSURE_API_KEY }}

A PostgreSQL your CI already starts. When your workflow runs PostgreSQL as a service container and loads your schema, check that server: add the same services: block and schema step to this job, then create the collection role (section 2) in a step before the check, with a password that exists only in CI. Give the connection inline, for example connection: host=localhost port=5432 dbname=postgres user=assure_collector password=<the CI-only password>. That password guards a database that lives only for the length of the job, so it is not a secret; for any other database, pass connection from a secret (the inputs table). Leave out data-dir and config-dirs: the runner cannot read the container's files, so each configuration file reads as a recorded gap (section 6, option c).

This workflow uses the intent-free profile, which needs no declaration. To check against a declaration you write, use postgresql-declared-model with collected files (section 9).

The runner must reach your database and api.symbolia.ai. For a database on a private network, use a self-hosted runner inside that network with outbound HTTPS.

Checks are free, so the workflow runs mode: api from the start. To list problems before the first check, you can run the Action once by hand with mode: lint, from a workflow that runs only on workflow_dispatch: it reads the same files, sends them to POST /v1/lint and lists every problem it finds in your files, profile, scope, requirements.md and HTTP heads. Never commit mode: lint to the workflow that runs on pull requests: a lint run checks nothing and exits 0 when it finds no problem. The Action collects and checks your files in the runner as for a check, then asks the API to read them. Each problem is a ::warning annotation and a line in the job summary; the lint record is written to output. The outputs are outcome (lint), exit-code (0 when nothing was found, else 2) and lint-findings (how many problems it found). It never runs a check and nothing is charged, but it counts against your rate limits. Fix what it lists, then run with mode: api.

Reading your first result

The first line of the job summary, and the Action's last log line, starts with a colour, then says how much was read, "N of 8 machines read, M refused", and the bounds of the result. A machine is one part of the check, such as client authentication or row-level security. A refused machine was not read, and the summary lists it under "Machines not read" with its reason. When a scope limit names machines the checker could not reach, they are out of scope, not refused, and the count ends ", n out of scope", for example "5 of 5 machines read, 3 out of scope": an out-of-scope machine leaves both counts, and the summary names the limit.

• green (exit 0): within these bounds, nothing disproven. For example "green: 7 of 8 machines read, 1 refused; declared premises: none (observed profile); version pins: major 18; nothing disproven; established: 3 of 40; deviations: 1; vacuous: 13; not established: 23 — top action: state it in requirements.md". A deviation is counted on its own. When no obligation on the machines read holds, the line says so in words: "nothing could be established (0 of N obligations hold); not established: n — top action: <action>". One line follows for each obligation that could not be established, "<id>: <reason> — <owner>: <what it needs>". Green never means more than this.
• red: something is disproven, for example "red: ...; disproven: <obligation> — <object>, <access path>, <locator>"; with more than one, "disproven: k, first <obligation> — …", and the free summary (GET /v1/checks/{id}/summary) lists the same k under disproven, each with platform_owned. It exits 1 when your fail-on names the status (fails by default) and the disproof is yours to fix. A fails reading whose findings are all platform-owned keeps the colour red with exit 0 and policy.reason platform_owned: the disproof is someone else's to fix. A fails reading on a read machine is red whatever fail-on says. A status you name in fail-on also turns the reading red and sets the exit. When your fail-on leaves a disproven status out, the exit is 0 and the line ends "(exit 0 by your fail-on: ...)". A status you chose to stop on that is not a verdict (for example fail-on: not_observed) is red with exit 1 and reads "stopped by your choice: not observed — <obligation>", never "disproven".
• yellow (exit 3): nothing could be read at all, "yellow: could not look: <reason>; <action>", for example "yellow: could not look: the input could not be represented; re-collect with the pinned collector". The summary prints the reason and the file it names under it. A typed outcome that stopped the check before any reading also exits 3. Yellow is a check run's action_required where a check run is published with checks: write; this Action publishes none, so it falls back to exit 3, which fails the job.

On the free plan, one upgrade line sits above that first line, at the very top of the summary: it names Premium and links to a checkout page already filled in with your account. When your free balance is spent, the line starts with one sentence that says so.

Under the first line, one sentence says what it means in plain words. For a green PostgreSQL run: "Nothing in your database configuration contradicts what is known about safe PostgreSQL setups. 21 of 41 checks could not be completed, mostly because they depend on what the system is for, which has not been stated. That is a gap in what we could see; your database configuration is unchanged by it." For red, the consequence of what was disproven and where; for yellow, that nothing below is a finding and what to do. Each disproven or deviating obligation is listed under "Why it matters" with its statement and its consequence ("Consequence not yet stated for <obligation>." until the profile states one).

When you name a file in the requirements input, the first line adds "requirements: h hold, n not established[, d disproven]", the summary lists each requirement under the not-established list with its sentence, "R3 — "<sentence>" — not established — missing method — <action>", and the outputs requirements-not-established and requirements-disproven count them. A disproven requirement turns the run red (VERDICTS.md, section 10). A requirement checked with http-observed-baseline cannot hold today: the HTTP check does not yet carry a verified method and path for each endpoint, so a matched HTTP requirement reads not established with the reason class missing_identity_binding. mode: local does not read requirements.md: requirements are checked in mode: api only, and a local run that finds one says so in one notice.

FIRST-LINE-SAMPLES.md shows one first line for each colour, word for word, with the meaning sentence for each colour and profile. FIXTURES.md, in docs/customer/ of the Assure repository (a document the Action tree does not ship), lists for each profile the committed fixtures, the first line a development check of each one reads, sample verdicts (one with refused machines) and a sample declaration for each declared profile.

A refused machine bounds the result and is named; a status you name in fail-on on its rows stops the job as on a read machine, and a reading the checker kept on it is read as not observed. allow-partial is still accepted and no longer changes anything.

Under the first line, the summary lists every reading under its status, each with its text: why it holds, why it fails, or what could not be read. The verdict file holds the same readings with their premises (VERDICTS.md). The Action keeps it at the output path; the workflow above uploads it as the assure-verdict artifact.

If a reading looks wrong, send a wrong_reading note through the feedback route, within the customer's permission, naming the check id, obligation and expected reading. Never send your configuration files or your connection string. Never send your API key in the note.

Upgrade to Premium (USD 20 a month)

Accounts start on the free plan. Premium (usd_20, USD 20 a month) adds checks of your app's sign-in and session routes, not only the database; paid formalisation of requirements no method states yet; and one monthly pool of USD 20 of usage that reports, formalisation and proof search share.

To pay, open the Premium Payment Link with your account id appended as client_reference_id, as the upgrade line at the top of a free account's job summary does: https://buy.stripe.com/<link>?client_reference_id=<your account id>. You can read your exact link before your first run: on the free plan, GET /v1/usage carries upgrade, {"url": "…", "line": "…"}, the same link and sentence a free account's verdict carries. When the payment completes, your account moves to Premium; no other step is needed. A paid plan's answer never carries upgrade, and while Symbolia has set no Payment Link no answer does: then ask Symbolia for a checkout link.

5. Inputs

6. Managed PostgreSQL and configuration files

Some facts live in configuration files: postgresql.conf and the files it includes, postgresql.auto.conf, pg_hba.conf, pg_ident.conf and postmaster.opts. The collector finds them through the server's own settings and reads them from the runner's filesystem.

With a connection and no data directory, the runner cannot read those files. This is the usual case for managed PostgreSQL. A reading that needs a fact from a file then reads not observed. Where the checker cannot represent the input without the file, as with a missing pg_hba.conf or postgresql.conf, the readings that use it read representation. When pg_hba.conf was not collected but the collection role can read pg_hba_file_rules (the server's own parse of the file), the checker reads the client-authentication rules from that view and cites raw/catalog_snapshot.json#pg_hba_file_rules; a collected pg_hba.conf wins over the view. The client-authentication and TLS obligations are the ones most affected.

To read the files, run the Action on a self-hosted runner that can read them:

• data-dir: the server's data directory, as the runner sees it.
• config-dirs: directories that hold configuration files outside the data directory. The Debian and Ubuntu packages keep them in /etc/postgresql/<major>/<cluster>:

data-dir: /var/lib/postgresql/18/main
config-dirs: /etc/postgresql/18/main

Give one directory per line, or separate them with colons. A path that holds a colon cannot be given here.

The collector reads files only inside data-dir and config-dirs.

The collector does not copy some include targets. It records each one as "not copied", and the readings that need it read not observed or representation. These are an absolute include_dir in postgresql.conf, any absolute include in pg_hba.conf or pg_ident.conf (an include, include_if_exists or include_dir line on PostgreSQL 16 and later, or an @file name), and a relative include that leads above the directory of the main file (postgresql.conf, pg_hba.conf or pg_ident.conf). An absolute include or include_if_exists in postgresql.conf is copied.

Letting the runner read the server's configuration files

The collector asks the server where each file is (config_file, hba_file, ident_file, data_directory) and reads each file at that path. One path is moved: a file inside the server's data directory is read from data-dir instead. A file outside the data directory, such as Debian's /etc/postgresql/18/main/pg_hba.conf, is read at the server's own path, which must lie inside config-dirs.

By default the runner cannot read these files. The data directory is mode 0700, and pg_hba.conf and pg_ident.conf are 0640, owned by postgres. There are three ways forward. The examples use Debian or Ubuntu, PostgreSQL 18 and a runner user named runner.

(a) Run on the database host, with the runner in the postgres group. Put the data directory in PostgreSQL's group-access mode (the same as initdb --allow-group-access), with the server stopped, and add the runner user to the group:

sudo systemctl stop postgresql@18-main
sudo chmod 0750 /var/lib/postgresql/18/main
sudo chmod -R g+rX /var/lib/postgresql/18/main
sudo systemctl start postgresql@18-main
sudo usermod -aG postgres runner

Restart the runner service so the new group applies. With the data directory at 0750 when the server starts, PostgreSQL writes postgresql.auto.conf and postmaster.opts group-readable (0640) from then on; pg_hba.conf and pg_ident.conf are already 0640 postgres:postgres. Inputs: data-dir: /var/lib/postgresql/18/main and config-dirs: /etc/postgresql/18/main. This gives every file, always current. The cost: the group also reads every table file in the data directory. Prefer (b).

(b) Give the runner copies, or read access to these files only. Copy the files inside the data directory to a directory the runner reads, and pass it as data-dir. Leave the files under /etc where they are, and give the runner read access to the two that it cannot read:

sudo install -d -m 0750 -o root -g runner /srv/assure-pgdata
sudo install -p -m 0640 -o root -g runner /var/lib/postgresql/18/main/postgresql.auto.conf /var/lib/postgresql/18/main/postmaster.opts /srv/assure-pgdata/
sudo setfacl -m u:runner:r /etc/postgresql/18/main/pg_hba.conf /etc/postgresql/18/main/pg_ident.conf

Inputs: data-dir: /srv/assure-pgdata and config-dirs: /etc/postgresql/18/main. In the Debian layout, postgresql.conf and the conf.d include directory are usually readable by every user; check with ls -l. -p keeps each copy's modification time. The runner reads these configuration files and nothing else. The cost: the copies go stale. Copy again after ALTER SYSTEM (which rewrites postgresql.auto.conf) and after a server restart (which rewrites postmaster.opts), and set the ACL again if an editor replaces pg_hba.conf. Copying the files to some other directory and naming it in config-dirs does not work: the collector looks for each file at the path the server reports.

For a runner on another host, put the copies at the same paths the server uses, and the data-directory files in the data-dir copy. Run this on the runner host, in a directory that holds copies of the server's files:

sudo install -d -m 0750 -o root -g runner /etc/postgresql/18/main /etc/postgresql/18/main/conf.d /srv/assure-pgdata
sudo install -p -m 0640 -o root -g runner postgresql.conf pg_hba.conf pg_ident.conf /etc/postgresql/18/main/
sudo install -p -m 0640 -o root -g runner conf.d/*.conf /etc/postgresql/18/main/conf.d/
sudo install -p -m 0640 -o root -g runner postgresql.auto.conf postmaster.opts /srv/assure-pgdata/

When the server keeps every configuration file in its data directory (the layout initdb writes), copy all of them, with any include directory at its relative path, into the data-dir copy, and leave out config-dirs.

(c) Managed PostgreSQL. The runner has no access to the server's files. Leave out data-dir and config-dirs. Every reading that needs a file reads not observed or representation, with the file named. The readings from the catalog still come back.

Managed PostgreSQL and connection poolers

Some managed services put a connection pooler in front of the server, and the pooler routes on the login name. Supabase's pooler, for example, takes the login name assure_collector.<project-ref>; inside the database the role is assure_collector.

• The user in connection is the login name. Keep it as the service gives it.
• collection-role is the role's name inside the database. The collector checks it against current_user and session_user. When it is not set, it is the user in connection.

When the two differ, the Action logs in with the login name and the collector checks the role. If you leave collection-role unset behind such a pooler, the collector refuses with collection_role_mismatch (collector_refused, exit 3), and the reason says which name to set.

On Supabase, the postgres role cannot grant pg_read_all_settings or pg_read_all_stats. It can grant pg_monitor, and the collector this Action ships refuses pg_monitor as broader than it needs (section 2). So this Action version cannot collect from a Supabase database.

Use the session pooler. Assure has run through Supabase's session pooler on port 5432. The collector runs each query in its own psql process, one short session per query; a transaction pooler has not been tested.

The collector asks for a read-only session. A pooler may not pass the request on: through Supabase's session pooler the session was not read-only. The collector runs only fixed SELECT statements either way. The job summary states whether the session was read-only (section 8).

The runner cannot read a managed server's configuration files, so the readings that need them read not observed or representation, as above.

7. The fail-on policy and exit codes

fail-on is a comma list of words, or the single word never. The Action sends it as you wrote it. The API checks every word against the profile and applies it. A word the profile cannot emit is bad_input, and the reason lists the words that profile accepts. GET /v1/profiles lists them too.

The words a profile accepts:

• any status the profile can emit except holds and vacuous;
• not_collected: every status the profile uses for a fact it could not read or represent;
• never, on its own: readings never fail the job, except a prove-class obligation that is not proven (exit 1, not_proven).

needs_intent is outside not_collected: it marks a norm that depends on what the system is for, which is out of scope by design. Name it on its own to fail on it.

Examples:

• fails (the default): the job fails when any obligation reads fails.
• fails,deviates: the job also fails on a deviation from vendor guidance or from the Assure baseline (observed profile).
• fails,not_collected: the job also fails when a needed fact was not collected or could not be represented.
• never: readings never fail the job, except a prove-class obligation that is not proven, which exits 1 (not_proven). A typed outcome still does.
• unresolved-security (strict, never the default): fails, and also every obligation the checker marks security: true that is not resolved, that is, has no verdict on a machine that was read. Such an obligation turns the run red with "unresolved by your choice (strict): <id> — <reason>; <action>", and each obligation that could not be established is also a notice annotation. The observed PostgreSQL profile marks 37 of its 41 obligations security: true (authentication, authorisation, privilege, definer context, replication and transport); there strict stops the job on any of them that has no verdict, and the first line says "strict: n of m security obligations observable at this pin". The declared PostgreSQL profile marks 4 of its 40 obligations security: true (M5 RLS-1 to RLS-4, the row-level security rows); there an unresolved RLS row on a machine that was read turns the run red, and the first line says "strict: 4 of 4 security obligations observable at this pin". The HTTP profile marks none, so there strict is a no-op and the first line says "strict: no obligations marked". Only the security obligations the pinned collector can observe count in n and m: an obligation the profile marks observable_at_pin: false is listed as not established, "not observable at collector pin <pin>", and the first line says "strict: n of m security obligations observable at this pin". An intent-bound obligation (class: intent_bound) depends on what the system is for, which no collector observes. All security obligations without a verdict bind under strict, including one the pin cannot observe; the report names each and why. An intent-bound one is named "unresolved by your choice (strict)", reads "depends on what the system is for" and has the action "state it in requirements.md". n and m count observability only: an intent-bound obligation never counts in them and is never listed as not observable at the collector pin; m counts the intent-free security obligations.

Each obligation has a class its profile declares, never settable per run, and GET /v1/profiles lists it: refute (green unless disproven) or prove (red unless proven). A prove-class obligation that does not read holds on a machine that was read turns the run red, "not proven: <id> — input not observed" when its input could not be read, else "not proven: <id> — <reason>; <action>", and the first line states "prove-class obligations: p (unproven: u)". Every obligation of today's profiles is refute-class.

The Action exits with the verdict's own policy exit, policy.exit in the verdict file. policy.reason says why, in one word. The job summary states the policy and this run's exit in plain words.

A reading with a status you fail on gives exit 1 whatever could not be read, with one exclusion. A fails reading sets exit 1 only when at least one of its findings has owner_class app or unknown, or it carries no findings at all: one whose findings are all platform or extension is platform-owned and excluded from the exit (platform_owned). A fails reading on a read machine is red whatever fail-on says. A status you name in fail-on also turns the reading red and sets the exit. allow-partial no longer changes the exit. The input-integrity gate gives 3 under every policy except never.

A vacuous reading only says that a domain was empty. A run whose only verdicts are vacuous reads "No verdicts" in the summary, and its first line says "nothing could be established".

The first line counts the machines read out of every machine the profile checks, "5 of 8 machines read, 3 refused" (", K refused" only when a machine was refused): a machine that gave no reading at all is listed as refused with the reason "no readings for this machine". When Assure worked the list out from the readings because the checker did not report it, the count ends "(inferred)". The bounds follow: "declared premises: n" (premises you declared; "none (observed profile)" for an observed profile that has none) and "version pins: major 18" (the server's observed major; "none" when the readings name none). Under the meaning sentence, the summary answers three questions in three short sentences, "Usable readings: u of n. Coverage complete: yes or no. Job stops: no (exit 0 by your fail-on), or yes (exit 1).", followed by the collection time and the loaded state when the collector records them, and lists the obligations the profile version cannot yet check (representation, missing method) under their own heading, "Unsupported by this profile version: n".

If the checker itself fails, the result is the typed outcome checker_error (exit 3) under every policy, never included. For an API check, read the result's charged: failures after the checker started, including checker_error, checker_timeout, checker_cpu_limit and checker_memory_limit, are charged unless the answer states an explicit no-charge decision. A refusal before admission, the checker's own internal error (checker_error whose detail.rule is internal_error), a server restart, and a malformed python-auth-declared-model bundle refused by its free pipeline are not charged. Local verdicts and failures say charged: false; that field is a check accounting flag, not an amount spent. A request refused before the checker starts is never charged, and neither is a check cut short by a server restart; it still counts against your rate limits. A result is returned whenever one can be produced: when the checker's output for one machine is malformed, that machine is listed under "Machines not read" with its reason (malformed_output: ..., or server_fault: ... when the server could not write it) and the other machines keep their readings. When no result can be produced, the failure's detail.malformation says what was malformed: a fixed kind, the file, the line, the field and the expected form, never your text.

The Action sets five outputs: verdict-path, outcome, exit-code, colour (green, red or yellow; a failure is red for bad input or a bad key, exit 2, and yellow otherwise) and not-established (how many obligations could not be established; empty for a failure). When a requirements file was sent, it adds requirements-not-established and requirements-disproven. On the observed profile, when the Action writes assure-requirements-draft.md, it adds requirements-draft, that file's path (empty when nothing was drafted).

8. Where the results appear

• The verdict file. JSON at the output path, schema assure.serve.verdict/v1. It holds every reading with its premises. See VERDICTS.md.

• The job summary. A table of counts by status, then one line per obligation. It appears on the run page. When the collector recorded the collection session, the summary ends with two lines, as the server reported them for that session:

  • The collection session was read-only: yes, no or not recorded;
  • TLS to the server: yes (<protocol>, <cipher>, <bits> bits), no or not recorded.

  Behind a connection pooler they describe the pooler's session to the server, not your runner's connection to the pooler. The job log carries the same two lines.

• The declaration proposal. On the observed profile (postgresql-observed-baseline), the Action writes assure-declaration-proposal.json beside the verdict file. It is a declaration drafted from your own catalog snapshot, in the runner, from the files already collected and withheld; nothing more is sent. Its declaration object validates as raw/declaration.json for postgresql-declared-model. Each value names where it came from in sources, and a key the snapshot gives no basis for is marked unread and left out. The keys in confirm are judgements: check each one, then merge the pull request Assure opens for it, or commit it as .assure/postgresql-declared-model.json (or .assure/declaration.json) in the checkout (raw/declaration.json in an artefacts directory), and the next check reads it (the declared reading below) to decide the rows that need intent. Inside a git checkout with nothing at .assure/postgresql-declared-model.json or .assure/declaration.json (a link at either path is not committed intent and is passed over), or with a file at .assure/postgresql-declared-model.json whose JSON differs from this run's draft, and a workflow token, the Action proposes (in mode: api and mode: local alike) the draft at .assure/postgresql-declared-model.json in a pull request of its own from assure/declaration-proposal (as for postgresql-declared-model: drafted from the collector's own snapshot before the withholding, so the draft holds your own literals and reads the same after you merge it); the job needs contents: write and pull-requests: write for it. Its body leads with "Assure drafted .assure/postgresql-declared-model.json from the collected catalog snapshot. Merging it commits the declaration; the next check then also reads postgresql-declared-model beside this reading, to decide the N rows that need intent.", N being the rows that need intent, then each key to confirm with where it was read. With contents: read (the jobs above, or a pull request from a fork) the push is refused with no warning (one plain log line), and the files and the section below stay as they are. When the branch is pushed but the pull request cannot be opened (no pull-requests: write), the summary says not proposed (…); the draft is below and shows the draft as withheld (the declaration object of assure-declaration-proposal.json), so a literal of your policies never reaches the job summary. When withholding left that draft unchanged (no literal of your policies in it), a "Commit this draft" link sits above it: GitHub's new-file page on the branch the proposal targets with the draft prefilled at .assure/postgresql-declared-model.json, byte for byte; otherwise no link is shown. The job summary adds one section, "Assure drafted a declaration from your database: N leaves proposed, M to confirm — commit it as .assure/declaration.json (with a connection; raw/declaration.json in an artefacts directory) and run postgresql-declared-model to decide K rows that need intent.", and each needs_intent row's next step names Assure's pull request and the file. Once Assure's pull request is open, the section says "merge Assure's proposal pull request; the next check then also reads postgresql-declared-model beside this reading, to decide K rows that need intent." instead, and no longer says "A proposal changes no reading": it says that the verdict, its file and the exit never change and that the pull request adds no output. The proposal changes no reading or exit of this run; the one output it adds is requirements-draft. No file is written when the collector's sidecar names no server major from 14 to 18.

• The declared reading. On postgresql-observed-baseline with a declaration committed at .assure/postgresql-declared-model.json (where its proposal pull request puts it) or .assure/declaration.json in the checkout, the Action also checks postgresql-declared-model on the same collected bundle with that file as raw/declaration.json (the first of the two present, in that order; the line and the section name the file read), its declared_predicate string literals withheld in the same numbering as the snapshot's before the check reads or sends it (the log says "Assure: declared check: Withheld in the runner …", then "Assure: declared reading: postgresql-declared-model, with" and the file read, once the check returns a verdict); the bundle is not withheld a second time (in mode: api a second submitted check, charged as a second check; the summary then says "two checks charged"). No workflow input changes: the declared check runs under the words of your fail-on that postgresql-declared-model accepts (an observed-only word such as deviates or needs_intent is left out; with none left, fails), and its exit is informational. The job summary's first line (on the free plan, the line under the upgrade line) and the verdict's first notice (the first ::notice after the check) then read both, for example **Assure: decided 27 of 69 rows across both readings** (postgresql-observed-baseline 19 of 55; postgresql-declared-model 8 of 26, with `.assure/declaration.json`). N counts the row ids decided (holds, fails or deviates) in either reading, never a row a reading kept on a machine it reports refused (that row reads not observed, as on every surface); M counts the ids in either. The section "### Declared reading (postgresql-declared-model, with .assure/declaration.json)" (with the path read) holds that verdict's summary, its headings one level deeper. The verdict file, the outputs, colour and the exit stay the observed reading's: the declared reading is informational until you set profile: postgresql-declared-model. A declared check that is refused or fails, or a declaration that cannot be read (not a regular file; a link at the path is passed over, as if absent), keeps the observed verdict and exit and reads "declared reading: not measured (the reason)" in that section, never a count.

• The requirements draft. Beside it, assure-requirements-draft.md holds the goals the proposed declaration lets Assure check, one plain sentence each (for example "Each user sees only their own data."), then lists the keys the snapshot gives no basis for. When no table was proposed as protected, or one was left out because its own policy opens every row, a ## Templates section offers two fill-in lines: row-level security on each user-data table with a policy keyed on the caller (RLS-1 and RLS-2) and the ownership check on inserts and updates (RLS-3), with <tables> (the open tables suggested) and <caller predicate> (for example auth.uid() = id) for you to fill in; the snapshot carries no column names, so Assure cannot pick the tables itself. Keep a filled line as a goal (- and the sentence) and the Action sends it as those checks; state the same tables and predicate as protected_tables and declared_predicate in the declaration, or those checks are not established. assure-requirements-typed.json beside it holds the checks under each goal: each goal pinned by its sentence's sha256 to the exact statements the check establishes, each with a specific sentence (for example "Only postgres may hold superuser.") and the snapshot rows it came from. Confirm each goal, then commit the draft as requirements.md and the typed file beside it, unchanged. In api mode the Action sends each goal you kept as written as its checks, and the job summary reads each goal back: "holds for N of M checks", with how many are not decided yet, or "broken:" with the specific sentences that fail. A goal you change is checked as written, and the summary names the lines changed since they were compiled. The Action uploads assure-requirements-draft.md as the assure-requirements-draft artifact of your own workflow run, in GitHub's artifact storage; the "Declaration proposal" section of the job summary links the run's artifacts. A second check in the same workflow run replaces that artifact, and an upload that fails is reported in the job log without failing the Action: the Action's exit stays the verdict's. Assure does not receive it.

• Annotations. The first line is the first notice annotation. With a declared reading, that first line is the both-readings line above and the observed first line is the next notice. Each fails reading is an error annotation. Each deviates reading is a warning annotation; on postgresql-observed-baseline an M6 one (such as SD-1-OB) also names up to five of the functions it read, with their count and login roles. Under strict, each obligation that could not be established is a notice annotation. At most 50 of each appear.

When no obligation reaches a verdict, the summary says "No verdicts" and the first line says "nothing could be established". It never means "no issues".

Text from the checker or your files is shown as plain text. A web address in it appears as code, never as a link.

The report

The report is opt-in: set report: true in mode: api to ask for it; unset or report: false skips it. It is a plain-language report of the claim tree behind a verdict: what was checked, what holds, what fails and why, and what the check could not decide. mode: local never asks for one. Every plan served today includes the report: a free account draws it from the USD 1 free balance granted with its key or at its GitHub sign-in, and without that grant the API refuses it with allowance_exhausted; tier_excludes is reserved for a plan that excludes the report. A language model writes it from the verdict's record alone, never from your files. A deterministic check then reads it against the record, and a report that fails a fact rule of that check is withheld. A report that passes every fact rule is served as written, even when it misses a style target. Reports are written for postgresql-declared-model verdicts today; for other profiles the report is withheld and says so.

• Written. The job summary carries the first line, then the report, then a line naming the report page. The page shows the claim tree with each rule's check id, status, reason and evidence. Open it with your API key in the Authorization header. The report-url output holds its address.
• Withheld or refused. The job summary carries the usual summary and one more line: "The report was withheld: <reason>." A refused report adds one warning annotation, never an error.

The report never changes the verdict, the verdict file or the exit code. The first line and the verdict file stay the record. The report-status output reads written, withheld, refused, or running when the report was still being written as the Action stopped waiting; the summary and report-url then name its page, to open later. DATA.md says what is sent to the writer and how long a report is kept.

What a report costs. Premium and Pro each have one monthly pool, USD 20 and USD 200 of usage a month, at the same rate as overage (cost x 1.2), which reports share with formalisation and proof search. On Premium and Pro the default report draws that monthly pool first, then any top-up. Overage is off until you set a budget: past the pool and your top-up, a report is refused until the reset, even with allow-overage. With a budget, the part beyond the pool is charged at cost x 1.2, up to that budget. The free plan has a balance of USD 1, granted once: per verified email for an account with an API key, and per GitHub owner at its GitHub sign-in; reports and requirement compiling share it, and it does not renew. A report is paid from it at its real cost, and reports stop while the balance is below zero. A recharge clears what is owed, and the rest goes to your account's top-up. A report within the allowance or the balance is not charged. The part of a report's cost beyond it is charged at cost x 1.2. Before a report runs, the API holds its expected cost (the high end of its quote) against your allowance and top-up, so two reports never share the same cover. A report that would go beyond the allowance runs only when your account has an overage budget and you set allow-overage: true, or when your account's top-up covers the hold. Otherwise the API refuses it with allowance_exhausted: nothing runs and nothing is charged, and the summary reads "Report: allowance exhausted: USD q needed; set allow-overage or top up", or, when your account has no overage budget, "Report: allowance exhausted: USD q needed; top up, or ask Symbolia to set an overage budget", or, when your budget is spent for the month, "Report: allowance exhausted: USD q needed; ask Symbolia to raise your overage budget, or top up". Without allow-overage, a report is never charged more than its hold, even when the model cost more. A free report beyond what is left of the balance is refused allowance_exhausted whatever allow-overage says. One job's quote can be at most USD 50 unless you ask Symbolia to raise your account's job ceiling; the quote comes first. A report whose quote is above it is refused job_ceiling, even with allow-overage. Each plan also has a daily report cap (daily_report_cap), which counts the reports that ran. While Assure is in beta a withheld report is not charged. Asking again for a report you already have returns the same record at no cost. The summary adds one line, "Report: cost USD x.xxx, charged USD y.yyy, allowance remaining USD z.zz", and the outputs report-cost-usd, report-charge-usd and report-allowance-remaining hold the same figures. A run that repeats an earlier request gets the earlier check and its stored report back, so the report line and the report-cost-usd, report-charge-usd and report-allowance-remaining outputs repeat the first run's figures, though this run charged nothing. The API does not yet mark a repeat, so to add up what you were charged, read GET /v1/usage, not these outputs.

Allowance notices. When a usage line reaches 75, 90 or 100 % of its monthly allowance since your last check, the job summary adds one line, for example "Report allowance: 90 % used (USD 4.50 of 5.00); resets 1 Nov; past the limit: metered at cost x 1.2". With no overage budget, or a budget of 0, it reads "past the limit: hard stop (overage budget USD 0.00)", and a report beyond the allowance and your top-up is refused until the reset. The overage budget limits only the part of a charge that your top-up does not cover, so a top-up stays spendable under a budget of 0. The free report balance does not renew, so its line reads "does not renew" where a monthly line reads its reset, adds ", and USD x is owed" when the balance is below zero, and ends "past the limit: reports stop".

9. Using collected files instead of a connection

You can collect on one machine and check from another. Set artefacts to a directory that holds a raw/ folder (or to the raw/ folder itself). Leave connection empty.

The directory must hold files under the names the profile reads. The API lists them for each profile (GET /v1/profiles). Files with other names stay in the runner and are listed in a notice. A symbolic link at an expected name is refused.

Give the collector's output directory as it wrote it. The collector writes raw/ and, beside it, COLLECTION-SIDECAR.json and TIMING.json. The Action takes those two files from beside raw/ (or from inside raw/, if you moved them there) and sends them as raw/COLLECTION-SIDECAR.json and raw/TIMING.json. If both places hold a copy and the copies differ, the Action stops with bad_input. Do not leave out COLLECTION-SIDECAR.json: it is the collector's record of which lines it withheld whole and why. A configuration file that holds a line the earlier collector withheld (# [collect_pg: line withheld, ...]) cannot be checked without it, so the Action stops with collector_refused and sends nothing: a collector output without its sidecar cannot be checked.

Keep REDACTION-MANIFEST.json too. The collector writes it beside raw/ in the same run as the sidecar. It records the digest of each file as the collector wrote it, and what the collector withheld. When a file holds a withheld line, the Action uses it in the runner to check that the sidecar belongs to these files: the file must be unchanged since collection, and the manifest and the sidecar must record the same withheld lines. If the manifest is missing, records a different digest for such a file, or disagrees with the sidecar, the Action stops with collector_refused and sends nothing. Records from another run are caught only when a file that holds a withheld line differs, byte for byte, from that run's file. Records kept from an earlier run of the same server pass if the withheld lines sit at the same places with the same marker, even where a line that was a comment is now a rule. So always use the sidecar and manifest written by the same collector run as raw/. The manifest stays in your runner; it is never sent. With the collector this Action ships, a withheld rule or setting is a marker line that names its own line number and reason, so records from another run cannot hide it: the check reads that line as not observed whatever the records say. That collector's sidecar is recognised by its own fields; a collection that mixes its output with the earlier collector's stops with collector_refused. The earlier collector withheld a pg_hba.conf rule with a quoted name, an @file list or a regular-expression user whole, so its files stop there with collector_refused; collect again with this Action.

Line continuation in pg_hba.conf (a line ending in \) depends on the server's major version. If raw/declaration.json gives a major on the other side of 16 from the one the sidecar records, and a pg_hba.conf line ends in \, the Action stops with bad_input. Set the declaration's major to the server's major.

The declared profile, postgresql-declared-model, reads your declaration from raw/declaration.json (and optionally raw/clients.json) beside the collected files. DECLARATIONS.md explains how to write it, validate it for free locally, and review its assumptions and coverage gaps:

      - name: Assure check from collected files
        uses: Symbolia-Assurance/assure-action@beta
        with:
          api-key: ${{ secrets.ASSURE_API_KEY }}
          profile: postgresql-declared-model
          artefacts: collected
          fail-on: fails

Bringing the folder to the runner

The Action reads artefacts from the runner's working directory. Put the folder there before the Assure step, in one of three ways:

• Committed to your repository. Add a step with actions/checkout, pinned to a full commit SHA. The complete workflow is below.
• Made by an earlier job. That job uploads the folder with actions/upload-artifact; the job that runs the Action fetches it with actions/download-artifact in place of the checkout step.
• Collected in the same job. Fetch the collector and run it in a step before the Assure step, as in "Running the collector yourself". The runner must then reach your database.

Committing the folder puts what it holds into your repository's history: role names, ACLs, pg_hba.conf rules with client addresses, and the other items DATA.md lists as sent as written. Commit it only where everyone who can read the repository may read those.

A complete workflow for the intent-free profile, with the collector's output committed as collected/:

name: Assure

on:
  pull_request:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Check out the repository
        uses: actions/checkout@<full commit sha of the release you trust>

      - name: Set up Python 3.14
        uses: actions/setup-python@<full commit sha of the release you trust>
        with:
          python-version: "3.14"

      - name: Assure check from collected files
        id: assure
        uses: Symbolia-Assurance/assure-action@beta
        with:
          api-key: ${{ secrets.ASSURE_API_KEY }}
          profile: postgresql-observed-baseline
          artefacts: collected
          fail-on: fails
          output: assure-verdict.json

      - name: Keep the verdict
        if: always()
        uses: actions/upload-artifact@<full commit sha of the release you trust>
        with:
          name: assure-verdict
          path: ${{ steps.assure.outputs.verdict-path }}

For the declared profile, set profile: postgresql-declared-model and commit your declaration as collected/raw/declaration.json.

For a folder made by an earlier job, this step takes the place of the checkout step:

      - name: Fetch the collected files
        uses: actions/download-artifact@<full commit sha of the release you trust>
        with:
          name: collected
          path: collected

The earlier job uploads the whole folder as the collector wrote it, under the name collected. The job that runs the Action names the collecting job in needs:, so it starts only after the upload; without it the two jobs run at the same time and the download finds nothing:

  check:
    needs: collect
    runs-on: ubuntu-latest

Running the collector yourself

The collector is action/collector/collect_pg.py in the Symbolia-Assurance/assure-action repository. Use it at the same ref as your uses: line. Fetch it on a machine that can reach the server and has Python 3.14 and psql:

git clone https://github.com/Symbolia-Assurance/assure-action assure-action
git -C assure-action checkout beta

Set the standard libpq variables for the server (PGHOST, PGPORT, PGDATABASE, PGPASSWORD, PGSSLMODE). Find the data directory first: ask the server with psql -c 'SHOW data_directory' ("A server on your own machine", below), and give that directory, as this machine sees it, in place of <data directory>. Then run:

python3.14 -B assure-action/action/collector/collect_pg.py --out collected \
  --role assure_collector \
  --privileges pg_read_all_settings,pg_read_all_stats \
  --data-dir '<data directory>' \
  --role-created-for-run yes

The collector logs in as --login-user, or as --role when that is not given. The collector never asks for a password: give it in PGPASSWORD, or in a password file psql reads.

It prints one line of JSON and exits with one of four codes:

With the two roles of section 2, a collection usually ends with exit 1: the role cannot read the catalog views that only a superuser may read, pg_hba_file_rules and pg_file_settings and, from PostgreSQL 15, pg_ident_file_mappings, and each view it cannot read is a gap with the status unreadable. The collector still reads the configuration files themselves inside --data-dir and --extra-root.

The refusals name the reason in their type: for example collection_role_superuser, collection_role_not_read_only or collection_role_not_least_privilege for a role section 2 does not allow, collection_role_mismatch when the role you connect as is not --role, unsupported_major outside PostgreSQL 14 to 18, and redaction_selfcheck_failed when its own check found a withheld value in its output. Recreate the role as in section 2, or fix what the reason names, and run it again into an empty directory.

A server on your own machine

For a PostgreSQL server on the machine you collect on, ask the server where its files are, as the user you normally connect as:

psql -c 'SHOW data_directory'
psql -c 'SHOW config_file'
psql -c 'SHOW hba_file'

Give the data directory as --data-dir. When config_file or hba_file lies outside it, give that file's directory as --extra-root. Homebrew on Apple silicon keeps the data directory at /opt/homebrew/var/postgresql@<major>, and Postgres.app at ~/Library/Application Support/Postgres/var-<major>; check with SHOW all the same.

Read the pg_hba.conf that SHOW hba_file names. Where its local lines say trust, the role needs no password; create it without one:

CREATE ROLE assure_collector LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
GRANT pg_read_all_settings, pg_read_all_stats TO assure_collector;
GRANT CONNECT ON DATABASE <your database> TO assure_collector;

In these statements <your database> is the name of the database to check, or postgres for a local server that holds no other database.

Otherwise create it with a password as in section 2. The collector never asks for a password, so set PGPASSWORD for the collector's run only, and unset PGPASSWORD afterwards. Test the role first; it prints assure_collector:

psql -U assure_collector -d <your database> -c 'SELECT current_user'

When psql is not on the path, as with a Homebrew server whose client is not linked, tell the collector where it is: --psql /opt/homebrew/opt/postgresql@<major>/bin/psql.

When you have finished collecting, drop the role, as the user that created it:

REVOKE CONNECT ON DATABASE <your database> FROM assure_collector;
DROP ROLE assure_collector;

To collect again later, create it again.

Collecting again after a change

A check on collected files reads the server as it was when you collected. After you change the server (a setting, a pg_hba.conf rule, a role or a grant), collect again. --out must be a new or empty directory, so remove the old output first, then run the collector as above and commit the new folder:

rm -rf collected
python3.14 -B assure-action/action/collector/collect_pg.py --out collected \
  --role assure_collector \
  --privileges pg_read_all_settings,pg_read_all_stats \
  --data-dir '<data directory>' \
  --role-created-for-run yes

Keep raw/, COLLECTION-SIDECAR.json and REDACTION-MANIFEST.json from the one new run together. Running the workflow again without collecting again sends the same files: it gets the stored verdict of the first run back, and it says nothing about the change.

The Action makes one check per distinct request. It derives its Idempotency-Key from the content of the request: a digest of the bundle's files, the profile, the selected scope and its binding, the requirements text, the repository and the commit sent with it, and the allow-partial word as sent. A later run whose request is the same, byte for byte, gets the stored verdict of the first run back, and it is not charged again. A changed byte in any file is a new check. So is a new commit or a changed requirements.md, even when the files are the same. A changed fail-on is the same check: fail-on is applied at render on the stored verdict, so each run's exit follows its own fail-on, and nothing is charged again. The Action sends fail-on in one canonical form in both modes, its words in lower case, without spaces, each once and sorted, so fails,deviates, fails, deviates and deviates,fails are one policy.

A collection from a connection is never the same twice: the collector records when it collected and how long each query took. An HTTP check is never the same twice either: the Action makes a fresh identity key for each job, so the endpoint tokens differ from run to run. A stored verdict comes back when artefacts holds a collected bundle with the same files as an earlier run on the same commit, for example when you run a job again.

A stored failure comes back the same way only when it was charged. A failure that was not charged, a timeout, an unexpected server fault or a restart keeps no key, so running the job again checks again. To check the same bundle again on purpose, set fresh-check: true: the Action then sends a random key, and the check runs and is charged again. The server keeps a key for as long as the verdict it points to (30 days).

When the verdict is the stored one, the job summary says so under its first line, with the time of the first check, and that nothing was charged this run. A report that comes back stored sets report-charge-usd to 0, and its line names what the first check was charged.

10. Typed outcomes

When the Action cannot produce a verdict, it writes a failure file at the output path (schema assure.serve.failure/v1) with outcome, charged, reason and action. In mode: api, charged is the one the server's failure envelope stated, copied as is. It is false when nothing reached the server (refused before a check was sent, or mode: local, which never contacts the API and charges nothing), and null when a check reached the server but the Action could not read what it charged (for example api_unreachable after the 202, or an older server whose envelope has no charged): read GET /v1/checks/{id} with the check id in the file. A mode: local verdict file says charged is false too. It also writes the reason to the job summary and one error annotation. When the API gave a check id, the failure file carries it.

The last line of the summary says what left your runner:

• "No check was sent." The Action stopped in your runner. Nothing was sent.
• "The API refused the request for the profile list before anything was collected; nothing from your system was sent." The Action asks the API for the profile list first. A wrong or revoked key, or a rate limit, is refused there, before the Action collects or sends anything.
• "The API refused the request before a check started; the collected files were sent and not kept."
• "Check <id>. The check was sent; the API refused the poll for its result."
• "Check <id>." The check reached the server. Report this id to Symbolia.
• "No check id came back from the API." The request may have left your runner; no check id came back.

A collection with gaps is still a verdict. Each gap reads not observed with the place it was looked for.

tier_excludes never ends a job. With the report on, it would mean your account's plan does not include the report; no plan served today excludes it, and a free account without its USD 1 report grant is refused allowance_exhausted instead. Either way the verdict, its summary and its exit stand, and the summary says the report was withheld. Set report: false, or ask Symbolia to grant the free report balance or move you to a paid plan.

rotate_too_early never ends a job. It is only answered by the API's key rotation route (POST /v1/keys/rotate), which the Action never calls: the key was asked to rotate before its last 7 days, and it still works.

billing_unavailable never ends a job. It is only answered by the API's billing routes, which the Action never calls: billing is not configured on that server, or Stripe could not be reached. The verdict, its summary and its exit stand.

tier_required never ends a job. It is only answered by the API's paid formalisation routes, which the Action never calls: paid formalisation is on Premium (USD 20 a month) and above. The verdict, its summary and its exit stand.

allowance_exhausted never ends a job either. With the report on, it means your plan's allowance is not set or is spent for the month, and nothing pays for the report (overage is off until you set a budget): the verdict, its summary and its exit stand, and the summary names the USD needed. Ask Symbolia to set an overage budget and set allow-overage: true, or to top up your account. On the free plan, it means your report balance is spent, and the summary says so.

overage_ceiling never ends a job: this month's report overage billed later, beyond your top-up, would pass a monthly overage limit set on your account, so the report does not run, even with allow-overage. Your top-up is spent before any overage, whatever the limit. job_ceiling never ends a job: the report's quote is above your account's job ceiling, so the report does not run, even with allow-overage; the summary names the quote and the ceiling. daily_report_cap never ends a job: your account has had its reports for the day (UTC). Nothing runs and nothing is charged for any of them.

11. Profiles

• postgresql-declared-model checks your server against a declaration you supply in raw/declaration.json (and optionally raw/clients.json). With artefacts, add your declaration under raw/. With connection (in mode: api) the Action collects as for the observed profile and reads .assure/postgresql-declared-model.json (else .assure/declaration.json, where an earlier proposal was merged) from the checkout (GITHUB_WORKSPACE) and places it in the collected bundle as raw/declaration.json before the withholding pass and the bundle limits, so its declared_predicate string literals are withheld exactly as an artefacts directory's are, with the same numbering as the snapshot; a link, a linked .assure/ directory, or a file that is not a regular readable file is refused (bad_input). The declaration input stays refused with a PostgreSQL connection. When the checkout has none and the collector's sidecar names a server major from 14 to 18, the Action drafts one from the collected catalog snapshot (drafted before the withholding, so the draft holds your own literals and reads the same after you merge it), sends the draft, writes assure-declaration-proposal.json beside the verdict file (the mode: api verdict path) and opens one pull request of its own on assure/declaration-proposal proposing .assure/postgresql-declared-model.json (it never commits to your branches; the workflow needs contents: write and pull-requests: write); merging it is the acceptance. Until then the result is bounded by an unaccepted draft and the step output says declaration=unaccepted-draft, as on a pull request whose declaration is not yet on the base branch. With no server major to draft from, and in mode: local, a connection with this profile still reads bad_input for the missing raw/declaration.json.
• postgresql-observed-baseline reads your server and compares it with observed facts and pinned public baselines. You declare nothing.
• http-observed-baseline reads the response heads you captured for the HTTP endpoints you select (section 12).
• mysql-declared-model checks a MySQL server against a mysql:// connection and your declaration file (declaration), or against an artefacts directory holding raw/submission.json. Seven machines read it, M1 to M4, M6, M7 and M8, and the check contacts no server. A report is withheld with profile_unqualified until the report writer is qualified for MySQL.

What each profile claims, and what it does not, is in SCOPE.md and, for http-observed-baseline, in section 12. What is collected and where it goes is in DATA.md.

12. Checking HTTP endpoints

http-observed-baseline checks one HEAD response per endpoint you select against the HTTP obligations Assure holds (response framing, transport policy, cookies and similar). Live collection against real endpoints is not in this release: the Action reads response heads you captured, offline. connection is refused for this profile, before anything is read.

Give the Action an artefacts folder that holds:

• manifest.json, with these ten keys exactly: "schema_version": "http-fixture-001", "mode": "offline_fixture", endpoints, and the seven flags at the values shown below (execution_authorized, hardware_authorized, industrial_release_authorized, release_allowed, physical_validation and self_approved false; simulation true). Any other key, a missing key or another value makes the Action stop before anything is sent (MANIFEST-INVALID). endpoints is a list of 1 to 16 objects with exactly these keys: id (endpoint-NNN, three digits), scope_token (a lower-case name you choose, distinct per endpoint), scheme, host, port, path, response_file (the head file's name in the folder) and complete (true when you captured the whole head);
• one file per endpoint holding the raw response head as received: the status line and every header line, each ending in CRLF, and the empty line that ends the head.

A complete manifest.json for two endpoints:

{
  "schema_version": "http-fixture-001",
  "mode": "offline_fixture",
  "endpoints": [
    {"id": "endpoint-001", "scope_token": "checkout", "scheme": "https", "host": "shop.example.test", "port": 443,
     "path": "/checkout", "response_file": "head-001.txt", "complete": true},
    {"id": "endpoint-002", "scope_token": "login", "scheme": "https", "host": "shop.example.test", "port": 443,
     "path": "/login", "response_file": "head-002.txt", "complete": true}
  ],
  "execution_authorized": false,
  "hardware_authorized": false,
  "industrial_release_authorized": false,
  "release_allowed": false,
  "physical_validation": false,
  "simulation": true,
  "self_approved": false
}

      - name: Assure check
        uses: Symbolia-Assurance/assure-action@beta
        with:
          api-key: ${{ secrets.ASSURE_API_KEY }}
          profile: http-observed-baseline
          artefacts: http-fixture

The inputs: profile: http-observed-baseline; artefacts, the folder above. scope is optional: a JSON file listing the endpoint ids to check, which must name exactly the manifest's ids (the Action stops before collecting otherwise). Leave scope-binding unset so the Action produces it: before collection it runs the identity producer and then the collector over your manifest, and sends their record as the scope binding with the endpoint tokens. identity-key stays pipe, its default: the Action makes a fresh key for each job and passes it on a pipe, so no key is an input, an environment variable or a file.

A scope file, when you give one, is a JSON list of the manifest's ids, for example ["endpoint-001", "endpoint-002"].

Each run of an HTTP check is a new check, charged as one: the Action makes a fresh identity key for each job, and no key is kept from one run to the next, so a new collection is new work.

The verdict's observed_facts holds, for each observed endpoint, the facts its readings used (the status code and the HSTS, CSP and cookie attributes, never a cookie value or a redirect URL), so you can explain a reading without collecting again.

Capturing the response heads

Capture each head with curl, one HEAD request over HTTP/1.1, and write it to the file the manifest names:

mkdir -p http-fixture
curl -sS --http1.1 -I https://shop.example.test/checkout > http-fixture/head-001.txt
curl -sS --http1.1 -I https://shop.example.test/login > http-fixture/head-002.txt
head -n 1 http-fixture/head-001.txt

-I sends a HEAD request and writes the head as received, every line ending in CRLF, with the empty line that ends it. --http1.1 matters: the first line of each head must be an HTTP/1.1 status line, such as HTTP/1.1 200 OK. A head whose first line is another version, such as HTTP/2 200 from a capture without --http1.1, or HTTP/1.0 200 OK from a server that answers in HTTP/1.0, is recorded as not observed. Without -L, curl does not follow a redirect, so a 3xx head is the endpoint's own answer.

The host in each manifest endpoint must be the same host as the URL you capture with curl.

Set complete to true for each head you captured this way.

A complete workflow for the HTTP profile captures the heads in the job. Commit http-fixture/manifest.json alone; one step per endpoint runs curl and writes that endpoint's head beside it. Every run then checks fresh heads, and no captured head is committed to your repository.

name: Assure HTTP

on:
  pull_request:
  push:
    branches:
      - main
  schedule:
    - cron: "17 3 * * *"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  http:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Check out the repository
        uses: actions/checkout@<full commit sha of the release you trust>

      - name: Set up Python 3.14
        uses: actions/setup-python@<full commit sha of the release you trust>
        with:
          python-version: "3.14"

      - name: Capture the head of /checkout
        run: curl -sS --http1.1 -I https://shop.example.test/checkout > http-fixture/head-001.txt

      - name: Capture the head of /login
        run: curl -sS --http1.1 -I https://shop.example.test/login > http-fixture/head-002.txt

      - name: Assure check
        id: assure
        uses: Symbolia-Assurance/assure-action@beta
        with:
          api-key: ${{ secrets.ASSURE_API_KEY }}
          profile: http-observed-baseline
          artefacts: http-fixture
          fail-on: fails
          output: assure-verdict.json

      - name: Keep the verdict
        if: always()
        uses: actions/upload-artifact@<full commit sha of the release you trust>
        with:
          name: assure-verdict
          path: ${{ steps.assure.outputs.verdict-path }}

Each run is a new check, even when the heads are the same as the last run's, byte for byte: the Action makes a fresh identity key for each job, so the endpoint tokens it sends differ from run to run (section 9).

You can instead commit the captured heads with the manifest and leave out the capture steps. Use this offline route when you must reproduce a check on a fixture that does not change, for example heads you captured once to keep as a record.

Every reading summary carries the profile's three scope notes:

• Readings cover one HEAD request per operator-selected endpoint.
• Evidence freshness and response authenticity are unverified; same-selection replay is not excluded.
• Per-endpoint coverage qualifications are not displayed in this report.

A full read of the two https endpoints above has the first line "green: 2 of 2 endpoints observed; 4 of 5 machines read, 1 refused; declared premises: 12; version pins: none; nothing disproven; established: 3 of 12; vacuous: 3; not established: 6 — top action: collect the facts HTTP-TLS10-NEGOTIATION reads": the TLS machine (M2) is refused with "no usable observed machine premise", because a captured head carries no TLS session. That is a bound of the result, so the run exits 0. For http:// endpoints M2 reads vacuous and the first line is "green: 2 of 2 endpoints observed; 5 of 5 machines read; declared premises: 12; version pins: none; nothing disproven; established: 3 of 12; vacuous: 6; not established: 3 — top action: declare redirects in raw/HTTP-INTENT.json beside the collected files (docs/customer/VERDICTS.md); requirements.md cannot state an HTTP requirement in this release". A head that carries both Content-Length and Transfer-Encoding fails HTTP-FRAMING-CL-TE, and under the default fail-on: fails the job exits 1, red. Those three not-established rows are HTTP-REDIRECT-POLICY, HTTP-RESPONSE-POLICY-ADEQUACY and HTTP-COOKIE-POLICY: an HTTP-INTENT.json you write beside manifest.json (issue #2381; its shape is in docs/customer/VERDICTS.md) is sent as raw/HTTP-INTENT.json and decides each row whose key it carries (redirects, response_headers, cookies) instead of reading it needs_intent.

Choose endpoints that answer HEAD with 2xx or 3xx; a 4xx or 5xx endpoint hides policy checks for the whole run and the verdict's warnings names them. No HTTP requirement can be stated in this release: a requirements.md sentence on this profile cannot hold. HTTP-REDIRECT-POLICY, HTTP-RESPONSE-POLICY-ADEQUACY and HTTP-COOKIE-POLICY ask for the HTTP-INTENT.json key that decides each (issue #2381); the other readings inform and ask nothing of you.

The policy exits are those of section 7. policy.reason takes exactly one of these eight values, the serving core's closed list, in the source's order (the policy decides them in the order docs/customer/VERDICTS.md section 9 gives):

• never (0, as the readings give) when your fail-on is never; a prove-class obligation that is not proven still exits 1 as not_proven.
• could_not_look (3, yellow) when nothing could be read at all: the input gate stopped the check, no machine was read, or no selected unit was observed.
• disproven (1, red) when a reading on a read machine has a status your fail-on names; a disproof your fail-on leaves out keeps this reason, red, with exit 0.
• not_proven (1, red) when a prove-class obligation has no holds on a machine that was read, under every fail-on.
• unresolved_strict (1, red) when under fail-on: unresolved-security, an obligation marked security: true is unresolved.
• stopped_by_choice (1, red) when a reading has a status that is not a verdict and that your fail-on names, such as not_observed.
• nothing_disproven (0, green) when nothing is disproven, whatever endpoints or machines could not be read.
• platform_owned (0, red) when every disproof your fail-on names is platform-owned, someone else's to fix.

A fails reading whose findings are all platform-owned keeps the colour red with exit 0 and policy.reason platform_owned: the disproof is someone else's to fix.

13. Checking MySQL from a submission

mysql-declared-model checks a MySQL server against a mysql:// connection and your declaration file, or against an artefacts directory holding raw/submission.json.

With a connection (the collector runs in your runner): set connection to a mysql://user:pw@host:port/ URI or a keyword/value string (mysql host=… port=… user=… password=…), profile to mysql-declared-model, and declaration to the path of your declaration file (symbolia.mysql-declaration.v0). The password reaches the collector by environment only (MYSQL_PWD), never on a command line. collection-role defaults to the user in the connection. Write a / in the user name or password as %2F (percent-encoding); the port is digits only, 1 to 65535.

- uses: Symbolia-Assurance/assure-action@beta
  with:
    connection: ${{ secrets.MYSQL_URL }}
    declaration: assure/mysql-declaration.json
    profile: mysql-declared-model
    api-key: ${{ secrets.ASSURE_API_KEY }}

With artefacts (you collect yourself): give the Action an artefacts folder that holds one file, raw/submission.json. Its schema is symbolia.mysql-declared-input.v0. It carries collection, declared_policy, grant_tables, mysql_user, system_variables, replication_channels, version and configuration_sha256, with material set to mysql and the seven flags at their standing values (execution_authorized, hardware_authorized, industrial_release_authorized, release_allowed, physical_validation and self_approved false; simulation true).

The check reads the file and contacts no server. Seven machines read it: M1, M2, M3, M4, M6, M7 and M8. A machine whose section the submission lacks reads representation, with the machine's own reason. A submission that holds a secret, such as a password or a key, is refused before anything is read, and the refusal names the path and the kind, never the value.

A report for this profile is withheld with profile_unqualified until the report writer is qualified for MySQL. /v1/profiles lists the profile's 50 obligations with the states each can take (holds, not_established, disproven, from what its machine can produce), a requirements.md line that quotes an obligation binds to it, and the report page names the MySQL areas. The report stays withheld until the writer qualifies for MySQL. Formalisation is not offered for this profile.

14. Checking a Python (Flask) repository

python-auth-declared-model checks how a Flask app signs people in and guards its routes. It reads your code as text and never runs it. The check is free and contacts no server of yours.

A whole workflow. It grants id-token: write so the Action signs in with your workflow's GitHub identity and you store no key, and contents: write and pull-requests: write so the Action can open its proposal (below). Set profile; leave artefacts and connection empty:

name: Assure

on:
  pull_request:
  push:
    branches:
      - main

permissions:
  contents: write
  id-token: write
  pull-requests: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<full commit sha of the release you trust>

      - name: Set up Python 3.14
        uses: actions/setup-python@<full commit sha of the release you trust>
        with:
          python-version: "3.14"

      - name: Assure check
        id: assure
        uses: Symbolia-Assurance/assure-action@beta
        with:
          profile: python-auth-declared-model

      - name: Keep the verdict
        if: always()
        uses: actions/upload-artifact@<full commit sha of the release you trust>
        with:
          name: assure-verdict
          path: ${{ steps.assure.outputs.verdict-path }}

The Action reads the checked-out repository: its tracked Python files and requirements.md, at most 2000 Python files of 512 KiB each, within 2048 upload entries including manifests and an 8 MiB encoded request body. It writes raw/REPOSITORY.json (each file's bytes, sha256 and git mode, the commit and the tree id) itself.

The declaration arrives as a proposal. The check reads your app against a declaration at .assure/declaration.json: your app objects, the session key that means "signed in", your guard decorators, the views that sign people in, raise privilege and sign out, and the routes that are public on purpose. On the first run there is none, so the Action sends the bounded repository bytes to the free declaration proposal route, whose drafter uses the checker's own readers, and runs the check on the returned draft. When the repository's Python files import FastAPI or Django and no other web framework, the Action asks the route for that stack's draft (stack: python/fastapi or python/django) and the pull request says which stack it was drafted for; any other repository is drafted as Flask. A field the bytes do not give remains unread in the proposal for you to review. When your Flask app loads its configuration by name (from_pyfile, from_object, from_envvar) from a file or module the check reads as outside the repository (flaskr's app.config.from_pyfile("config.py") with no instance/config.py, or from_envvar; a from_pyfile or from_object name that is not a literal is not read, and drafts nothing), the draft proposes instance_config: "constants-only" as a field to confirm, read at that call: keep it only if that configuration assigns constants.

Assure never commits to your branches; it opens one pull request proposing each profile's draft at its own path under .assure/; merging it is the acceptance. The pull request, Assure: proposed intent — review and merge to accept, comes from Assure's own branch assure/declaration-proposal into your base branch (the pull request's base, or your default branch on a push), and changes only the drafts' files: python-auth's .assure/declaration.json and postgresql-declared-model's .assure/postgresql-declared-model.json, side by side when both profiles run on one repository, its description holding one section per file. Its description and the job summary list each field to confirm with the file and line it was read from. A later run updates the same pull request, keeping the other profile's file, in the shallow checkout actions/checkout leaves too; it never opens a second one. Its description opens by naming the file this run is proposing. A branch on an older base tip, or one holding a file its description does not name (a proposal opened before one pull request carried both profiles), is rebuilt from the base branch's tip, carrying over each draft under .assure/ whose section its description holds (with that section); a file it does not name is left behind.

Which profiles draft intent: python-auth-declared-model drafts .assure/declaration.json; postgresql-declared-model reads the declaration supplied with the run, and drafts one only on its own connection run with no .assure/declaration.json in the checkout, proposing it in Assure's pull request (the job summary of a run not bounded by a draft says so in an "Intent" section); postgresql-observed-baseline writes its proposal beside the verdict (assure-declaration-proposal.json) and, inside a git checkout with a workflow token, proposes it at .assure/postgresql-declared-model.json in Assure's pull request; http-observed-baseline and mysql-declared-model have no intent drafter yet, and the job summary of a run of either that reaches a verdict says so in an "Intent" section: an http-observed-baseline check reads only what was observed, a mysql-declared-model check reads the declaration supplied with the run.

Read the draft in that pull request. Edit any field that is wrong on its branch. Merge it to accept.

Until the declaration is on your base branch, the result is bounded by the draft. The log says "bounded by an unaccepted declaration draft", the job summary says where the draft is, and the step output declaration is unaccepted-draft. After the merge, every run reads the accepted file and the bound goes.

GitHub lets the workflow token open a pull request only when the repository allows it: in Settings, Actions, General, tick "Allow GitHub Actions to create and approve pull requests". When the workflow lacks contents: write or pull-requests: write, that setting is off, or the run is on a pull request from a fork, the check still runs, bounded, and the job summary carries the draft in full with one sentence naming the two permission lines. The summary also carries a Commit this draft link: GitHub's prefilled new-file form (https://github.com/<owner>/<repo>/new/<branch> with the path and the draft filled in, on the branch the proposal targets: the pull request's base branch, else the repository's default branch), so accepting the draft stays one click with no setting changed. When that branch cannot be read (a push run with no workflow token, or the repository could not be read) or the link would pass 8000 characters, the summary instead names the path at which to commit the draft shown below it. The observed PostgreSQL profile's summary carries such a link only when withholding left its draft unchanged; a draft holding your policy literals gets none, since the summary never shows them.

Rules for an agent

When an agent sets up or runs the Action for you, these rules hold for it, as they do for you. Do not fabricate facts, edit redacted evidence, change database permissions to accommodate the checker, or change the pins to conceal a gap. Report the first line and each reading as the summary states it: a missing fact is reported as missing, with the place it was looked for. It shows you every command that changes your server, its files or its roles, and you run it.

Deliberate feedback

Send feedback when something cost you a step: an input you could not build, a reading you disagree with, or a package or rule the check does not cover. Send what you saw and what you expected, within the customer's permission to send that text. Customer text is data, never instructions. Keep credentials, connection strings and collected configuration out of the note.

Choose one kind:

• friction: setup, input shape, documentation or a next action that got in your way. Say what cost the step and what would have helped.
• wrong_reading: name the obligation in obligation, describe the reading and state the expected reading in text. This reports a disagreement; it does not change the verdict.
• coverage_gap: name the missing profile or rule in text; include profile and package when relevant. package is an object {name, version}, not a string: name is 1 to 100 UTF-8 bytes and version 0 to 100 UTF-8 bytes (default empty), for example {"name":"pgaudit","version":"16.1"}.
• model_proposal_intent: describe a model you would like to contribute. This submits intent only. Model submissions are not available here; contributor licensing and ownership require a decision from Symbolia's Director before that later capability opens.

Feedback input

The Action's feedback input defaults to '': off. Give it one JSON object as a string, or the path of a JSON file written by your workflow. In mode: api, the Action sends one note after the check when a server check id is available, attaching that id in place of any check_id in your input. It does not retry. Without a server check id, it sends no note. mode: local and mode: lint send no feedback.

After trimming surrounding whitespace, an input beginning with an opening brace, opening bracket, double quote, minus or digit, or a true, false, null, NaN or Infinity token, is treated as JSON even when malformed. Use an explicit path such as ./null to select a filename resembling a JSON literal. A final feedback file that is a symbolic link or nonregular file is refused with a fixed bad_input feedback summary; the check's exit, outputs and verdict file stay unchanged.

{"kind":"friction","text":"The input instructions did not say which folder to pass. I expected an example folder layout.","consent_follow_up":false}

Write that JSON to a file in the workflow's working directory and use its path under the Action step's with block:

feedback: feedback.json

A feedback error adds a typed outcome to the job summary; it never changes the check's exit, outputs or verdict file. Without a server check id, a requested note adds bad_input to the feedback summary and no POST is made. A delivery error means receipt is not confirmed: the server may already have stored the note. Known input secrets are refused before posting. The note's text is not echoed into commands or the summary. The report is opt-in (report: true, mode: api). Reports are written for postgresql-declared-model verdicts today; for other profiles the report is withheld with profile_unqualified, without a model call. report: false stops the check record going to OpenRouter. Deliberate feedback is separate: it does not go to a model, and report: false does not turn it off.

Feedback API

POST /v1/feedback accepts one UTF-8 JSON object, with no duplicate keys, non-finite numbers or extra keys. Authenticate with the same API key as checks, in the Authorization: Bearer header. Send Content-Type: application/json and one Content-Length; no transfer encoding or query parameters.

Every field in one body, as the route accepts it:

{"kind":"coverage_gap","text":"No rule reads the pgaudit settings. I expected a reading of pgaudit.log.","check_id":"0123456789abcdef0123456789abcdef","profile":"postgresql-declared-model","profile_wanted":"postgresql-pgaudit","obligation":null,"package":{"name":"pgaudit","version":"16.1"},"agent":{"model_id":"example-model-1","client":"example-agent/1.0"},"consent_follow_up":false}

A refusal of the body's fields (an unknown key, a missing kind or text, a wrong type or form) is bad_input (400) whose detail.accepted_fields lists the nine keys above, sorted, and whose detail.kinds lists the four kinds, so one refusal names the whole accepted shape. detail.shapes gives each key's form: package is {name, version}, agent is {model_id, client}, kind lists the four kinds, consent_follow_up is boolean and every other key is text; detail.example is one minimal valid body, the friction example this section prints. The reason for an unknown key names that key; no value is ever echoed. A refusal of one named field also carries detail.malformation.pointer, that field's JSON pointer (such as /check_id); a body that is not one JSON object carries none. A value or key that carries an Assure API key (asr_, an 8-hex key id, _ and a 43-character secret) is refused bad_input and nothing is stored: a value's refusal names its field, and such a key is never named. A body that is not UTF-8, is not JSON or repeats a key is refused before its fields are read: bad_input (400) with detail.malformation.kind body_not_utf8 or body_not_json, and without accepted_fields, kinds, shapes or example.

The request body limit is 16,384 bytes. Feedback is free on every plan, with no charge or usage ledger row. Each POST uses the same per-account minute rate window as checks; a repeat still uses that window. Up to 100 new notes per account per UTC day are accepted. Within one account and UTC day, the same kind, check id and exact text returns the first note with duplicate set to true, without a new row or another daily slot. Changing other metadata alone does not change that identity. A rate refusal is rate_limited (429) with Retry-After; a daily refusal names window set to day and the wait until midnight UTC.

POST returns 200 with schema, id, received_at, kind, check_id, profile, obligation, package, sha256, duplicate, related, routed and the response flags; it does not echo the text. check_id, profile and obligation are the stored row's values (null when not sent) and sha256 is the stored row's deduplication SHA-256, the hash of kind|check_id|text rather than of the text alone, so a record can cite the note without trusting its own request body; on a duplicate they are the first row's. related lists this account's other notes of the same kind and profile whose status is not merged or declined, among its notes of the newest 7 UTC-day files, newest first and at most 10, each as id, kind, profile, status and match (kind+profile), so a second note on one gap can see the first; when the note has no profile it lists the open notes of the same kind of any profile, null included, each with match kind. routed says where the note goes next: digest, the daily agent feedback digest that reads it (Agent feedback digest YYYY-MM-DD, the note's UTC day), status_route, the GET /v1/feedback/{id} route that answers its state, and next, one sentence naming both. GET /v1/feedback/{id} returns 200 with the stored row, including text, the account and key ids, timestamp, metadata, the deduplication SHA-256, check_known, rows_unreadable and response flags. check_known records whether that account held a verdict for the supplied check id at submission time; it is not a live lookup. rows_unreadable counts unreadable lines in that note's UTC-day file, including zero. status is the note's state as Symbolia acts on it: received until then, in_pr with the pull request number pr, merged with release, the engine commit that ships the change, or declined with a reason; updated_at is when it was set. When the state cannot be read just now it reads unavailable with a reason, and the note still answers. A malformed, absent or another account's id returns the same not_found (404). Neither route accepts query parameters.

Notes are kept for 12 months, with retention and removal on request handled by the operator. The daily digest reads notes without changing them: counts by kind, counts by profile wanted with distinct account counts, packages by kind with distinct account counts, bounded text from every kind for triage regardless of consent, notes consenting to follow-up, and friction notes by check id. Consent controls follow-up only; it does not hide a submitted note from triage. Account ids appear as stable short hashes. Customer text appears only in fenced data blocks marked DATA>, with control and format characters removed and display length bounded. The digest reports skipped or unreadable files and unreadable rows, including zero. When the feedback collection cannot be accessed, the digest stops with an error instead of reporting an empty day. Feedback is not read by the checker or report writer. No automatic demand-ledger entry or model proposal is created.