Expand token creation documentation in README

README.md

@@ -4,14 +4,86 @@ A template to get started with [GitHub Agentic Workflows](https://githubnext.git
 
 ## Quick Setup
 
-To use Copilot in your workflows, configure a GitHub token:
-
-1. Create a [Personal Access Token](https://github.com/settings/personal-access-tokens/new) with **Copilot Requests** permission
-2. Add it as a repository secret named `COPILOT_GITHUB_TOKEN`:
-   - Go to **Settings** > **Secrets and variables** > **Actions**
-   - Click **New repository secret**
-   - Name: `COPILOT_GITHUB_TOKEN`
-   - Paste your token and click **Add secret**
+To use GitHub Agentic Workflows, you'll need to configure GitHub tokens for authentication. GitHub Actions provides a default `GITHUB_TOKEN` automatically, but you'll need to create additional tokens for specific features.
+
+### Token Overview
+
+| Token Name | When You Need It | Required For |
+|------------|------------------|--------------|
+| `COPILOT_GITHUB_TOKEN` | Copilot workflows | AI agent tasks, Copilot engine |
+| `GH_AW_GITHUB_TOKEN` | Cross-repo operations | Accessing other repositories, remote GitHub tools |
+| `GH_AW_PROJECT_GITHUB_TOKEN` | GitHub Projects v2 | Creating/updating project boards |
+| `GH_AW_AGENT_TOKEN` | Agent assignments | Assigning Copilot bots to issues/PRs |
+
+### Creating Tokens
+
+#### 1. Copilot Token (Most Common)
+
+For workflows using the Copilot engine or AI features:
+
+1. Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
+2. Configure the token:
+   - **Token name**: "Copilot Agentic Workflows"
+   - **Resource owner**: Your user account
+   - **Repository access**: Choose "Public repositories" or select specific repos
+   - **Permissions**:
+     - **Account permissions** → **Copilot Requests**: Access ✅ (Required)
+3. Click **Generate token** and copy the token value
+
+#### 2. Cross-Repository Token (For Multi-Repo Workflows)
+
+For workflows that need to access multiple repositories:
+
+1. Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
+2. Configure the token:
+   - **Token name**: "Agentic Workflows Cross-Repo"
+   - **Repository access**: "All repositories" or select specific repos
+   - **Permissions**:
+     - **Repository permissions**:
+       - **Contents**: Read (minimum) or Read+Write (for creating PRs)
+       - **Issues**: Read+Write (for issue operations)
+       - **Pull requests**: Read+Write (for PR operations)
+3. Click **Generate token** and copy the token value
+
+#### 3. Projects Token (For GitHub Projects v2)
+
+For workflows that manage GitHub Projects:
+
+**For User-owned Projects:**
+- Use a [Classic PAT](https://github.com/settings/tokens/new) with `project` scope
+- Fine-grained PATs do **not** work with user-owned Projects
+
+**For Organization-owned Projects:**
+1. Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
+2. Configure the token:
+   - **Token name**: "Agentic Workflows Projects"
+   - **Repository access**: Select specific repos or "All repositories"
+   - **Organization permissions** (must be explicitly granted):
+     - **Organization access**: Grant to the target organization
+     - **Projects**: Read+Write
+3. Click **Generate token** and copy the token value
+
+### Adding Tokens to Your Repository
+
+After creating tokens, add them as repository secrets:
+
+1. Go to your repository → **Settings** → **Secrets and variables** → **Actions**
+2. Click **New repository secret**
+3. Enter the secret name (e.g., `COPILOT_GITHUB_TOKEN`) and paste your token value
+4. Click **Add secret**
+5. Repeat for each token you created
+
+### Security Best Practices
+
+- **Least privilege**: Only grant the minimum permissions needed for each token
+- **Scope to specific repos**: Use fine-grained tokens with access to only necessary repositories
+- **Use workflow-level permissions**: Restrict `GITHUB_TOKEN` using `permissions:` in your workflows:
+  ```yaml
+  permissions:
+    contents: read
+    issues: write
+  ```
+- **Consider GitHub Apps**: For production workflows, use GitHub App tokens for enhanced security with short-lived, auto-revoked credentials
 
 ## Learn More