Prepare your GitHub account

On GitHub, a Gryndel workspace belongs to one GitHub account: an organisation, or your own personal account. Gryndel works through a GitHub App, a GitHub integration with its own name, its own permissions and one webhook for every repository it can see. Your Gryndel operator has already created that App for your organisation. Your part is to install it on your account and choose which repositories it may see. Then you can create the workspace.

If your team uses GitLab, follow Prepare your GitLab group instead.

What you need

• Owner access to the GitHub organisation, or your own personal account. GitHub only lets organisation owners install an App on the organisation, and Gryndel only lets owners create the account's workspace.
• The name or install link of your organisation's Gryndel GitHub App. Your Gryndel operator can tell you. Gryndel's comments show this name as <name>[bot].
• Sign in with GitHub offered on Gryndel's sign-in page. If the page only offers GitLab, your operator hasn't turned on GitHub sign-in yet. Ask them.

Compared with GitLab, there is less to do: you don't add Gryndel to the organisation as a member, and nobody sets up webhooks per repository. The App's own webhook covers every repository it is installed on.

What the App can do

The operator chose the App's permissions when creating it. GitHub shows you the exact list before you install it. Usually they are:

Permission	Why Gryndel needs it
Contents: read and write	Read the code under review and your guideline files. When an admin uses Learn a repository, Gryndel opens a pull request with its notes from a branch of its own.
Pull requests: read and write	Post findings as review comments with suggestions, and resolve its own threads.
Issues: read and write	Post the summary, progress and command replies. GitHub stores pull request comments as issue comments.
Commit statuses: read and write	Set the gryndel/review pass/fail status on the reviewed commit.
Metadata: read-only	Required by GitHub for every App.
Members (organisation): read-only	Tell the organisation's owners from its members. See below.

Gryndel never merges, approves or changes repository settings, and it doesn't commit suggested fixes on GitHub. People apply them with GitHub's Commit suggestion button.

Install the App

1. Open the install link your operator gave you. If you only have the App's name, open https://github.com/apps/<name> (on GitHub Enterprise Server, your server's address instead of github.com) and click Install.
2. Choose the account to install it on: your organisation, or your personal account.
3. Under repository access, choose Only select repositories and pick them, or All repositories. See the table below.
4. Check the permissions GitHub lists, then click Install.

Choice	Pick it when	Note
Only select repositories	You're starting out, or only some teams want reviews. Recommended for a first roll-out.	New repositories need adding to the installation before Gryndel can review them.
All repositories	Most of the organisation's repositories should be reviewed.	Gryndel can see every repository, including new ones, but still reviews only those you turn on in Gryndel.

Either way, installing the App doesn't start any reviews. Reviews start when a workspace admin turns a repository on in Gryndel.

Not an owner?

GitHub lets organisation members ask for an App instead of installing it. The request goes to the organisation's owners, who approve it on GitHub. Until then, the App isn't installed.

Why the Members permission matters

Gryndel reads the roles in your organisation with the person's own GitHub sign-in, and GitHub only answers if the App has the Members organisation permission (read-only).

	With the Members permission	Without it
Organisation owners	Admins in Gryndel by default	Viewers, like everyone else
Creating the workspace	Owners can	Nobody can: the account isn't offered in New workspace
Members page	Lists the organisation's members with their roles	Shows an error that the App needs the Members organization permission

A personal account doesn't need it: its owner is always the admin.

To check, open the organisation on GitHub, go to Settings → GitHub Apps, and click Configure next to Gryndel's App. The page lists the App's permissions. If Members is missing, ask your operator to add it to the App. GitHub then asks an owner of each installation to accept the new permission on that same page; until someone does, the old permissions apply.

Change the repositories later

1. On GitHub, open the installation:
   • Organisation: the organisation's Settings → GitHub Apps, then Configure next to Gryndel's App.
   • Personal account: your Settings → Applications → Installed GitHub Apps, then Configure.
2. Under repository access, add or remove repositories, and click Save.
3. In Gryndel, open Repositories and click Refresh repositories. Without that, Gryndel reads the list again on its own once it is 15 minutes old.

A repository you remove from the installation is out of Gryndel's reach: it can't read or review it any more.

Make the status block merging (optional)

Gryndel sets a gryndel/review commit status on each reviewed commit. By default it fails only for P0 findings (critical: security or data loss). The status blocks nothing until you require it. To do so, add gryndel/review as a required status check in the repository's branch protection rule or ruleset on GitHub. GitHub suggests status names it has seen recently, so do this after Gryndel has reviewed at least one pull request in the repository.

Start without requiring it. Require it once the team trusts the findings. Which severity fails the status is set in Gryndel: see Your team's settings.

Check it worked

• On GitHub, the installation's Configure page lists the repositories you chose.
• In Gryndel, signed in with GitHub, open the workspace menu and choose New workspace… (or Create a workspace if you have no workspace yet). Your account appears in the list.

If it didn't work

What you see	Likely cause	What to do
The install page doesn't offer your organisation	The App can only be installed on the account that owns it.	Ask your operator which account the App is for.
GitHub offers to send a request instead of installing	You aren't an owner of the organisation.	Ask an owner to approve the request, or to install it.
Your account isn't in New workspace	You signed in with GitLab, the App isn't installed there yet, you aren't an owner, the Members permission is missing, or the account already has a workspace.	Sign out and Sign in with GitHub. Check the installation and the Members permission. If a workspace exists, ask its admins to make you an admin.
A repository is missing from Repositories	It isn't in the App's installation, or Gryndel hasn't read the list again yet.	Add it to the installation, then click Refresh repositories.
"GitHub discovery is unavailable" on Repositories	The App is no longer installed on the account, or GitHub couldn't be reached.	Check the installation on GitHub, then retry. If it is installed, tell your operator.

Next: Create a workspace.