Security & permissions, in plain English.
Bracework is a GitHub App asking for the smallest credential set a triage-and-fix tool can run on. The four permissions, the data we read and write, and the data we do not store — outlined below so a security lead or CISO can read it, sign off on it, and move on.
No long-lived secrets. No "paste a token here".
The credentials Bracework uses, in the order they are minted, with the lifetime of each spelled out below.
- standing credentials
No long-lived personal access tokens.
Bracework never asks for a personal access token, never stores one, and never recommends minting one. The GitHub App installation token is the only credential Bracework holds, and it is per-installation and short-lived.
- next-run token
A short-lived App installation token for the next run only.
For each nightly triage run we mint a fresh installation token (1-hour expiry) from the GitHub App. The token is held in memory for the duration of that one run, scoped to the repos you authorized at install time.
- CI runtime
Ephemeral CI tokens minted by each GitHub Actions run.
When Bracework triggers an Actions workflow to validate a fix branch, the workflow reads its token from ACTIONS_RUNTIME_TOKEN / OIDC — not a static secret in Bracework. The token is per-job, scoped to the requesting repo, and discarded when the job ends.
- what we never ask for
No org-admin grants. No "paste a token here".
The App is installed at the lowest scope you can pick — single-repo, repo-set, or org-wide — and we read only the four permissions above. We never request admin, owner, or workflow scopes, and we never collect credentials from a user.
Four permissions, and the work that depends on each.
Every requested scope, with the plain-English justification GitHub asks for. The metadatascope (repo list, default branch, visibility) is auto-granted to every installed App — it is not listed below because it is on by default, not because it was forgotten.
| Permission | Access | Why we need it |
|---|---|---|
| Contents | Read & Write | Reads source to plan the smallest advisory closure; writes one commit on a working branch — never to the default branch and never with a force push. |
| Pull requests | Read & Write | Reads existing PRs and review comments for context; writes the proposed fix as a PR after green CI. |
| Checks | Read | Reads check-run status (GitHub Actions, Buildkite, CircleCI via the Checks API) to gate the PR; never opens a PR while CI is red. |
| Packages | Read | Reads published package metadata and version tags to detect vulnerable dependency versions in lockfiles; never publishes packages. |
What we read, what we write, what we never store.
Bracework’s data plane is the per-tenant dep-change log (the DependencyChange, FixDraft, and ConnectedRepo tables). Every row is scoped to your userId; nothing in triage is customer-identifying in the public-facing feed.
- What we read
- Source — package metadata only (lockfiles, manifest files for the affected dep). Never commit history, never forks, never disabled / private branches you have not authorized.
- What we write
- One commit on one working branch per repo per night, plus one PR after green CI. Never force-pushes, never merges to default, never deletes branches.
- What is stored in our DB
- Triage metadata only: advisory ID, repo, package, from→to versions, fix-branch name, PR number, CI run URL, status, timestamp. The row is per-tenant — your `userId` is the partition key on `ConnectedRepo` and the dep-change log.
- What we never store
- No source code, no PATs, no CI secrets, no commit history, no Dockerfiles or build artifacts. The "merged fix" audit row is metadata-only; the fix itself stays on your branch.
One branch, one PR, per repo, per night.
Bracework opens one fix branch per repo per night — named bracework/nightly-<date>, off the repo’s default branch — and pushes one PR after green CI. No force-pushes, no writes to the default branch, no deletes of the working branch until the PR is merged or closed. Auto-merge is enabled only where the org permits it; otherwise the PR waits for a human reviewer.
- CI must be green before the PR is opened; a failing pipeline produces no PR at all.
- Org-protected branches, branch-up-to-date requirements, and CODEOWNERS are honored: If we cannot comply with a rule, we do not push.
Every dep change, recorded in /audit.
Once your team is signed up, every dependency change is recorded in /audit— auto-bump, PR, CI run, advisory, and a CSV export. The page is login-gated and scoped to your repos; it is never public.
The questions every SCA evaluation hits.
Side-by-side comparisons, against Bracework.
The trade-off every security team weighs when picking an SCA tool — mapped against Bracework’s credential, branch, and audit posture above.
Talk to a Bracework engineer — one working session, no slides.
Bring the procurement review, the threat model, or the org policy — we will walk through how a per-tenant Bracework rollout lines up with each.