Skip to content

docs(github): remove stale PAT/notifications references from GitHub MCP server docs #996

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jottakka wants to merge 1 commit into
base: main
Choose a base branch
from
+6 −26
Open

docs(github): remove stale PAT/notifications references from GitHub MCP server docs #996

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 2 additions & 22 deletions app/en/references/auth-providers/github/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -822,11 +822,10 @@ This section lists the GitHub App permissions required by tools in the Arcade Gi
| **Repositories** | Contents (Read/Write for file ops), Metadata (Read), Members (Read for org repos) |
| **Reviews** | Contents (Read), Pull requests (Read/Write), Metadata (Read) |
| **User Context** | Read user profile, Members (Read for orgs) |
| **Notifications** | ⚠️ Classic PAT with `notifications` scope (GitHub Apps limitation) |

### Detailed Permissions by Category

<Tabs items={["Issues", "Pull Requests", "Projects", "Repositories", "User Context", "Special Cases"]}>
<Tabs items={["Issues", "Pull Requests", "Projects", "Repositories", "User Context", "Act on Behalf of User"]}>
<Tabs.Tab>

**Issues Tools** (7 tools):
Expand Down Expand Up @@ -914,18 +913,7 @@ This section lists the GitHub App permissions required by tools in the Arcade Gi
</Tabs.Tab>
<Tabs.Tab>

**⚠️ Notifications Tools**

GitHub Apps **cannot** access the notifications API. This is a [platform limitation by design](https://docs.github.com/en/rest/activity/notifications).

**Workaround:**

- Tools: `get_notification_summary`, `list_notifications`
- **Required**: Classic Personal Access Token with `notifications` scope
- **Create at**: [github.com/settings/tokens](https://github.com/settings/tokens)
- **Why**: Notifications are personal user data, not accessible to apps by GitHub's design

**User-on-Behalf-of Actions:**
**Act on Behalf of User**

The "Act on behalf of user" permission is only needed for specific user-attributed actions:

Expand Down Expand Up @@ -1029,7 +1017,6 @@ After initial installation, you can add more repositories:
| **"Installation not found"** | Wrong Installation ID | Check Installation ID in URL |
| **"403 Forbidden"** | Missing permissions, not installed, or rate limited | Review permissions, check installation |
| **"404 Not Found" on existing repo** | Permissions not approved by admin | Check app settings → verify permissions approved |
| **Notifications not working** | GitHub Apps can't access notifications | Use classic PAT with `notifications` scope |
| **Can't star repositories** | Missing "Act on behalf of user" permission | Enable in User permissions settings |

### Debugging Steps
Expand Down Expand Up @@ -1110,13 +1097,6 @@ A: Starring repositories requires the "Act on behalf of user" permission:
- The app can still read and perform other actions without this permission
- [Why this permission exists](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)

**Q: Why can't I access notifications?**
A: Notifications require a classic PAT (GitHub Apps cannot access notifications API by design):

- This is a platform limitation, not an Arcade limitation
- Create a classic PAT at [github.com/settings/tokens](https://github.com/settings/tokens) with `notifications` scope
- [Why GitHub Apps can't access notifications](https://docs.github.com/en/rest/activity/notifications)

### Security

**Q: What if my credentials are compromised?**
Expand Down
8 changes: 4 additions & 4 deletions toolkit-docs-generator/data/toolkits/github.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2096,7 +2096,7 @@
"name": "since",
"type": "string",
"required": false,
"description": "Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.",
"description": "Only show issues updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.",
"enum": null,
"inferrable": true
},
Expand Down Expand Up @@ -5829,7 +5829,7 @@
"type": "info",
"location": "description",
"position": "after",
"content": "<Callout type=\"info\">\n **Configuration Required**: All tools require secrets to be configured in Arcade Dashboard. See [Secrets Setup](#secrets-setup) below.\n</Callout>"
"content": "<Callout type=\"info\">\n **Configuration**: On Arcade Cloud, these tools work out of the box. Self-hosted and GitHub Enterprise Server users can set the `GITHUB_SERVER_URL` secret in Arcade Dashboard. See [Secrets Setup](#secrets-setup) below.\n</Callout>"
},
{
"type": "info",
Expand All @@ -5842,14 +5842,14 @@
"type": "section",
"location": "before_available_tools",
"position": "after",
"content": "## GitHub App Permissions Summary\n\nWhen creating your GitHub App, you'll need to grant specific permissions. Here's a quick reference of which tools require which permissions:\n\n### Repository Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Contents** | Read | All repository and pull request tools, getting file contents |\n| **Contents** | Write | Creating/updating files, creating branches, merging PRs |\n| **Issues** | Read & Write | Issue management, PR assignments, managing labels (Issues) |\n| **Pull requests** | Read & Write | Pull request management, reviews, managing labels (PRs) |\n| **Metadata** | Read | All tools (automatically granted) |\n| **Statuses** | Read | `CheckPullRequestMergeStatus` |\n\n### Organization Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Members** | Read | Projects, collaborators, org repos, user search |\n| **Projects** | Read & Write | All Projects V2 tools |\n\n### User Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Read user profile** | Read | User context tools, review workload |\n| **Act on behalf of user** | Enabled | `SetStarred` (starring repositories) |\n\n### Tools by Permission Requirements\n\n<details>\n<summary><b>Basic Repository Access</b> (Contents Read + Metadata)</summary>\n\n- `GetRepository`\n- `CountStargazers`\n- `ListStargazers`\n- `ListRepositoryActivities`\n- `GetFileContents`\n\n</details>\n\n<details>\n<summary><b>Repository Write</b> (Contents Write + Metadata)</summary>\n\n- `CreateBranch`\n- `CreateOrUpdateFile`\n- `UpdateFileLines`\n\n</details>\n\n<details>\n<summary><b>Issue Management</b> (Contents Read + Issues + Metadata)</summary>\n\n- `CreateIssue`\n- `UpdateIssue`\n- `GetIssue`\n- `ListIssues`\n- `CreateIssueComment`\n- `ListRepositoryLabels`\n- `ManageLabels` (for issues)\n\n</details>\n\n<details>\n<summary><b>Pull Request Read</b> (Contents + Pull requests Read + Metadata)</summary>\n\n- `ListPullRequests`\n- `GetPullRequest`\n- `ListPullRequestCommits`\n- `ListReviewCommentsOnPullRequest`\n- `CheckPullRequestMergeStatus` (+ Statuses)\n\n</details>\n\n<details>\n<summary><b>Pull Request Write</b> (Contents Read + Pull requests Write + Metadata)</summary>\n\n- `UpdatePullRequest`\n- `CreatePullRequest`\n- `SubmitPullRequestReview`\n- `ManagePullRequest`\n- `ManagePullRequestReviewers`\n- `CreateReviewComment`\n- `CreateReplyForReviewComment`\n- `ResolveReviewThread`\n- `ManageLabels` (for pull requests)\n- `MergePullRequest` (+ Contents Write)\n\n</details>\n\n<details>\n<summary><b>Organization Tools</b> (Contents + Metadata + Members)</summary>\n\n- `ListOrgRepositories`\n- `SearchMyRepos`\n- `ListRepositoryCollaborators`\n- `AssignPullRequestUser` (+ Issues Write)\n\n</details>\n\n<details>\n<summary><b>Projects V2</b> (Contents + Metadata + Projects + Members)</summary>\n\n- `ListProjects`\n- `ListProjectItems`\n- `SearchProjectItem`\n- `ListProjectFields`\n- `UpdateProjectItem` (Projects Write)\n\n</details>\n\n<details>\n<summary><b>User Context</b> (Contents + Metadata + Read user profile)</summary>\n\n- `WhoAmI` (+ Members)\n- `GetUserRecentActivity`\n- `GetUserOpenItems`\n- `GetReviewWorkload` (+ Pull requests Read)\n\n</details>\n\n<details>\n<summary><b>⚠️ Special: Notifications</b> (Requires Classic PAT)</summary>\n\n- `GetNotificationSummary`\n- `ListNotifications`\n\n**Note**: GitHub Apps cannot access notifications API. Requires classic Personal Access Token with `notifications` scope.\n\n</details>\n\n---",
"content": "## GitHub App Permissions Summary\n\nWhen creating your GitHub App, you'll need to grant specific permissions. Here's a quick reference of which tools require which permissions:\n\n### Repository Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Contents** | Read | All repository and pull request tools, getting file contents |\n| **Contents** | Write | Creating/updating files, creating branches, merging PRs |\n| **Issues** | Read & Write | Issue management, PR assignments, managing labels (Issues) |\n| **Pull requests** | Read & Write | Pull request management, reviews, managing labels (PRs) |\n| **Metadata** | Read | All tools (automatically granted) |\n| **Statuses** | Read | `CheckPullRequestMergeStatus` |\n\n### Organization Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Members** | Read | Projects, collaborators, org repos, user search |\n| **Projects** | Read & Write | All Projects V2 tools |\n\n### User Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Read user profile** | Read | User context tools, review workload |\n| **Act on behalf of user** | Enabled | `SetStarred` (starring repositories) |\n\n### Tools by Permission Requirements\n\n<details>\n<summary><b>Basic Repository Access</b> (Contents Read + Metadata)</summary>\n\n- `GetRepository`\n- `CountStargazers`\n- `ListStargazers`\n- `ListRepositoryActivities`\n- `GetFileContents`\n\n</details>\n\n<details>\n<summary><b>Repository Write</b> (Contents Write + Metadata)</summary>\n\n- `CreateBranch`\n- `CreateOrUpdateFile`\n- `UpdateFileLines`\n\n</details>\n\n<details>\n<summary><b>Issue Management</b> (Contents Read + Issues + Metadata)</summary>\n\n- `CreateIssue`\n- `UpdateIssue`\n- `GetIssue`\n- `ListIssues`\n- `CreateIssueComment`\n- `ListRepositoryLabels`\n- `ManageLabels` (for issues)\n\n</details>\n\n<details>\n<summary><b>Pull Request Read</b> (Contents + Pull requests Read + Metadata)</summary>\n\n- `ListPullRequests`\n- `GetPullRequest`\n- `ListPullRequestCommits`\n- `ListReviewCommentsOnPullRequest`\n- `CheckPullRequestMergeStatus` (+ Statuses)\n\n</details>\n\n<details>\n<summary><b>Pull Request Write</b> (Contents Read + Pull requests Write + Metadata)</summary>\n\n- `UpdatePullRequest`\n- `CreatePullRequest`\n- `SubmitPullRequestReview`\n- `ManagePullRequest`\n- `ManagePullRequestReviewers`\n- `CreateReviewComment`\n- `CreateReplyForReviewComment`\n- `ResolveReviewThread`\n- `ManageLabels` (for pull requests)\n- `MergePullRequest` (+ Contents Write)\n\n</details>\n\n<details>\n<summary><b>Organization Tools</b> (Contents + Metadata + Members)</summary>\n\n- `ListOrgRepositories`\n- `SearchMyRepos`\n- `ListRepositoryCollaborators`\n- `AssignPullRequestUser` (+ Issues Write)\n\n</details>\n\n<details>\n<summary><b>Projects V2</b> (Contents + Metadata + Projects + Members)</summary>\n\n- `ListProjects`\n- `ListProjectItems`\n- `SearchProjectItem`\n- `ListProjectFields`\n- `UpdateProjectItem` (Projects Write)\n\n</details>\n\n<details>\n<summary><b>User Context</b> (Contents + Metadata + Read user profile)</summary>\n\n- `WhoAmI` (+ Members)\n- `GetUserRecentActivity`\n- `GetUserOpenItems`\n- `GetReviewWorkload` (+ Pull requests Read)\n\n</details>\n\n---",
"header": "## GitHub App Permissions Summary"
},
{
"type": "warning",
"location": "custom_section",
"position": "after",
"content": "## Configuration & Setup\n\n### Authentication\n\n<Callout type=\"warning\">\n **Critical**: This MCP Server uses **GitHub Apps** authentication, not OAuth Apps.\n \n You **must** create a GitHub App to use this server. OAuth Apps are not supported.\n</Callout>\n\nThe Arcade GitHub MCP Server uses the [GitHub auth provider](/references/auth-providers/github) to connect to users' GitHub accounts.\n\n**For Arcade Cloud:**\n- No configuration needed\n- Your users will see `Arcade` as the requesting application\n- All tools work out of the box\n\n**For Self-Hosted:**\n- You must [create your own GitHub App](/references/auth-providers/github#creating-a-github-app)\n- [Configure the GitHub auth provider](/references/auth-providers/github#configuring-github-auth-in-arcade) with your app credentials\n- Your users will see your application name\n\n<Callout type=\"info\">\n **New to GitHub Apps?** Read [Why Arcade Uses GitHub Apps](/references/auth-providers/github#why-arcade-uses-github-apps-not-oauth-apps) \n to understand the security and compliance benefits.\n</Callout>\n\n### Secrets Setup\n\nAll tools require secrets to be configured in Arcade Dashboard.\n\n**Steps:**\n\n1. Go to [Arcade Dashboard](https://api.arcade.dev/dashboard)\n2. Navigate to **Secrets** in the left sidebar\n3. Click **Add Secret**\n4. Add the following secrets:\n\n| Secret Name | Value | Required For |\n|-------------|-------|--------------|\n| `GITHUB_SERVER_URL` | `https://api.github.com` (default for GitHub.com) | All tools |\n| `GITHUB_CLASSIC_PERSONAL_ACCESS_TOKEN` | Classic PAT with `notifications` scope | Notifications tools only |\n\n<Callout type=\"info\">\n **Default**: If `GITHUB_SERVER_URL` is not configured, it defaults to `https://api.github.com` (GitHub.com)\n \n **GitHub Enterprise Users**: Set `GITHUB_SERVER_URL` to your Enterprise server's API endpoint (e.g., `https://github.yourcompany.com/api/v3`). Note that Enterprise uses `/api/v3` path. See [GitHub Enterprise Support](#github-enterprise-support) for details.\n</Callout>\n\n<Callout type=\"warning\">\n **For Notifications Tools**: Create a classic Personal Access Token at [github.com/settings/tokens](https://github.com/settings/tokens) with only the `notifications` scope checked. GitHub Apps cannot access the notifications API.\n</Callout>\n\n---",
"content": "## Configuration & Setup\n\n### Authentication\n\n<Callout type=\"warning\">\n **Critical**: This MCP Server uses **GitHub Apps** authentication, not OAuth Apps.\n \n You **must** create a GitHub App to use this server. OAuth Apps are not supported.\n</Callout>\n\nThe Arcade GitHub MCP Server uses the [GitHub auth provider](/references/auth-providers/github) to connect to users' GitHub accounts.\n\n**For Arcade Cloud:**\n- No configuration needed\n- Your users will see `Arcade` as the requesting application\n- All tools work out of the box\n\n**For Self-Hosted:**\n- You must [create your own GitHub App](/references/auth-providers/github#creating-a-github-app)\n- [Configure the GitHub auth provider](/references/auth-providers/github#configuring-github-auth-in-arcade) with your app credentials\n- Your users will see your application name\n\n<Callout type=\"info\">\n **New to GitHub Apps?** Read [Why Arcade Uses GitHub Apps](/references/auth-providers/github#why-arcade-uses-github-apps-not-oauth-apps) \n to understand the security and compliance benefits.\n</Callout>\n\n### Secrets Setup\n\nGitHub tools read an optional `GITHUB_SERVER_URL` secret from the Arcade Dashboard. It defaults to `https://api.github.com`, so you only need to set it for GitHub Enterprise Server.\n\n**Steps:**\n\n1. Go to [Arcade Dashboard](https://api.arcade.dev/dashboard)\n2. Navigate to **Secrets** in the left sidebar\n3. Click **Add Secret**\n4. Add the following secrets:\n\n| Secret Name | Value | Required For |\n|-------------|-------|--------------|\n| `GITHUB_SERVER_URL` | `https://api.github.com` (default for GitHub.com) | All tools |\n\n<Callout type=\"info\">\n **Default**: If `GITHUB_SERVER_URL` is not configured, it defaults to `https://api.github.com` (GitHub.com)\n \n **GitHub Enterprise Users**: Set `GITHUB_SERVER_URL` to your Enterprise server's API endpoint (e.g., `https://github.yourcompany.com/api/v3`). Note that Enterprise uses `/api/v3` path. See [GitHub Enterprise Support](#github-enterprise-support) for details.\n</Callout>\n\n---",
"header": "## Configuration & Setup"
}
],
Expand Down
Loading