Create a workspace

A workspace is where Gryndel keeps everything for one team: its repositories, review settings, model providers and keys, rules, costs and review history. Each workspace belongs to one GitLab group (with its subgroups) or one GitHub account (an organisation or a personal account). Its members come from GitLab or GitHub, so nobody needs inviting.

Create one workspace per group or account that wants reviews. If a workspace already exists for your group or account, you don't need another: ask its admins to make you an admin on Members.

Before you start

	GitLab	GitHub
Who can create it	An Owner or Maintainer of the group	An owner of the organisation, or the owner of the personal account
Prepared first	A reviewer account for Gryndel that is a Developer of the group, and its token. See Prepare your GitLab group.	Gryndel's GitHub App is installed on the account. See Prepare your GitHub account.
Signed in with	Sign in with GitLab	Sign in with GitHub

A Gryndel session belongs to one host. Signed in with GitLab, you only see and create GitLab workspaces; signed in with GitHub, only GitHub ones. To switch, sign out and sign in with the other.

1. Create it

GitLab

1. Sign in to Gryndel with GitLab.
2. Open the workspace menu at the top of the page and choose New workspace…. (With no workspace yet, click Create a workspace instead.)
3. In the New workspace dialog, find your group:
   • The list shows the top-level groups where you are an Owner or Maintainer. Tick Include subgroups to see subgroups too.
   • Or type to search, or paste a full group path such as company/payments.
4. Select the group. Under Reviewer account, paste the reviewer's token. Gryndel checks it with GitLab and shows the account reviews will be posted as and when the token expires.
5. Click Create workspace. It stays disabled until the token checks out.

Its members are everyone with access to the GitLab group, directly or through a parent group. Replace the token later on the Workspace page, before it expires.

Workspaces can't overlap

Groups inside or above an existing workspace aren't listed. If your group is missing, a parent group may already have a workspace. Ask its admins to review your projects there.

GitHub

1. Sign in to Gryndel with GitHub.
2. Open the workspace menu at the top of the page and choose New workspace…. (With no workspace yet, click Create a workspace instead.)
3. The New workspace dialog lists the GitHub accounts that have Gryndel's App installed, where you are an owner and that have no workspace yet. Type in Search your GitHub accounts to narrow the list.
4. Select the account and click Create workspace.

Its members are the organisation's members, or just you for a personal account. GitHub accounts don't nest, so there is no overlap to worry about.

What happens next: the new workspace opens and you are its admin. Nothing is reviewed yet: you choose the repositories in step 3, and reviews need a model (see the next page).

2. Copy settings (optional)

If you administer another workspace, you can bring its model providers (with their API keys), review agents and rules into the new one. That saves setting up the same model twice, and keeps teams on the same conventions. Open Workspace and use Copy from another workspace. See Workspace.

A session shows one host's workspaces, so you can only copy from a workspace on the same host: GitLab to GitLab, or GitHub to GitHub.

3. Turn on repositories

Reviews are off for every repository until an admin turns them on. Start with one or two repositories, check the reviews are useful, then add more.

GitLab

1. Open Repositories. It lists your group's projects (GitLab's word for repositories), including subgroups. Click Refresh projects if a new one is missing.
2. Tick the projects to review and click Enable selected.
3. The first time in a sign-in, GitLab asks you to let Gryndel change GitLab as you. That's how it adds each project's webhook with your Maintainer access. Allow it.
4. Back in Gryndel, click Enable now.

You need Maintainer access to each project. Turning reviews off later turns the webhook off the same way.

If GitLab can't reach Gryndel

The webhook only works if your GitLab server can reach the Gryndel server. If reviews never start, check the project's Settings → Webhooks → Recent events in GitLab. Show your operator any failed deliveries.

GitHub

1. Open Repositories. It lists the repositories Gryndel's GitHub App can see on the account.
2. Tick the repositories to review and click Enable selected.

That's all: there is no per-repository webhook and no extra permission to grant, because the App's webhook already covers every repository it is installed on. The Webhook column shows configured for enabled repositories. Pausing or turning a repository off later changes nothing on GitHub either.

A repository missing from the list isn't in the App's installation. Add it on GitHub (see Change the repositories later), then click Refresh repositories.

What happens next: Gryndel reviews new merge or pull requests in those repositories, and the ones already open. Repositories explains every option, including pausing and the per-repository settings.

Check it worked

• On Repositories, the Reviews column shows Enabled for the repositories you chose.
• Once a model is connected, open a small test merge or pull request and watch for Gryndel's progress comment. See Your first review.

If it didn't work

What you see	Likely cause	What to do
Your group or account isn't in New workspace	You lack the role, Gryndel isn't prepared there yet, a workspace already covers it, or you signed in with the other host.	Check Prepare your GitLab group or Prepare your GitHub account. Sign in with the host the workspace is for.
"Add @… to … as a Developer first" (GitLab)	The reviewer account isn't a member of the group, or is below Developer.	Add it as a Developer. See Prepare your GitLab group.
"The token needs the api scope" (GitLab)	The token was made with read_api or other scopes only.	Make a new token with the api scope.
"… is a GitLab administrator" (GitLab)	The token belongs to an administrator.	Use a user made for Gryndel, or a group access token.
"GitLab did not accept this token" (GitLab)	It was mistyped, revoked or has expired.	Copy it again, or make a new one.
"Install Gryndel's GitHub App on … first" (GitHub)	The App isn't installed there, or GitHub doesn't see you as an owner.	Install the App, and check the App has the Members permission.
Enabling a GitLab project fails	You need Maintainer access to it, or you didn't allow the permission request.	See Troubleshooting.

Next: Connect a model.