Docs · Quickstart
Your first verdict, step by step.
Connect your repository, select an execution profile, approve a rule and read the evidence on your next pull request. Verification and repair keep separate responsibilities.
Last updated 1 October 2026
- 1 · Verify the release
- sha256sum -c SHA256SUMS
- bracel-verify release bundle: OK
- git push git@github.com:your-org/bracel-verify.git main
- pinned by full commit SHA in your workflow
- 2 · Approve a rule, add the workflow
- git switch -c add-bracel && git add <rules file> .github/workflows/bracel.yml
- pull request reviewed and merged into main
- 3 · Read-only preflight
- npm lockfile at the repository root
- express 4 · Node.js 24
- runs-on: ubuntu-24.04 · pull_request · contents: read
- no blocking findings · nothing changed · nothing sent
- 4 · First pull request
- Bracel Verify · PASS · http.auth-required@1 · all-requests-denied
Before you start
Read the execution profile contract, prepare your setup request and inspect a recorded result before choosing the first rule.
- An application on Node.js/TypeScript, Python, Java/JVM, Go or C#/.NET, with the build and dependency contract of its execution profile.
- An isolated PostgreSQL or MySQL fixture, plus a defined Redis fixture when the scenario requires it. Provide readiness and observable business state.
- GitHub Actions on GitHub-hosted
ubuntu-24.04runners. Check the rest on the compatibility page.
1 · Verify the release
Check the release bundle against its published checksums, then push it to a private repository you own. You will reference it by full commit SHA, never by tag or branch.
2 · Approve a rule
Add the rules file to your default branch through a reviewed pull request. Bracel always reads it from the pull request’s base commit, so a pull request cannot change the rules that judge it. Use test values only.
Example: a Node.js route rule. Other language and persistence profiles use their own build, start and observation contracts; do not reuse the Node.js command unchanged.
{
"schemaVersion": 2,
"application": {
"start": ["node", "dist/server.js"],
"build": "build",
"port": 3000,
"readinessPath": "/health",
"readinessTimeoutSeconds": 60,
"env": { "NODE_ENV": "test" }
},
"protections": [
{
"id": "admin-auth",
"template": "http.auth-required",
"templateVersion": 1,
"parameters": { "requests": [{ "method": "GET", "path": "/admin/users" }] }
}
]
} 3 · Add the workflow
Add a workflow that runs on pull_request with a read-only token. Never use pull_request_target for this.
name: Bracel Verify
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
concurrency:
group: bracel-verify-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
verify:
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@<pinned SHA>
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false
- uses: your-org/bracel-verify@<full commit SHA of the release> 4 · Run the preflight
The read-only preflight checks your committed rules, the supported profile and the workflow settings. It changes nothing, sends nothing, and prints a fix for each blocking problem.
5 · Read your first result
Open a pull request that touches a protected route. In the pull request, open the check and read the first table: the approved rule and why it ran, what was expected and observed, why the verdict follows, and what to do next. To see a FAIL, push a temporary commit that breaks the rule, read the summary, then revert it.
For an observed violation, reproduce it from the recorded inputs and schedule. Start controlled Fix only after approving model sharing; inspect the diff, independent verification and customer checks before human review.
Bracel changes no merge settings. If your administrators make the check required, a failing result blocks merging.
Next · Rule templates