Tooling

GitHub App

The NanoFlags GitHub App connects repositories to a project without a CI key: code references from every default-branch push, one flag summary per pull request and a NanoFlags scenarios check.

What it does

Code references. On each push to a linked repository's default branch, NanoFlags finds where each flag key is read, so the flag page shows “where this flag is used”.
Pull request comment. One comment per pull request, edited in place on every push, lists the flags read in the changed files with their published state in every environment.
Scenario check. A check run evaluates the project's saved CI-suite scenarios, the same way nanoflags scenarios run does (Team plan and above).

The GitHub Action stays available and works independently; you can use either or both.

Install and link

In NanoFlags, open Settings → Integrations as an owner or admin of the project and choose Install on the “Connect GitHub” card.
On GitHub, pick the account or organization and the repositories (installing on an organization needs its owner, or approval by one).
GitHub returns you to NanoFlags. Confirm Link: the installation now belongs to your NanoFlags organization.
Choose which repositories feed the current project, the environment whose scenarios run on pull requests, and whether they run against its draft or its published revision. The first scan of each new repository is queued right away.

Why linking is protected

A link only works for the admin who started the installation from NanoFlags, within one hour, after GitHub has confirmed the installation to NanoFlags. An installation can belong to one NanoFlags organization only; no other organization can see it or link it.

To give the app more repositories later, use Configure on GitHub on the GitHub App settings page, then select them in NanoFlags. Each project chooses its own repositories; one repository can feed several projects of the same organization.

Code references

NanoFlags reads the repository tree and the source files through the GitHub API: .ts, .tsx, .js, .jsx, .mjs, .cjs, skipping node_modules, dist, build, .next, declaration files, binary files and files over 256 KB, up to 1000 files and 8 MB per scan. Detection is the same as nanoflags refs scan: a call such as flags.boolean("checkout-v2"), useFlag("checkout-v2") or client.getBooleanValue("checkout-v2") whose first argument is the flag key as a string literal. Keys held in variables or built at runtime are not found.

Each scan replaces that repository's references in the project (also ones uploaded by the Action for the same repository name).

Pull request comment

When a pull request is opened, reopened or updated, NanoFlags reads the changed files (up to 300) at the pull request's head and posts or updates a single comment:

each flag referenced, linked to its page in the dashboard;
per environment, the published state: on or off, rollout percentage or rule count, the revision (r12), and “draft differs” when an unpublished edit exists;
possibly stale flags of the project (below).

A pull request that reads no flag gets no comment.

Scenario check

For every commit GitHub asks the app to check, NanoFlags adds a completed check run named NanoFlags scenarios (one per linked project, with the project key in the name when a repository feeds several). It evaluates the scenarios marked “Include in CI suite” against the selected environment's draft or published revision, with the same engine and comparison as the CI suite: success when all pass, failure when any fails. The check reflects the NanoFlags configuration, not the code in the pull request. Results are not recorded as CI runs in NanoFlags — use the Action with a CI key if publishing policy should count them.

Plans

Scenario checks are part of the Team plan and above. On Explore the check is posted as neutral and says so; the comment and code references work on every plan.

Stale flag hints

The pull request comment and the flag page point out flags that may be ready for cleanup:

no linked repository references the flag on its default branch any more (flags created in the last 7 days and permanent flags are not reported);
a boolean flag served true to everyone by the production environment's published revision, with no configuration change for 30 days.

These are hints: other repositories and dynamically built keys are not seen.

Permissions and why

Permission	Access	Used for
Contents	Read	Reading the tree and source files of linked repositories for code references, and the changed files of a pull request.
Metadata	Read	Required by GitHub for every app: repository names and default branches.
Pull requests	Read and write	Listing a pull request's changed files, and posting or editing the one NanoFlags comment.
Checks	Read and write	Creating the NanoFlags scenarios check run.

Events: push, pull_request, check_suite, and installation events. The app never pushes code, never changes repository settings and reads only repositories you grant it.

What NanoFlags stores

The installation: GitHub account name and type, installation id, and the names of the repositories it can access.
For each reference: repository name, file path, line number, the text of that line (at most 240 characters) and the commit. Whole files are never stored. File contents are read in memory only for the scan.
Webhook delivery ids, for 7 days, to ignore duplicates. Payloads are not stored.

See the privacy notice.

Unlink and uninstall

Unlink (Settings → Integrations, admin): removes the installation from your NanoFlags organization, every project's repository links and the code references the app stored. The app stays installed on GitHub.
Remove a repository in NanoFlags (uncheck it) or on GitHub: its links and references go away.
Uninstall on GitHub (Settings → Applications → NanoFlags → Uninstall, or the organization's settings): GitHub tells NanoFlags, which deletes the installation, its repositories, links and stored references. Comments and check runs already posted stay on GitHub.