Skip to content

GitHub App ​

The fixlock GitHub App runs the same check as CI on every pull request, with no workflow file in the repository. Install it on a repo that has a .fixlock/ folder, and each PR gets:

  • a fixlock check that fails when a locked fix or feature is changed without the owner's approval, and passes again as soon as they approve the PR;
  • one PR comment that explains which lock changed, why it exists and who must approve. The comment is edited in place as the PR changes, and clean PRs don't get one.

It reads the code through GitHub's API. Nothing is checked out or stored, and the only code it reads is the files a PR changes plus the .fixlock/ folder.

How it decides ​

The app uses the same engine as fixlock check, so the results match the CLI and the GitHub Action:

SituationCheck
The PR doesn't touch locked code, or only reformats itPasses
A locked fix is removed or rewrittenFails, until an approver (by default the lock's owner) approves the PR
The PR author is the lock's ownerPasses
The approver's latest review is "changes requested"Fails again
A variable is renamed inside a lockPasses with a note (see matching.renames)
The repo has no .fixlock/config.jsonNeutral, with a pointer to set it up

Locks and policies are read from the base branch. A PR can't approve itself by deleting a lock or loosening the policy in the same PR. A PR that sets fixlock up for the first time is judged by its own config.

To make the check mandatory, add fixlock as a required status check in the branch protection rules for main.

App or Action? ​

GitHub AppGitHub Action
Setup per repoInstall the appAdd a workflow file
Runs onThe app's server (no Actions minutes)Your Actions runners
Locks and policy fromThe base branchThe PR's checkout
Working-code rewrite warningsNot yetYes
Tracker sync (--notify)Not yetYes
GitLab, Bitbucket, JenkinsNoUse the CLI in your CI

Pick one per repository. If the base branch has a workflow that uses the fixlock Action, the App stays out of that repository's pull requests, so each PR gets one fixlock check and one comment.

Run your own copy ​

The app is a Cloudflare Worker in app/. The free plan is enough for most teams. Set-up takes about 15 minutes.

1. Deploy the Worker

bash
git clone https://github.com/AbinandhMJ/fixlock && cd fixlock/app
npx wrangler login
npx wrangler deploy

Note the URL it prints, such as https://fixlock-app.<your-subdomain>.workers.dev. Opening it in a browser should say "fixlock GitHub App is running".

2. Register the GitHub App

Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (for an organization: the organization's settings → Developer settings). Fill in:

FieldValue
GitHub App nameAnything unique, such as fixlock-yourcompany
Homepage URLhttps://abinandhmj.github.io/fixlock/
Webhook URLYour Worker URL followed by /webhook
Webhook secretA long random string, such as the output of openssl rand -hex 32. Keep it for step 3
Repository permissionsChecks: Read and write · Contents: Read-only · Pull requests: Read and write · Metadata: Read-only
Subscribe to eventsPull request, Pull request review, Check run
Where can this app be installed?Only on this account, or Any account to let others install it

Create the app, then on its settings page:

  • note the App ID;
  • under Private keys, click Generate a private key. A .pem file downloads.

3. Give the Worker its secrets

bash
npx wrangler secret put APP_ID           # the App ID
npx wrangler secret put WEBHOOK_SECRET   # the webhook secret from step 2
npx wrangler secret put PRIVATE_KEY < path/to/your-app.private-key.pem

4. Install it

On the app's page, click Install App and choose the repositories. Open a pull request in one of them: the fixlock check appears within a few seconds.

On GitHub Enterprise Server, also set the GITHUB_API variable to your server's API URL, for example https://github.example.com/api/v3.

Deploy updates from GitHub Actions ​

The repository's GitHub App workflow tests the app on every PR. When CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are set as repository secrets, it also deploys every change on main. Create the token in Cloudflare under My Profile → API Tokens, using the "Edit Cloudflare Workers" template. The app's own secrets stay in Cloudflare; deploying doesn't change them.

Troubleshooting ​

No check appears. On the app's settings page, open Advanced → Recent Deliveries. Each delivery should get a 202 response.

  • 401 Bad signature: … don't match: the webhook secret on the GitHub App and the Worker's WEBHOOK_SECRET are different. Set the same new value in both: Change secret on the app's General tab, then npx wrangler secret put WEBHOOK_SECRET in app/. Paste the value itself, not the app's client secret from the Credentials tab.
  • 401 No X-Hub-Signature-256 header: the GitHub App has no webhook secret. Set one under Change secret.
  • 500 WEBHOOK_SECRET is not set: run npx wrangler secret put WEBHOOK_SECRET from the app/ folder, so it goes to the fixlock-app Worker. npx wrangler secret list shows which secrets it has.
  • No deliveries at all: check that the app is subscribed to the Pull request event and installed on the repository.

The check says "could not check this pull request". The error is in the check's details. A malformed .fixlock/registry.json or config.json is the usual cause. Run npx wrangler tail in app/ to see the Worker's logs live.

The check is neutral. The base branch has no .fixlock/config.json. Run fixlock init and merge it.

No check, and the repository uses the fixlock Action. That's intended: the Action reports, and the App stays quiet. Remove the Action's workflow to use the App instead.

"has no GitHub username". The lock's owner (or the lead, depending on the policy) has no GitHub username in .fixlock/config.json, so no GitHub approval can match them. Add it with fixlock team add --name "…" --github <username> and merge that.

MIT licensed · A product of Algotricz