You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Three product-feedback refinements to the Apps page:
1. Lead with app management. The page is about managing authorized external
apps (one card each); GitHub is the current sole app, presented under a
"GitHub App" section, with room noted for GitLab etc. later.
2. Make the scenario explicit. New "Main scenario: letting the cloud sandbox
reach your repositories" section — the sandbox carries no git credentials,
which is what the App solves. BYOC generally doesn't need it (the runner
host's own gh suffices).
3. Drop internal concepts. Removed the GitHub-App-vs-MCP comparison and the
Safari token-minting internals (per-turn injection, gh credential helper,
bash guard, 302/postMessage callback). Kept only the user-facing security
properties (no credentials handed over, scoped to granted repos, least
privilege).
Copy file name to clipboardExpand all lines: en/ai-sre/apps.mdx
+43-57Lines changed: 43 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Apps
3
-
description: Apps are authorized external applications in AI SRE— currently GitHub. Once authorized, the agent can work directly inside your code repositories: read code, investigate recent changes / commits / PRs, trace a PR from a change ticket, and (when you ask) fix a bug, open a PR, or file an issue. It all runs through plain gh / git, using a short-lived, repo-scoped GitHub App token issued per turn.
description: Apps is where you manage authorized external applications in AI SRE. Each application appears as a card — currently GitHub (with room for GitLab and others later). Once authorized, AI SRE can work directly inside your code repositories: read code, investigate changes / commits / PRs, trace a PR, and (when you ask) fix a bug, open a PR, or file an issue. Its main job is to let the cloud sandbox reach your repositories safely.
An **App** is an authorized external application — today there is exactly one,**GitHub**. Once you authorize a GitHub App, AI SRE can **work directly inside your GitHub repositories** during a session: understand and explore code, investigate recent changes / commits / PRs, trace a PR from a change ticket, answer questions about a codebase, and — when you ask — fix a bug, open a PR, or file an issue.
16
+
**Apps** is where you manage **authorized external applications**. Each external application appears as a**card** — you authorize it, manage its installations, and enable / disable or revoke it right from its card.
17
17
18
-
The mechanism is plain: the agent operates on your repository with native `gh` and `git` commands inside its own sandbox, using a GitHub App installation token that Safari issues **per turn** and scopes to **only the repositories you granted**. The agent never sees or types that token.
18
+
Today there is exactly one app under Apps — **GitHub** (with room to add GitLab and other code-hosting platforms later). Once you authorize GitHub, AI SRE can **work directly inside your code repositories**during a session: understand and explore code, investigate recent changes / commits / PRs, trace a PR from a change ticket, answer questions about a codebase, and — when you ask — fix a bug, open a PR, or file an issue. It all runs through native `gh` / `git`, like an engineer working in a terminal.
19
19
20
-
<Warning>
21
-
The **GitHub App** on this page and the **MCP server** that uses GitHub as an example in [MCP](/en/ai-sre/mcp) are **two different mechanisms** — don't confuse them:
20
+
## Main Scenario: Letting the Cloud Sandbox Reach Your Repositories
22
21
23
-
-**GitHub App (this page)**: the agent runs `gh` / `git`**directly** in its sandbox against your repository — clone, `git log`, `gh pr diff`, open a PR — like an engineer working in a terminal.
24
-
-**MCP server**: the agent makes **tool calls** to a hosted MCP server, and that server performs the operation and returns the result.
22
+
---
25
23
26
-
One is "the agent runs git/gh in a shell"; the other is "the agent calls tools on a remote MCP server." This page covers only the former.
27
-
</Warning>
24
+
AI SRE sessions run in a **Flashduty cloud sandbox** by default. The sandbox is a clean, isolated, ephemeral environment that **carries none of your git credentials** — which is exactly what an App solves. Once you authorize the GitHub App, the agent inside the sandbox can clone your repositories, read diffs, and open PRs, **without you handing it any password or token**; its access is limited to the repositories you granted, with only the least privilege needed to do the work. **This is what the GitHub App is mainly for.**
25
+
26
+
<Note>
27
+
**BYOC (self-hosted Runner) generally doesn't need it.** A Runner runs on your own machine, which usually **already has `gh` / `git` credentials configured** (you work with repositories on it every day). In that case the agent just uses the host's own `gh` — **no GitHub App authorization needed**. (If the host happens to have no `gh` configured, authorizing the App lets BYOC sessions use it too.) For the differences between environments, see [Environments (BYOC)](/en/ai-sre/environments).
28
+
</Note>
28
29
29
30
## Where to Find It
30
31
@@ -36,46 +37,48 @@ Go to **Plugins → Apps**. Apps is the **first and default** tab in the Plugins
36
37
Viewing the Apps tab requires the appropriate permission; without it, the tab is hidden. Authorizing, revoking, and enabling / disabling each require their own action permission — when you lack one, the corresponding button is shown disabled.
37
38
</Note>
38
39
39
-
## Connecting a GitHub Organization
40
+
## The GitHub App
40
41
41
42
---
42
43
43
-
Start the authorization from the GitHub card on the Apps page. The whole install completes in a popup through GitHub's official install page, and the list refreshes automatically after the callback.
44
+
The following uses **GitHub**, the only app available today, to walk through authorization, installation management, and adjusting repository access.
45
+
46
+
### Connecting a GitHub Organization
47
+
48
+
Start the authorization from the GitHub card. The whole install completes in a popup through GitHub's official install page, and the list refreshes automatically after the callback.
44
49
45
50
<Steps>
46
51
<Steptitle="Start the authorization">
47
-
Click **Authorize** on the GitHub card (if the card already has an installation, the button reads **Connect another organization**). The backend returns the GitHub App's install URL, and the frontend opens a popup of roughly **1024 × 760**.
52
+
Click **Authorize** on the GitHub card (if the App already has an installation, the button reads **Connect another organization**). The frontend opens a popup that loads GitHub's official install page.
48
53
</Step>
49
54
<Steptitle="Pick the organization and repositories on GitHub">
50
-
The popup loads the GitHub App install page. Choose the **organization** (or personal account) to install into, and grant a repository scope — **All repositories** or **Only select repositories**. The set of granted repositories determines which repositories AI SRE can access afterward.
55
+
Choose the **organization** (or personal account) to install into, and grant a repository scope — **All repositories** or **Only select repositories**. The set of granted repositories determines which repositories AI SRE can access afterward.
51
56
</Step>
52
-
<Steptitle="GitHub calls back, the frontend refreshes">
53
-
After you confirm on GitHub, GitHub calls back to the backend; the backend 302-redirects to the frontend callback page `/ai-sre/app-callback`, which then forwards the result to the Apps tab via `postMessage` and closes the popup. On success, the Apps page shows **Authorized** and refreshes the installation list, and the new organization appears.
57
+
<Steptitle="Auto-refresh after you confirm">
58
+
After you confirm on GitHub, the popup closes automatically, the Apps page shows **Authorized** and refreshes the installation list, and the new organization appears.
54
59
</Step>
55
60
</Steps>
56
61
57
62
<Note>
58
63
If you are not the owner of the organization, GitHub routes the request to the organization owner through its request-to-install approval flow; the installation activates only after approval. Which organization to install into and which repositories to grant are decided entirely on GitHub's install page — Flashduty does not select on your behalf.
59
64
</Note>
60
65
61
-
## Managing Installations
62
-
63
-
---
66
+
### Managing Installations
64
67
65
68
Each authorized organization adds one installation row under the GitHub card. Each row shows:
66
69
67
70
| Element | Description |
68
71
|---|---|
69
-
| Organization name | The GitHub organization / account login the installation lives on (`github_target`) |
70
-
| Status dot | A colored dot plus a label: **Connected** (`active`), **Suspended** (`suspended`), **Revoked** (`revoked`)|
72
+
| Organization name | The GitHub organization / account login the installation lives on |
73
+
| Status dot | A colored dot plus a label: **Connected**, **Suspended**, **Revoked**|
71
74
| Repository count | The number of repositories currently granted to this installation |
The toggle in the top-right of the card switches between Enabled and Disabled, which moves the App's installations as a whole between **active ↔ suspended**. **Disable = suspend**: while suspended, no installation token is issued and the agent can no longer reach those repositories — but the **GitHub installation itself is kept**, so you can re-enable instantly with one click, without going through the GitHub authorization again. An App counts as "enabled" as long as it has at least one **Connected** installation.
78
+
The toggle in the top-right of the card switches between Enabled and Disabled. **Disable = suspend**: while suspended, the agent can no longer reach those repositories — but the **GitHub installation itself is kept**, so you can re-enable instantly with one click, without going through the GitHub authorization again. An App counts as "enabled" as long as it has at least one **Connected** installation.
76
79
</Accordion>
77
80
<Accordiontitle="Revoke"icon="trash">
78
-
Click **Revoke** on a row to open a confirmation dialog — "Revoke authorization for organization '…'? After revoking, AI SRE will no longer be able to access this organization's repositories. You can re-authorize at any time." On confirm, the installation is set to **Revoked** and no token is issued from then on; any cached token also expires naturally within its TTL of at most 1 hour. A revoked installation is hidden from the card; re-authorizing the same organization restores it.
81
+
Click **Revoke** on a row; after you confirm, the installation is set to **Revoked** and AI SRE can no longer access that organization's repositories. A revoked installation is hidden from the card; re-authorizing the same organization restores it.
79
82
</Accordion>
80
83
</AccordionGroup>
81
84
@@ -85,70 +88,53 @@ Each authorized organization adds one installation row under the GitHub card. Ea
85
88
86
89
### Adding or Adjusting Repository Access
87
90
88
-
The organization is already connected, but you want AI SRE to reach more of its repositories — you don't need to revoke and reconnect. In **Plugins → Apps**, click **Authorize / Connect another organization** again for that organization (or open the App's **Configure** page on GitHub directly). GitHub shows the **Repository access** screen; select the additional repositories and save. The callback takes the install callback's `setup_action=update` path, so AI SRE **re-syncs** the granted repository list automatically, and the new repositories become available without re-creating the connection.
91
+
The organization is already connected, but you want AI SRE to reach more of its repositories — you don't need to revoke and reconnect. In **Plugins → Apps**, click **Authorize / Connect another organization** again for that organization (or open the App's **Configure** page on GitHub directly). GitHub shows the **Repository access** screen; select the additional repositories and save, and AI SRE **re-syncs** the granted repository list automatically — the new repositories become available without re-creating the connection.
89
92
90
93
<Note>
91
-
**Fallback**: if a newly added repository still reports "cannot access / 404 / 403" in a session, open the Flashduty App's page on GitHub (e.g. `github.com/apps/flashduty`) → **Configure** → select the organization → scroll to the **Danger zone** → **Uninstall**. Then return to **Plugins → Apps** in Flashduty and authorize the organization again, granting **all** the repositories you need in one pass.
94
+
**Fallback**: if a newly added repository still reports "cannot access / 404 / 403" in a session, open the App's page on GitHub (e.g. `github.com/apps/flashduty`) → **Configure** → select the organization → scroll to the **Danger zone** → **Uninstall**. Then return to **Plugins → Apps** in Flashduty and authorize the organization again, granting **all** the repositories you need in one pass.
92
95
</Note>
93
96
94
-
## How AI SRE Uses It
97
+
## How AI SRE Works Inside a Repository
95
98
96
99
---
97
100
98
-
After authorization, you need no extra configuration. When you ask AI SRE to work on a task in a repository during a session, it does the work itself inside the sandbox — behavior governed by the built-in `github` Skill.
99
-
100
-
### The token: short-lived, repo-scoped, least-privilege
101
-
102
-
-**Issued per turn**: Safari injects a GitHub App installation token into the bash environment for each turn and wires `git` to use `gh`'s credential helper — `gh` reads the token automatically, and `git` HTTPS clone / push just work, with **nothing written** to `.git/config` or any URL. The token expires automatically at the end of the turn (cache TTL ≤ 1 hour); nothing to revoke.
103
-
-**Least privilege**: the token carries only the permissions it needs — `contents` / `pull_requests` / `issues` are **write**, `metadata` is **read**.
104
-
-**The agent never touches the token**: the agent never sees, types, pastes, or echoes it. Operations like `echo $GH_TOKEN`, `env`, `printenv`, or embedding the token in a URL (`https://x:TOKEN@github.com/...`) are blocked by the **bash guard**, so the token cannot leak into the transcript.
105
-
-**Scope limited to granted repositories**: the token is scoped to the repositories granted at install. A `404` / `403` on an ungranted repository means "add that repository to the installation" — at which point the agent asks you to do so rather than trying to work around scope.
101
+
After authorization, you need no extra configuration. When you ask AI SRE to work on a task in a repository during a session, it works like an engineer joining the project — understand first, then change, then verify. This behavior is governed by the built-in `github` Skill.
106
102
107
-
<Note>
108
-
**Cloud sessions** use the account's GitHub App installation. If `gh auth status` reports not logged in, the account has no GitHub App installed — or it is not installed on the target repository — and the agent tells you to install the GitHub App from **Plugins → Apps** and grant the repository. It does **not** ask you for a token.
109
-
110
-
**BYOC sessions** are different: they use the runner host's **own `gh`** (you run `gh auth login` on the host, or set `GH_TOKEN` in the runner environment), **not** this App token. For differences between environments, see [Environments (BYOC)](/en/ai-sre/environments).
111
-
</Note>
112
-
113
-
### Typical actions
114
-
115
-
The agent works like an engineer joining the project — understand first, then change, then verify:
103
+
**Typical actions**
116
104
117
-
-**Enter the repository**: clone it into its own workspace (`gh repo clone OWNER/REPO`) and read the repo's own conventions first (`CLAUDE.md`, `AGENTS.md`, `README`, `CONTRIBUTING`).
118
-
-**Investigate changes / PRs**: `git log`, `gh pr list`, `gh pr view <number>`, `gh pr diff <number>`, `gh search prs` — to trace a PR named in an incident or change ticket, see what a release shipped, or read a diff before deciding anything.
105
+
-**Enter the repository**: clone it into its own workspace and read the repo's own conventions first (`CLAUDE.md`, `AGENTS.md`, `README`, `CONTRIBUTING`).
106
+
-**Investigate changes / PRs**: use `git log`, `gh pr list`, `gh pr view`, `gh pr diff`, `gh search prs` to trace a PR named in an incident or change ticket, see what a release shipped, or read a diff before deciding anything.
119
107
-**Change and propose**: create a branch, make a minimal diff, open a reviewable PR with `gh pr create`, or file an issue with `gh issue create`, and report the PR / issue URL back to you.
120
108
121
-
### Hard guardrails
109
+
**Hard guardrails** — the agent never crosses these:
-**Never push the default branch directly** — always a branch + PR.
111
+
-**Never force-push** (`git push --force`), and **never push the default branch directly** — always a branch + PR.
127
112
-**One logical change per PR**, kept reviewable; if a change balloons beyond a focused diff, it stops and hands the analysis back to you.
128
113
- Never delete branches, close others' issues / PRs, or change repository settings; never commit secrets, credentials, or build artifacts.
129
114
115
+
<Note>
116
+
If the agent reports it cannot access a repository in a cloud session, it usually means the account has not authorized the GitHub App, or the target repository was not granted — just authorize and grant it under **Plugins → Apps**. The agent does **not** ask you for any token.
117
+
</Note>
118
+
130
119
## Permissions & Scope
131
120
132
121
---
133
122
134
-
GitHub App **authorize** and **revoke** are **account-level** operations (`team_id = 0`). **The account is the only security boundary**; the team here is just an ownership / audit tag:
135
-
136
-
-**Who can authorize / revoke / enable / disable**: **any** account member with the corresponding action permission can authorize a new organization, revoke any installation, or enable / disable the whole App — these operations act on all installations in the account, not narrowed by team.
137
-
-**Runtime token resolution is account-level too**: when a session needs a repository, the token is resolved and minted from **any connected installation in the account** (`ResolveSessionToken` does not filter by team). Members of an account share one authorization — consistent with AI SRE's "usage = account-level, ownership = team tag" model for other resources.
123
+
GitHub App **authorize** and **revoke** are **account-level** operations. **The account is the only security boundary**; the team here is just an ownership / audit tag: any account member with the corresponding permission can authorize a new organization, revoke any installation, or enable / disable the whole App; when a session needs a repository, it obtains access from **any connected installation in the account**. Members of an account share one authorization — consistent with AI SRE's "usage = account-level, ownership = team tag" model for other resources.
0 commit comments