Apps#

An installed app acts as its own bot on the repositories you give it, even when nobody is online. Its bot is listed among the organization's members but takes no seat, so installing an app adds no seats. Apps GitCafe lists in the directory can be installed by any organization; an app that is not listed can be installed only by the organization that publishes it and by organizations GitCafe admitted to its pilot.

Find an app#

The directory at /apps shows every listed app by category (coding agents, code review, CI and deploys, security and quality, workflow automation), with a search. Organization owners and admins also reach it from Browse apps in the organization's Apps settings.

An app's page shows its publisher, its description, what it does on its own as its bot, what people may do through it as themselves, the events it receives and links to its website, support and privacy policy. When you are signed in, Your organizations lists each organization you belong to with what you can do there: Install, Manage an installation it already has, or Request it from the organization's admins.

Install an app#

Organization owners and admins install apps.

1. Choose Install on the app's page, or follow the install link the publisher gave you, and choose the organization.
2. Review the consent page: the app's name and publisher, what it does, and its permissions in plain words grouped by repositories, pull requests, issues, comments, organization and teams, each marked Read, Write or Admin. Permissions that publish, move, delete or change who has access are marked Destructive; those marked Owner only need an organization owner to install. Org-wide permissions (organization settings, organization members, team members, runners) act on the whole organization, not just the repositories the app can reach: they can give people access to all current and future repositories, and their changes stay after you uninstall the app. Runners an app starts take jobs, with their secrets, from every repository your runner groups serve. Under People, the page also says whether members may Assign issues and pull requests to the app and Mention it. Details shows the exact app ID, revision and manifest you are approving.
3. Under Repository access, choose All repositories, which covers every current and future repository in the organization, private ones included, or Only select repositories… and pick up to 50. Nothing is chosen for you, and Install stays unavailable until you choose. Selected access never covers repositories created later, except ones the bot creates itself when it may create repositories.
4. Choose Install (the button names the app) and confirm it's you if asked.

If the app has a setup page, GitCafe then sends you there to finish setting it up; otherwise you land on the app's page in your settings. If the publisher released a new version while the consent page was open, nothing is installed. Choose Review changes, check the permissions again, and install. An organization can have up to ten installed apps.

Request an app#

Members who cannot install apps choose Request next to the organization on the app's page, optionally say why, and choose Send request. The organization's owners and admins see it under Requests in Apps: Approve opens the consent page, where you choose its repository access, and installing approves every pending request for that app; Deny takes an optional reason. The member sees the answer, with the reason, on the app's page and can ask again. An organization holds up to 25 pending requests.

How an app shows up#

Each installation gets a bot with its own handle, such as @acme-amp. Its comments, reviews and mention suggestions show the app's icon and name with a Bot badge, and its name links to the bot's profile. The bot can act only on the repositories it can reach, within the listed permissions; it cannot use other repositories, including public ones. Each permission covers exactly what it names: labeling issues does not let the bot close them, and leaving review comments does not let it approve or dismiss reviews. An app you allow to Approve or request changes counts toward required reviews like a person does; like a person, it cannot approve its own pull requests. Webhooks an app creates send only events from repositories it can reach, stop while it is paused and are deleted when you uninstall it. Apps cannot change organization or team rulesets, which also cover repositories it cannot reach. No app can install apps, manage billing or close the organization.

Bots where people work#

The organization's Members page lists each installed app's bot under Apps, with who installed it, the repositories it can reach (their names for owners and admins, a count for other members) and when it was last issued a token (Last token issued: when the app last asked for access, not proof that it did anything). Its profile, at its handle (such as /acme-amp), shows the app, its publisher, your organization and the issues, pull requests and review requests assigned to it that you can see. Only members of the organization that installed it can open the profile.

If the app asks for it:

• Assign issues and pull requests to the bot from the assignee picker, where bots are listed under Bots after people. The bot must be able to read the issue or pull request in a repository it can reach.
• Request a review from the bot when it may also Write reviews or Approve or request changes. Its approval counts like a person's.
• Mention the bot with @ in a comment; the suggestions list only bots that may be mentioned in the repository.

A paused or suspended app, or one that lost the repository, is not offered and cannot be assigned or asked for a review. A bot that was already assigned or asked stays, with a warning in the sidebar and the picker, until someone removes it; other changes to the assignees and reviewers still save, and keeping it tells the app nothing. The sidebar shows who assigned each assignee and who asked each reviewer, and the app is told through its webhook when it is assigned, unassigned or asked (see App webhooks).

Apps that let members act as themselves attribute that work to the member: Alice via Hoplite, without a Bot badge. Its avatar shows the app's icon with the member's own picture in the corner.

Manage an installed app#

Apps lists each installed app with who installed it and when, when it was last issued a token (Last token issued), the repositories it can reach and whether it is active. Choose an app to open its page: its bot, what it does on its own, what people may do through it and its repository access.

• Manage repositories: switch between All repositories and Only select repositories…, or change the selection, and choose Save repository access. Giving the app more access may ask you to confirm it's you. If someone else changed the installation meanwhile, nothing is saved; choose Start over.
• Pause (in the ⋯ menu): stops the app at once until you choose Resume.
• Suspended means GitCafe suspended the app in every organization. It can't act until GitCafe lifts the suspension, and there is no Resume for it.
• Uninstall (in the ⋯ menu): stops the installation's access and tokens. It does not delete data the publisher already holds; ask the publisher to delete it. Comments the bot made stay attributed to it.
• People connected (for apps members can connect to act as themselves): the members who connected the app here, with the audiences each connection covers, its repositories and permissions, when they connected and when it last issued a token (Last token issued). Remove access works as in Connections below.

Changing repository access, pausing and uninstalling stop the access tokens the app already holds; the app requests new ones when it may act again. An app with a webhook is told when it is installed, about each of these, about resuming and about approved updates (installation events), but not about a suspension by GitCafe or about what it does while suspended.

See and remove members' connections#

Connections in the organization's settings lists every app and client that people connected to act as themselves on this organization's repositories: installed apps and unverified clients such as MCP apps alike, each with Authorized by its number of people, newest first, with Load more when there are more. It includes everyone whose connection reaches the organization, whether through membership, a repository role or a team's role. Owners and admins can open one to see each person's connection: its audiences (API, MCP, Git), its repositories here, its permissions, when they connected and when it last issued a token (Last token issued; using a token does not update it).

Remove access ends that person's connection for this organization's repositories only: reads, writes, Git and MCP stop at once, lists leave the organization's repositories out, and reconnecting does not bring it back. The member's connection keeps working in other organizations. Restore lifts the removal; it gives access back, so it asks you to confirm it's you.

Review an update#

When a publisher changes an app, the app keeps what you approved until you review the change. Its row in Apps shows Update available; choose Review update from its actions to see what the new revision changes: permissions added, raised, lowered or removed, for the bot and for people who connect it; how people can connect it (API, MCP, Git); where it sends events and which ones; and whether people can assign or @mention its bot.

Choose Approve update to adopt it. Approving may ask you to confirm it's you, and an app with owner-level permissions needs an organization owner for every update. If the publisher changed the app again meanwhile, nothing changes; choose Review changes to see the newest revision. The app keeps its bot and repositories. Tokens it already holds stop, and it requests new ones with the approved permissions; an app with a webhook is told (installation.permissions_accepted).

Anything a publisher removes leaves every installation at once, without a review: the app's tokens lose it at their next use, and the app is not told through its webhook.

Publish an app#

Organization owners and admins publish apps in the organization's Settings → Apps, under Your apps. Choose New app and fill in:

• App: its icon, name, slug (part of every installation's bot handle; it never changes) and a one-line summary.
• Links: its homepage, support and privacy policy, each an HTTPS URL. Every app needs all three, listed or not: install consent and the app's page link to them.
• Listing (optional): a category and Markdown description for the app directory.
• Acts on its own: the bot's name, whether people can assign it work and request its review (Assignable) or @mention it (Mentionable), and what the bot may do. Set one level per resource, or open Details for exact permissions. Owner-only and destructive permissions are marked.
• Acts for people: whether members can connect the app to act as themselves, through which of API, MCP and Git, the most they can let it do, and its OAuth redirect URIs. An authorization request with no scope asks for all of it.
• Setup and webhooks: an optional setup URL admins go to after installing, and the webhook URL and events, by category. Each event needs the bot to read what it describes; the form says which read access is missing and adds it with Add read access.

Create app saves revision 1. If a field needs fixing, the form names it next to the button and moves to the first one. When the app has webhooks, its signing secret shows once; copy it then.

Actions that create or widen an app's authority, such as creating an app, installing one and registering a signing key, ask the person to confirm it's you unless they did so recently, and then continue on their own. A confirmation lasts 10 minutes with a password and 15 with a passkey. An access token can't do these.

Choose Edit on an app to change it. Save as revision N seals the next revision; if someone else saved a revision after you opened the form, nothing is saved, and Start over opens the newest one. Installations keep what they approved until their admins review the update; anything you remove leaves them at once. The slug, signing keys and webhook secret don't change with a revision.

Register a signing key#

Your backend proves it is the app with an ES256 JWT signed by a P-256 key pair you generate. Register the public half; the private key never leaves your backend, and GitCafe refuses one if you paste it.

In Settings → Apps → Your apps, choose Register key on the app, enter a Key ID (up to 64 letters, digits, ., _ or -; your backend puts it in each JWT's kid header) and paste the Public key, either as a PEM block that begins -----BEGIN PUBLIC KEY----- or as a JWK (a key set with just that key works too). For example, with OpenSSL:

Or call the Register an app public key operation of the REST API from a recently confirmed browser session, with the key ID and the public JWK:

It returns 201 with the key's id, kid, createdAt, and lastUsedAt and revokedAt, both null for a new key. An app has at most 5 live keys and registers at most 100 over its life; past either limit the key is refused (APP_KEY_LIMIT). A key ID can't be reused (APP_KEY_EXISTS), and a point that isn't on P-256 is refused (APP_KEY_INVALID). To rotate, register the new key, move your backend to it, then revoke the old one.

Apps and their keys can also be managed with the Apps operations of the REST API. Your backend acts as an installation's bot with an installation token: the Mint an installation token operation, called with a client assertion signed by one of the app's keys, returns a token that lasts 15 minutes and holds the installation's approved permissions.

A runner service asks for the Runners permission and the actions.workflow_job event to start runners for the organizations that install it; see Build a runner service as an app.

To appear in the directory, give the manifest a listing (its category and a Markdown description) and ask GitCafe to list it. Give it a capabilities.setup_url to receive admins after they install: GitCafe adds installation_id, org and the install link's state as query parameters. Link people to /apps/<slug>/install?state=<value>, where the state is up to 256 letters, digits, ., _, ~ or -.

Clone as the app#

An app whose bot may read repository contents (repo contents read) can clone and fetch the repositories its installation reaches, Git LFS files included, with a short-lived installation token:

1. Your backend signs a single-use ES256 JWT with a registered key: header kid names the key; iss and sub are the app ID; aud is the exact token URL below; jti is unique; exp is at most 5 minutes after iat.

2. It posts the JWT to https://git.cafe/api/apps/installations/<installation-id>/access_tokens as {"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "<jwt>"}, optionally with permissions to narrow the token (such as only [{"kind": "repo", "family": "contents", "level": "read"}]) and repositoryIds to narrow it to some of the installation's repositories (up to 100). Every listed repository must be one the installation reaches now, or no token is issued (INSTALLATION_TOKEN_REPOSITORIES). A narrowed token never reaches another repository, not even through organization permissions such as deleting repositories or reading webhook deliveries. It cannot create or change organization webhooks (WEBHOOK_NARROWED_TOKEN), which would receive every selected repository's events after it expires, or organization CI integrations (CI_INTEGRATION_NARROWED_TOKEN), which sign checks and statuses into every repository bound to them; it can still read both. Even a token for the whole installation changes, disables or removes an organization CI integration only when the installation reaches every repository bound to it (CI_INTEGRATION_UNSELECTED_BINDING), and an integration whose webhook secret or API token the app set signs checks and serves logs only for repositories the installation reaches at the time (Buildkite). Other organization and team settings stay as approved. The response has the token (gct_…), its expiresAt, 15 minutes later, and the repositories it reaches.

3. Git uses the token as the HTTPS password; the username is not checked, so use x-access-token:

   shCopy

   1	git clone https://x-access-token:<token>@git.cafe/<org>/<repo>

   Authorization: Bearer <token> works too, for example through git -c http.extraHeader=....

Each Git request checks the token again. It stops working when it expires and as soon as the installation is paused, uninstalled or its repository access changes, or the app is suspended; request a new one then. It reaches only the installation's repositories (or the ones you listed), not other public ones; any other repository looks as if it does not exist. An installation gets at most 120 tokens an hour.

When a job finishes before its token expires, revoke the token with the token itself: DELETE https://git.cafe/api/apps/installation/token with Authorization: Bearer <token> returns 204, and every later request with that token is refused as unauthenticated (401). Only installation tokens can revoke themselves this way.

The publishing organization's Apps page lists its apps under Your apps, with each key's creation, last use and revocation. To retire a key, choose Revoke. Select This key is compromised to also stop every token already issued to the app's installations; installations work again once the app requests tokens with another key.

Choose Add icon (or Change icon) to upload the app's icon: a PNG, JPEG, GIF, WebP or AVIF image up to 1 MiB, as for avatars. It shows in the directory, on the consent page, in each organization's Apps list and on every installation's bot, including work the bot did before the change.