Skip to content

Expand token creation documentation in README #9

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

Merged
pelikhan merged 6 commits into from
Dec 20, 2025
Merged

Expand token creation documentation in README #9

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bbb4763
Initial plan
Copilot Dec 20, 2025
bf379e0
Add comprehensive token creation details to README
Copilot Dec 20, 2025
29e75e2
Remove CLI instructions for token management, keep only UI method
Copilot Dec 20, 2025
6dcee3b
Restructure README: document COPILOT_GITHUB_TOKEN end-to-end first
Copilot Dec 20, 2025
d85add4
Remove Security Best Practices section
Copilot Dec 20, 2025
8d188f0
Convert numbered lists to checkboxes for todo items
Copilot Dec 20, 2025
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
103 changes: 95 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,101 @@ 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 with Copilot, you need to configure a `COPILOT_GITHUB_TOKEN`. GitHub Actions provides a default `GITHUB_TOKEN` automatically, but it doesn't have the permissions needed for Copilot features.

### Setting Up Your Copilot Token

#### Step 1: Create the Token

- [ ] Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
- [ ] 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)
- [ ] Click **Generate token** and copy the token value

#### Step 2: Add Token to Your Repository

- [ ] Go to your repository → **Settings** → **Secrets and variables** → **Actions**
- [ ] Click **New repository secret**
- [ ] Enter the secret name: `COPILOT_GITHUB_TOKEN`
- [ ] Paste your token value
- [ ] Click **Add secret**

That's it! Your workflows can now use Copilot.

### Additional Tokens (Advanced)

For advanced workflows, you may need additional tokens:

| Token Name | When You Need It | Required For |
|------------|------------------|--------------|
| `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 |

<details>
<summary><b>Creating Cross-Repository Token</b></summary>

For workflows that need to access multiple repositories:

- [ ] Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
- [ ] 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)
- [ ] Click **Generate token** and copy the token value
- [ ] Add to repository secrets as `GH_AW_GITHUB_TOKEN`

</details>

<details>
<summary><b>Creating Projects Token</b></summary>

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:**
- [ ] Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
- [ ] 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
- [ ] Click **Generate token** and copy the token value
- [ ] Add to repository secrets as `GH_AW_PROJECT_GITHUB_TOKEN`

</details>

<details>
<summary><b>Creating Agent Assignment Token</b></summary>

For workflows that assign Copilot bots to issues or pull requests:

- [ ] Go to [GitHub Settings → Personal Access Tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)
- [ ] Configure the token:
- **Token name**: "Agentic Workflows Agent"
- **Repository access**: Select specific repos
- **Permissions**:
- **Repository permissions**:
- **Actions**: Write
- **Contents**: Write
- **Issues**: Write
- **Pull requests**: Write
- [ ] Click **Generate token** and copy the token value
- [ ] Add to repository secrets as `GH_AW_AGENT_TOKEN`

</details>

## Learn More

Expand Down