Skills, MCP and apps / Apps and webhooks
Install an app
You want a service, like a package preview bot, to work on your repositories. Your own token can do everything that you can do, so you do not want to give it that token.
3 min read
Install the app of the service. It gets its own identity, only the permissions that you approve, and only the repositories that you pick. You can take the app back at any time.
You need:
- For your own account: nothing more.
- For an organization: you must be an owner of the organization.
1. Find the app
- Open the app directory. It lists the public apps. Search by name.
- Click the app. Its page shows the description, the owner, the permissions and the events that the app asks for.
Note
A private app is not in the directory. It installs only on the account that owns it. Its owner opens it at /apps/<slug>.
2. Read the consent screen
Click Install. The consent screen shows:
- Permissions: what the app can do, one line each. For example,
surfaces:writelets the app write its own card and status on pull requests. - Events: what the app hears about, one line each.
The app acts as its own bot, <slug>[app]. It never approves pull requests, never reads held items, and never gets admin rights, the vault or secret values.
3. Pick where it goes
Under Where to install:
- Pick the Account: your own, or an organization that you own.
- Pick All repositories, or Only picked repositories.
- For picked repositories, type a name in Find a repository, click Search, and select each repository. You can pick up to 500.
- Click Install with the name of the app.
When the app has a setup URL, Source sends you there to finish the setup on the site of the app. The link carries a setup code that works once, for 10 minutes. When the app has no setup URL, you land on Installed apps.
Note
An install for all repositories also covers the repositories that you make later, and the ones that move to your account. On an account with very many repositories, the install can be slow.
Done
The app acts on the repositories that you picked, with only the permissions and events that you approved. It waits for your approval to get more.
To change its repositories, approve a request or uninstall it, see Manage installed apps. A repository admin who does not own the account uses Add an app to one repository.