From 37a6a3894d251cbbc033b71d4005ca23951cf24b Mon Sep 17 00:00:00 2001 From: Lukasz Raczylo Date: Thu, 11 Dec 2025 12:51:32 +0000 Subject: [PATCH] Update token requirements documentation. --- README.md | 75 ++++++++++++++++++++++++ docs/index.html | 153 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 227 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0a8b03a..73974ad 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,9 @@ $ git-velocity serve --port 8080 - GitHub App authentication - Environment variable support +### 🔑 Required GitHub Token Permissions +See [Token Permissions](#-github-token-permissions) for detailed requirements. + ## 🚀 Quick Start ### Installation @@ -268,6 +271,78 @@ Git Velocity includes **95 hardcoded achievements** across 20 categories with mu | ✂️ Comment Trimmer | Removed 50 outdated comment lines | | 💀 Dead Code Hunter | Removed 500 outdated comment lines | +## 🔑 GitHub Token Permissions + +Git Velocity requires specific GitHub API permissions to fetch repository data. Below are the required permissions for each authentication method. + +### Personal Access Token (Classic) + +When creating a classic Personal Access Token, select the following scopes: + +| Scope | Required | Description | +|-------|----------|-------------| +| `repo` | ✅ Yes | Full access to private repositories (includes commits, PRs, issues) | +| `read:org` | ⚠️ If using org patterns | Required when using `pattern: "*"` to list organization repositories | + +> **Note**: For public repositories only, the `public_repo` scope is sufficient instead of full `repo` access. + +### Fine-Grained Personal Access Token (Recommended) + +Fine-grained tokens provide more granular control. Configure the following permissions: + +**Repository Permissions:** +| Permission | Access Level | Description | +|------------|--------------|-------------| +| Contents | Read | Access commit data and file contents | +| Pull requests | Read | Access PR data, reviews, and comments | +| Issues | Read | Access issue data and comments | +| Metadata | Read | Basic repository information (automatically included) | + +**Account Permissions:** +| Permission | Access Level | Description | +|------------|--------------|-------------| +| Email addresses | Read | Access public email for user deduplication | + +### GitHub App Authentication + +When using GitHub App authentication, configure the following permissions: + +**Repository Permissions:** +| Permission | Access Level | Description | +|------------|--------------|-------------| +| Contents | Read | Fetch commits and diffs | +| Pull requests | Read | Fetch PRs, reviews, and review comments | +| Issues | Read | Fetch issues and issue comments | +| Metadata | Read | Repository metadata (required) | + +**Organization Permissions (if using org patterns):** +| Permission | Access Level | Description | +|------------|--------------|-------------| +| Members | Read | List organization repositories | + +**Account Permissions:** +| Permission | Access Level | Description | +|------------|--------------|-------------| +| Email addresses | Read | User profile deduplication | + +### GitHub Actions (GITHUB_TOKEN) + +When running in GitHub Actions, the default `GITHUB_TOKEN` has sufficient permissions for repositories in the same organization/account. For cross-organization access, use a PAT or GitHub App. + +### API Endpoints Used + +Git Velocity uses the following GitHub REST API endpoints: + +| Endpoint | Purpose | +|----------|---------| +| `GET /orgs/{org}/repos` | List repositories by organization | +| `GET /repos/{owner}/{repo}/commits` | Fetch commit history | +| `GET /repos/{owner}/{repo}/commits/{sha}` | Fetch commit details with diff | +| `GET /repos/{owner}/{repo}/pulls` | List pull requests | +| `GET /repos/{owner}/{repo}/pulls/{number}/reviews` | Fetch PR reviews | +| `GET /repos/{owner}/{repo}/issues` | List issues | +| `GET /users/{username}` | Fetch user profile information | + ## ⚙️ Configuration ### Full Configuration Reference diff --git a/docs/index.html b/docs/index.html index d8b88f6..2b3adeb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -117,6 +117,7 @@ Achievements Installation GitHub Action + Permissions Configuration
@@ -140,6 +141,7 @@ Achievements Installation GitHub Action + Permissions Configuration
@@ -613,8 +615,157 @@ + +
+
+
+

GitHub Token Permissions

+

Required permissions for each authentication method

+
+
+ +
+

+ + Personal Access Token (Classic) +

+
+ + + + + + + + + + + + + + + + + + + + +
ScopeRequiredDescription
repo YesFull access to private repositories
read:org If using patternsRequired for pattern: "*" org listing
+
+

+ + For public repos only, public_repo scope is sufficient. +

+
+ + +
+

+ + Fine-Grained Token (Recommended) +

+

More secure with granular control over permissions.

+
+
+

Repository Permissions

+
    +
  • Contents: Read
    • +
  • Pull requests: Read
    • +
  • Issues: Read
    • +
  • Metadata: Read (auto)
    • +
+
+
+

Account Permissions

+
    +
  • Email addresses: Read
    • +
+
+
+
+ + +
+

+ + GitHub App Authentication +

+
+
+

Repository Permissions

+
    +
  • Contents: Read
    • +
  • Pull requests: Read
    • +
  • Issues: Read
    • +
  • Metadata: Read
    • +
+
+
+

Organization Permissions

+
    +
  • Members: Read (if using patterns)
    • +
+

Account Permissions

+
    +
  • Email addresses: Read
    • +
+
+
+
+ + +
+

+ + API Endpoints Used +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointPurpose
GET /orgs/{org}/reposList organization repositories
GET /repos/{owner}/{repo}/commitsFetch commit history
GET /repos/{owner}/{repo}/commits/{sha}Fetch commit details with diff
GET /repos/{owner}/{repo}/pullsList pull requests
GET /repos/{owner}/{repo}/pulls/{n}/reviewsFetch PR reviews
GET /repos/{owner}/{repo}/issuesList issues
GET /users/{username}Fetch user profile
+
+
+
+
+
+ -
+

Configuration