Install Fwozen

Fwozen blocks merges with a required GitHub check run named fwozen. Installing takes about ninety seconds; making the check required is the step that turns a red X into an actual block, so this page spends most of its words there.

Before you start

• GitHub Cloud. GitHub Enterprise Server, GitLab, and Bitbucket are not supported yet.
• A GitHub organisation owner installs the app, because Fwozen requests one organisation permission (members: read) and GitHub requires an owner for that.
• Someone who can save a ruleset for the enforcement step: an organisation owner, or a repository admin on the per-repository path. Fwozen asks for no organisation administration in either direction, so enforcement at organisation scope is always a rule you save. On the per-repository path it can write the rule itself, but only on an installation that has granted it repository administration: write — /security says where that stands.
• A GitHub plan and repository visibility that support rulesets or protected branches. Where GitHub offers neither, Fwozen reports setup as unavailable and says why, rather than showing you a button that cannot work.
• Rules already in Terraform? Mark those repositories as managed as code before step 4, on the repository’s page in Fwozen. Fwozen then writes nothing to them and shows you the values for your own module instead, so the next terraform plan has no drift to report.

1. Install the GitHub App

Choose All repositories unless you have a reason not to. Selected repositories is fine too. Fwozen only counts private repos you explicitly enable, so a wide installation does not cost you anything.

2. Enable the repositories you care about

Fwozen reads your repository list and shows open pull request counts and last-push times, so you can tell which repositories are alive. Enable them individually, in bulk, or with a glob:

services/**        matches 14 repositories
*-api              matches 3 repositories
!archived-*        excludes archived work

3. Watch a branch

Start with one branch, usually main on the repository with the most open pull requests. Watching a branch is what tells Fwozen where to write the check and whose rules to read.

4. Make the fwozen check required

This is the make-or-break step. Until fwozen is a required status check on the branch, a freeze is advisory. The check will fail, and anyone with merge rights can merge anyway.

On an installation that has granted Fwozen repository administration: write, setup offers a button. Fwozen writes the repository ruleset itself, on the branch you enrolled, and then reads it back from GitHub before anything in the product or in your audit log says the rule exists. A queued write says queued until that read-back returns, and a failed one says which of the four ways it failed. It writes nothing to a repository you have marked as managed as code.

Everywhere else — an installation whose owner has not approved that permission, a repository you manage as code, and organisation scope, which Fwozen asks for no administration over — the sequence is:

1. Fwozen writes the current policy check. Before it offers you anything to click, it evaluates the real verdict and writes it to every enforcement-relevant commit: each watched branch tip, the head of every open pull request targeting it, and every live merge-group head. That is also what makes fwozen appear in GitHub’s required-check picker, which only lists checks it has seen recently.
2. Fwozen opens the right GitHub settings. One organisation ruleset covering every selected repository where your plan and role allow it, otherwise one repository ruleset per repository. Either way it carries the exact rule name, target branches, context fwozen, the Fwozen app to pin it to, and the recommendation to leave the bypass list empty. It shows how many saves are still needed; on the per-repository path that is one per repository, because that is GitHub’s boundary.
3. You save one native rule. In GitHub, as yourself. GitHub’s audit log shows a human, because a human did it.
4. Fwozen verifies the ruleset. When you come back it re-reads GitHub’s effective rules for the branch and tells you what it found, including when it could not determine the answer. Verify again is there for the retry.

If a correct ruleset already exists, from a reinstall or from a rule someone made earlier, setup finishes with zero saves. If one exists but is wrong, Fwozen opens that rule’s edit page with the mismatch named, rather than talking you into a duplicate.

Managing rules as code? The same plan is available as gh api and Terraform, as an alternative rather than the normal path. Fwozen detects the rule within about thirty seconds either way. Both samples pin the check to Fwozen’s GitHub App id, which is published, is not a secret, and is the difference between a verified rule and one Fwozen reports as needing attention:

FWOZEN_APP_ID=$(curl -fsSL https://api.fwozen.com/.well-known/fwozen-app \
  | jq -r .githubAppId)

gh api -X POST repos/acme/api-server/rulesets \
  -f name='fwozen' \
  -f target='branch' \
  -f enforcement='active' \
  -F conditions[ref_name][include][]='refs/heads/main' \
  -F rules[][type]='required_status_checks' \
  -F 'rules[][parameters][required_status_checks][][context]=fwozen' \
  -F "rules[][parameters][required_status_checks][][integration_id]=$FWOZEN_APP_ID"

The Terraform is the same object. Signed in, the enforcement step generates this block for the branch you enrolled with the app id already filled in; here it is as a shape you can read before you install anything:

resource "github_repository_ruleset" "fwozen_main" {
  name        = "fwozen"
  repository  = "api-server"
  target      = "branch"
  enforcement = "ACTIVE"

  conditions {
    ref_name {
      include = ["refs/heads/main"]
      exclude = []
    }
  }

  rules {
    required_status_checks {
      strict_required_status_checks_policy = false
      required_check {
        context        = "fwozen"
        integration_id = var.fwozen_app_id
      }
    }
  }
}

5. Verify it would block a merge

Fwozen reads GitHub’s effective rules for each watched branch and reports what it found, including when it could not determine the answer, with a badge saying how long ago it last looked. A verified result means the fwozen check is active, required, and pinned to the Fwozen app on that branch. It does not mean nobody can merge. Bypass actors are a separate question, and one GitHub usually will not answer at all.

Classic branch protection is guidance only. The effective-rules endpoint Fwozen reads on every branch reports rulesets rather than classic protection, and we have not demonstrated a classic read against a live classic rule, so Fwozen tells you what to configure and then says the result is unknown rather than showing you a green light it has not earned.

If fwozen is not in GitHub’s dropdown

GitHub only lists checks it has seen complete recently, and Fwozen writes the real current verdict to every enforcement-relevant commit before offering you the GitHub step, which is normally what puts fwozen in the picker. The rest of that answer, and the other three things that go wrong at this step, are on troubleshooting.

Next: your first freeze.