Bracel
Request access

Docs · Quickstart

Your first verdict, step by step.

Five steps, all through reviewed pull requests in your own repositories. Nothing to sign up for on our side, and nothing that sends your code anywhere.

Last updated 1 October 2026

Coming soon
your-service · terminal 00:12
  1. 1 · Verify the release
  2. sha256sum -c SHA256SUMS
  3. bracel-verify release bundle: OK
  4. git push git@github.com:your-org/bracel-verify.git main
  5. pinned by full commit SHA in your workflow
  6. 2 · Approve a rule, add the workflow
  7. git switch -c add-bracel && git add <rules file> .github/workflows/bracel.yml
  8. pull request reviewed and merged into main
  9. 3 · Read-only preflight
  10. npm lockfile at the repository root
  11. express 4 · Node.js 24
  12. runs-on: ubuntu-24.04 · pull_request · contents: read
  13. no blocking findings · nothing changed · nothing sent
  14. 4 · First pull request
  15. Bracel Verify · PASS · http.auth-required@1 · all-requests-denied
Illustrative session · file names and output are examples

Before you start

  • One Node.js application at the repository root, on Express 4 or NestJS 11, with npm and a committed package-lock.json from the public npm registry.
  • An application that starts without a database or other service, listens on PORT, and answers on a readiness route.
  • GitHub Actions on GitHub-hosted ubuntu-24.04 runners. 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.

{
  "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.

Bracel changes no merge settings. If your administrators make the check required, a failing result blocks merging.