# 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) 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. 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](https://staging.git.cafe/docs/account/account-settings.md#confirm-its-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 `@amp-acme`. 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 `/amp-acme`), 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](https://staging.git.cafe/docs/integrations/webhooks.md#app-webhooks)). Apps that let members [act as themselves](https://staging.git.cafe/docs/account/mcp-connections.md#connect-a-gitcafe-app-as-yourself) 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. ## 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](https://staging.git.cafe/docs/account/account-settings.md#confirm-its-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 keep their old permissions until it requests new ones. Anything a publisher removes leaves every installation at once, without a review: the app's tokens lose it at their next use. ## 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. - **Listing**: a category and Markdown description for the app directory, and its homepage, support and privacy policy links. - **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 and may ask you to confirm it's you. When the app has webhooks, its signing secret shows once; copy it then. 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. Apps and their P-256 public signing keys can also be managed with the Apps operations of the [REST API](https://staging.git.cafe/docs/reference/api.md). Private keys never leave your backend. 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//install?state=`, where the state is up to 256 letters, digits, `.`, `_`, `~` or `-`. 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.