Bot Identities
Create service identities, install them on personal or organization workspaces, grant scopes, and manage tokens safely.
A bot is a service identity that automations and external integrations act as. It has a stable slug, display name, optional description and photo, permission scopes, and one or more workspace installations.
Automations do not need a long-lived bot token
Trylle automatically issues a short-lived, run-scoped bot session token to each automation sandbox. Use try bot token only for an external integration that must authenticate as the bot outside an automation run.
Identity, installation, and scope
These controls are separate:
| Control | What it limits |
|---|---|
| Bot identity | The actor name and shared bot configuration |
| Workspace installation | Which personal accounts or organizations grant the bot repository access |
| Bot scopes | The maximum operations the bot can perform across its installations |
| Automation scopes | An optional, narrower subset applied to one automation |
Installing a bot on a workspace grants it access to repositories in that workspace, constrained by its scopes. Only a ready bot installed on the automation's workspace can be selected in the automation editor.
Create a bot
Open Settings > Bots and choose New bot. You can also choose Create new bot from the automation editor's bot picker.
Enter a slug, name, and optional description. A photo can be a PNG, JPG, GIF, or WebP within the upload limit shown by the dashboard.
Select the personal and organization workspaces where the bot should be installed.
Grant the smallest set of scopes needed by its intended automations or integrations.
Create the bot and wait for installation provisioning to reach Ready before selecting it in an automation.
The slug must contain 1 to 39 lowercase letters, numbers, or hyphens. It cannot begin or end with a hyphen. The slug is fixed after creation; the display name, description, photo, and scopes can be edited later.
New bots start with issues:read and issues:comment selected in the creation dialog.
Available scopes
| Group | Scopes |
|---|---|
| Repository | repo:read, repo:write, labels:write, members:read |
| Issues | issues:read, issues:comment, issues:write, issues:close |
| Pull requests | pulls:read, pulls:comment, pulls:write, pulls:merge |
| Files | files:read, files:write |
Granting a write scope does not bypass repository ownership, installation, or automation scope checks. A run receives only the intersection of its automation scopes and the bot scopes.
Manage installations
Bot installations can target a personal workspace or an organization where you have administrative authority. Organization owners and administrators can install or remove a bot for their organization.
When editing a bot, installation changes save immediately; they are not part of Save changes. Removing an installation removes that workspace's repository grant and can prevent its automations from running.
| Provisioning state | Meaning |
|---|---|
pending | The installation or bot is waiting to be processed. |
provisioning | Repository access is being granted. |
ready | The bot can be selected and used. |
failed | Provisioning failed; inspect the installation and retry it. |
deprovisioning | Repository access is being removed. |
The bot creator controls the shared identity and permission scopes. An administrator of another workspace where the bot is installed can manage that workspace's installation without taking ownership of the shared identity.
Change scopes safely
While a bot has any active installation, its scopes can be reduced but not expanded. This prevents a shared bot from silently gaining broader access in workspaces that already approved it.
To add a new scope:
- Record which workspaces currently have the bot installed.
- Remove every installation and wait for deprovisioning to finish.
- Add the required scope and save the bot.
- Reinstall the bot only on the workspaces that approve the broader permission set.
- Recheck dependent automations and run a controlled test.
Inspect bots from the CLI
List bot identities visible to the active account:
try bot listThe current CLI does not filter this list by workspace. Use the dashboard account switcher and installation view when workspace context matters.
Mint a bot token
Only the bot owner can mint a long-lived API token:
try bot token BOT_IDThe command prints a new secret
Each try bot token BOT_ID invocation creates a fresh token and prints its plaintext to standard output. The plaintext is available only at creation time. The CLI does not set a name or expiry, and it cannot list or revoke issued tokens. Do not run this command in an ordinary CI job, recorded terminal, shared screen, or chat-driven shell.
Move the token directly into a secret manager and expose it only to the process that needs it. Trylle CLI and public API authentication recognize TRYLLE_BOT_TOKEN; keep that variable isolated from sessions using a personal TRYLLE_API_KEY.
The public API can issue a named token with an expiry and revoke a token by ID. Use those lifecycle controls when an integration needs a durable credential, and revoke the token immediately if its plaintext is exposed. See API authentication and the OpenAPI reference.
Current CLI boundary
Trylle CLI 1.1.4 can list bots and mint a token. It cannot:
- Create or edit a bot identity.
- Add or remove workspace installations.
- Change bot scopes or provisioning state.
- List, name, expire, or revoke bot tokens.
Use the dashboard for identity, scope, and installation management, and the public API when explicit token lifecycle controls are required.