Installing Fwozen across an enterprise

If your company runs GitHub Enterprise Cloud with dozens of organisations, installing Fwozen one consent screen at a time is a bad afternoon. GitHub has a REST endpoint for exactly this. An administrator of your enterprise can install a GitHub App into any organisation in it, without a per-organisation approval, one call at a time.

The important half of that sentence is your. Read the permission model below before the recipe. It is the reason this page exists on a vendor’s own documentation site, and it is a fact about your safety rather than about our convenience.

Who can do this, and who cannot

The endpoint is authorised by a GitHub App that is installed on the enterprise and holds the Enterprise organization installations permission at write level. That permission is scoped to the enterprise the calling App is installed on and does not cross an enterprise boundary.

Which credential the calls below use

Not the one your gh auth login holds. That is a user token, and the permission above belongs to an App. So the calls use an installation access token for a GitHub App you created and installed on your own enterprise with Enterprise organization installations at write level. GitHub documents that exchange, JWT and all, under Automating app installations in your enterprise’s organizations; it is three requests and we will not reproduce it badly here. Follow it, export the installation token, and the recipes below work as written:

export ENTERPRISE_APP_TOKEN=<installation access token for YOUR installer App>

The App you install through these calls is Fwozen. The App you authenticate with is yours, and it never leaves your enterprise.

The call

One request per organisation. client_id identifies the App to install, which can be any valid GitHub App, including a third-party one like Fwozen. repository_selection chooses between all repositories and a selected set. If that organisation already has a pending request to install the App, this approves it.

gh api -X POST \
  --header "Authorization: Bearer $ENTERPRISE_APP_TOKEN" \
  /enterprises/ACME/apps/organizations/acme-payments/installations \
  -f client_id="$FWOZEN_APP_CLIENT_ID" \
  -f repository_selection='all'

And across the estate, which is the whole reason to be here. Keep it boring: read the organisation list from GitHub, loop, and let a failure stop the loop rather than scroll past. The listing endpoint is the install endpoint’s own companion. It answers with the enterprise-owned organisations an App can be installed into.

set -euo pipefail

gh api --paginate \
  --header "Authorization: Bearer $ENTERPRISE_APP_TOKEN" \
  /enterprises/ACME/apps/installable_organizations --jq '.[].login' \
| while read -r org; do
    echo "installing into $org"
    gh api -X POST "/enterprises/ACME/apps/organizations/$org/installations" \
      --header "Authorization: Bearer $ENTERPRISE_APP_TOKEN" \
      -f client_id="$FWOZEN_APP_CLIENT_ID" \
      -f repository_selection='all'
  done

Getting the client id

client_id is the OAuth client identifier of the Fwozen GitHub App. It is not a secret: it is the public half of the pair, and it appears in the URL of the App’s own authorisation flow. Read it, and the numeric App id the enforcement rule pins to, from the discovery document:

curl -fsSL https://api.fwozen.com/.well-known/fwozen-app \
  | jq '{ githubAppId, githubAppClientId }'

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

It is the same string for every customer. If the document is unreachable, mail [email protected] and you will get the exact value.

Do not guess it from the App slug and do not scrape it out of a screenshot. An install call that names the wrong client id installs the wrong App into your organisation.

What this does not do

Installing is not enrolling, and it is worth being blunt about the gap, because an admin who expects otherwise will believe an estate is covered when it is not.

• It does not enable any repository. Fwozen never enables a repository on its own. Private repositories are the billable unit, and enabling one silently would be a charge nobody agreed to. After the fan-out, every organisation still has zero repositories enabled, and someone chooses.
• It does not make anything billable. An installed-but-unenrolled organisation costs nothing. The bill follows enabled private repositories, not installs.
• It does not create a ruleset. Installing grants the App its permission set on the repositories you chose. It writes nothing: a ruleset is only ever written by an explicit enforcement setup, on a branch somebody enrolled, in a repository not marked as managed as code, by a signed-in person. Enforcement at organisation scope is always a rule a person saves — Fwozen asks for no organisation administration in either direction — so a fan-out leaves every organisation needing somebody to go and set enforcement up, whether that is the one-click write on a repository ruleset or the one native GitHub rule saved by hand. Until that happens, a freeze is recorded and visible but does not block a merge.
• It does not create Fwozen organisations or link identities. Each installed organisation is claimed in Fwozen the ordinary way, by someone who administers it.

A sensible order

1. Pilot one organisation by hand first, all the way through to a freeze that blocks a real pull request. The install guide is that path, and doing it once tells you more than reading this page twice.
2. Fan the install out with the loop above.
3. In each organisation, enable the repositories that matter and watch their default branches. A glob does most of the work.
4. Have somebody in each organisation set enforcement up, which is a button where that installation has granted repository administration: write and the one native rule Fwozen shows them the exact values for where it has not. Either way Fwozen verifies it against GitHub and reports what GitHub actually said.

If you are driving that from a script or an agent rather than by hand, the REST API covers every step after the install, and the agent policy says which of them still need a person.