Skip to content

Commit 0140434

Browse files
Copilotaustenstone
Copilot
and
austenstone
committed
docs: add comprehensive documentation for organization token limitations and two-token workaround
Co-authored-by: austenstone <22425467+austenstone@users.noreply.github.com>
1 parent 8647073 commit 0140434

2 files changed

Lines changed: 194 additions & 159 deletions

File tree

‎README.md‎

Lines changed: 192 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,192 @@
1-
# GitHub Copilot CLI Action 🤖
2-
3-
A GitHub Action wrapper for the [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) that enables AI-powered automation in your workflow files.
4-
5-
## Installation
6-
7-
### Token Setup
8-
9-
> [!WARNING]
10-
> The default `GITHUB_TOKEN` does **NOT** have Copilot permissions!
11-
12-
You need a **Personal Access Token (PAT)** with Copilot access.
13-
14-
**🚀 Quick Setup:** [Create Copilot CLI Token (Pre-configured)](https://github.com/settings/personal-access-tokens/new?name=Copilot+CLI+Token&description=GitHub+Copilot+CLI+automation+for+workflows&expires_in=90&user_copilot_requests=read)
15-
16-
At minimum, you need: **`Copilot Requests = Read-only`**
17-
18-
> [!TIP]
19-
> Save your token as a repository secret named `COPILOT_TOKEN`
20-
21-
### Basic Setup
22-
23-
Add the following workflow to your `.github/workflows` folder:
24-
25-
```yaml
26-
name: 'Copilot Automation'
27-
on: [pull_request]
28-
29-
jobs:
30-
copilot:
31-
permissions:
32-
pull-requests: write
33-
runs-on: ubuntu-latest
34-
steps:
35-
- name: 'Checkout Repository'
36-
uses: actions/checkout@v5
37-
38-
- name: 'Run Copilot CLI'
39-
uses: austenstone/copilot-cli@v2
40-
with:
41-
copilot-token: ${{ secrets.COPILOT_TOKEN }}
42-
prompt: |
43-
Review this pull request for:
44-
1. Code quality and best practices
45-
2. Security vulnerabilities
46-
3. Performance implications
47-
4. Documentation completeness
48-
```
49-
50-
### Advanced Setup with MCP Servers
51-
52-
```yaml
53-
prompt: 'What time is it?'
54-
mcp-config: |
55-
{
56-
"mcpServers": {
57-
"time": {
58-
"type": "local",
59-
"command": "uvx",
60-
"args": ["mcp-server-time", "--local-timezone", "America/New_York"],
61-
"tools": ["*"]
62-
}
63-
}
64-
}
65-
```
66-
67-
## Configuration
68-
69-
### Input Parameters
70-
71-
| Parameter | Description | Required | Default |
72-
|-----------|-------------|----------|---------|
73-
| `copilot-token` | PAT with "Copilot Requests" permission. **The default `github.token` does NOT work** — you must provide a PAT. | ✅ | - |
74-
| `prompt` | Natural language prompt to send to GitHub Copilot | ✅ | - |
75-
| `repo-token` | Token for standard GitHub repo operations (push, PRs). Falls back to `copilot-token` if not set. Can use default `GITHUB_TOKEN` here. | ❌ | `github.token` |
76-
| `mcp-config` | MCP server configuration in JSON format | ❌ | - |
77-
| `copilot-config` | GitHub Copilot CLI configuration (JSON) | ❌ | See below |
78-
| `allow-all-tools` | Allow all tools without approval | ❌ | `true` |
79-
| `allowed-tools` | Comma-separated list of tools to allow (e.g., `"shell(rm),shell(git push)"`) | ❌ | - |
80-
| `denied-tools` | Comma-separated list of tools to deny (e.g., `"shell(rm),shell(git push)"`) | ❌ | - |
81-
| `copilot-version` | Version of `@github/copilot` to install (e.g., `"latest"`, `"0.0.329"`) | ❌ | `latest` |
82-
| `model` | AI model to use (e.g., `"claude-sonnet-4.5"`, `"gpt-5"`) | ❌ | - |
83-
| `agent` | Specify a custom agent to use | ❌ | - |
84-
| `additional-directories` | Comma-separated list of additional directories to trust (e.g., `"/tmp,/var/log"`) | ❌ | - |
85-
| `disable-mcp-servers` | Comma-separated list of MCP servers to disable (e.g., `"github-mcp-server,custom-server"`) | ❌ | - |
86-
| `enable-all-github-mcp-tools` | Enable all GitHub MCP tools | ❌ | `false` |
87-
| `resume-session` | Resume from a previous session ID (use `"latest"` for most recent) | ❌ | - |
88-
| `log-level` | Log level: `"none"`, `"error"`, `"warning"`, `"info"`, `"debug"`, `"all"`, `"default"` | ❌ | `all` |
89-
| `upload-artifact` | Upload Copilot logs as workflow artifacts | ❌ | `true` |
90-
91-
### MCP Server Configuration
92-
93-
The action supports Model Context Protocol (MCP) servers for extending Copilot's capabilities. Configure MCP servers using JSON format with an `mcpServers` object where each key is the server name and the value contains its configuration.
94-
95-
> [!IMPORTANT]
96-
> See the [official MCP server configuration docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers) for complete details.
97-
98-
## Examples
99-
100-
<details>
101-
<summary>📋 <strong>View All Example Workflows</strong></summary>
102-
103-
| Workflow | Description |
104-
|----------|-------------|
105-
| [CI Fix](.github/workflows/copilot-ci-fix.yml) | Automatically analyzes failed workflow runs and creates a pull request with fixes |
106-
| [Comment Trigger](.github/workflows/copilot-comment.yml) | Responds to issue comments starting with `/copilot` and executes the requested task |
107-
| [Dependabot Analysis](.github/workflows/copilot-dependabot-update.yml) | Reviews Dependabot PRs with detailed dependency analysis, breaking changes, and migration guidance |
108-
| [PR Review](.github/workflows/copilot-pr-review.yml) | Performs comprehensive autonomous code reviews on pull requests with severity-based feedback |
109-
| [Research](.github/workflows/copilot-research.yml) | Conducts deep research on GitHub issues using Firecrawl to gather and synthesize information |
110-
| [Security Triage](.github/workflows/copilot-security-triage.yml) | Triages all security alerts (Dependabot, Secret Scanning, Code Scanning) into a single comprehensive report |
111-
| [Issue Triage](.github/workflows/copilot-triage.yml) | Automatically labels issues based on their title and content using existing repository labels |
112-
| [Usage Report](.github/workflows/copilot-usage-report.yml) | Generates comprehensive Copilot usage reports and analytics |
113-
114-
</details>
115-
116-
## Troubleshooting
117-
118-
> [!NOTE]
119-
> Most issues stem from token configuration.
120-
121-
### Common Issues
122-
123-
1. **"Copilot token required" / Permission Denied**
124-
- The default `GITHUB_TOKEN` does NOT have Copilot access
125-
- You must use a PAT with the "Copilot Requests" permission
126-
- Make sure your token is saved as a secret and referenced correctly
127-
128-
2. **Copilot starts but permission denied**
129-
- The repo-token default to `GITHUB_TOKEN`.
130-
- Add `permissions: write-all` to your workflow file.
131-
- Check Settings > Actions > General > Workflow permissions.
132-
- Verify the token is correctly configured in your workflow.
133-
134-
3. **Tool Access Denied**
135-
- Check your `allowed-tools` and `denied-tools` configuration
136-
- If `allow-all-tools: false`, you must explicitly allow needed tools
137-
138-
4. **MCP Server Connection Issues**
139-
- Verify MCP server URLs are accessible from GitHub-hosted runners
140-
- Check authentication headers and tokens
141-
- Ensure `type` is set correctly (`local`, `http`, or `sse`)
142-
143-
5. **Session Resume Not Working**
144-
- Session data is stored in logs; ensure `upload-artifact: true`
145-
- Use `resume-session: latest` to continue the most recent session
146-
147-
6. **Large Output Truncation**
148-
- Set `log-level: error` or `log-level: warning` to reduce verbosity
149-
- Break complex prompts into smaller, focused tasks
150-
151-
## Related Resources
152-
153-
- [GitHub Copilot CLI Documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli)
154-
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
155-
- [MCP Server Configuration Docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers)
156-
- [Search for workflow examples](https://github.com/search?q=%22copilot+-p%22+path%3A.github%2Fworkflows%2F*.yml&ref=opensearch&type=code)
157-
1+
# GitHub Copilot CLI Action 🤖
2+
3+
A GitHub Action wrapper for the [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) that enables AI-powered automation in your workflow files.
4+
5+
## Installation
6+
7+
### Token Setup
8+
9+
> [!WARNING]
10+
> The default `GITHUB_TOKEN` does **NOT** have Copilot permissions!
11+
12+
You need a **Personal Access Token (PAT)** with Copilot access.
13+
14+
**🚀 Quick Setup:** [Create Copilot CLI Token (Pre-configured)](https://github.com/settings/personal-access-tokens/new?name=Copilot+CLI+Token&description=GitHub+Copilot+CLI+automation+for+workflows&expires_in=90&user_copilot_requests=read)
15+
16+
At minimum, you need: **`Copilot Requests = Read-only`**
17+
18+
> [!TIP]
19+
> Save your token as a repository secret named `COPILOT_TOKEN`
20+
21+
#### Organization Repositories
22+
23+
> [!IMPORTANT]
24+
> **Fine-grained PAT Limitation:** Organization-owned tokens cannot have the "Copilot Requests" permission — this is a GitHub platform limitation.
25+
>
26+
> **Workaround for Organization Repos:**
27+
> 1. Use a **user-owned PAT** with "Copilot Requests" permission for `copilot-token`
28+
> 2. Use the default `GITHUB_TOKEN` or an org token for `repo-token` (for repository operations)
29+
>
30+
> ```yaml
31+
> - uses: austenstone/copilot-cli@v2
32+
> with:
33+
> copilot-token: ${{ secrets.COPILOT_TOKEN }} # User PAT with Copilot access
34+
> repo-token: ${{ secrets.GITHUB_TOKEN }} # Default token for repo operations
35+
> prompt: "Your prompt here"
36+
> ```
37+
>
38+
> This two-token pattern allows Copilot access while maintaining proper repository permissions.
39+
40+
### Basic Setup
41+
42+
Add the following workflow to your `.github/workflows` folder:
43+
44+
```yaml
45+
name: 'Copilot Automation'
46+
on: [pull_request]
47+
48+
jobs:
49+
copilot:
50+
permissions:
51+
pull-requests: write
52+
runs-on: ubuntu-latest
53+
steps:
54+
- name: 'Checkout Repository'
55+
uses: actions/checkout@v5
56+
57+
- name: 'Run Copilot CLI'
58+
uses: austenstone/copilot-cli@v2
59+
with:
60+
copilot-token: ${{ secrets.COPILOT_TOKEN }}
61+
prompt: |
62+
Review this pull request for:
63+
1. Code quality and best practices
64+
2. Security vulnerabilities
65+
3. Performance implications
66+
4. Documentation completeness
67+
```
68+
69+
### Advanced Setup with MCP Servers
70+
71+
```yaml
72+
prompt: 'What time is it?'
73+
mcp-config: |
74+
{
75+
"mcpServers": {
76+
"time": {
77+
"type": "local",
78+
"command": "uvx",
79+
"args": ["mcp-server-time", "--local-timezone", "America/New_York"],
80+
"tools": ["*"]
81+
}
82+
}
83+
}
84+
```
85+
86+
## Configuration
87+
88+
### Input Parameters
89+
90+
| Parameter | Description | Required | Default |
91+
|-----------|-------------|----------|---------|
92+
| `copilot-token` | PAT with "Copilot Requests" permission. **The default `github.token` does NOT work** — you must provide a PAT. | ✅ | - |
93+
| `prompt` | Natural language prompt to send to GitHub Copilot | ✅ | - |
94+
| `repo-token` | Token for standard GitHub repo operations (push, PRs). Falls back to `copilot-token` if not set. Can use default `GITHUB_TOKEN` here. | ❌ | `github.token` |
95+
| `mcp-config` | MCP server configuration in JSON format | ❌ | - |
96+
| `copilot-config` | GitHub Copilot CLI configuration (JSON) | ❌ | See below |
97+
| `allow-all-tools` | Allow all tools without approval | ❌ | `true` |
98+
| `allowed-tools` | Comma-separated list of tools to allow (e.g., `"shell(rm),shell(git push)"`) | ❌ | - |
99+
| `denied-tools` | Comma-separated list of tools to deny (e.g., `"shell(rm),shell(git push)"`) | ❌ | - |
100+
| `copilot-version` | Version of `@github/copilot` to install (e.g., `"latest"`, `"0.0.329"`) | ❌ | `latest` |
101+
| `model` | AI model to use (e.g., `"claude-sonnet-4.5"`, `"gpt-5"`) | ❌ | - |
102+
| `agent` | Specify a custom agent to use | ❌ | - |
103+
| `additional-directories` | Comma-separated list of additional directories to trust (e.g., `"/tmp,/var/log"`) | ❌ | - |
104+
| `disable-mcp-servers` | Comma-separated list of MCP servers to disable (e.g., `"github-mcp-server,custom-server"`) | ❌ | - |
105+
| `enable-all-github-mcp-tools` | Enable all GitHub MCP tools | ❌ | `false` |
106+
| `resume-session` | Resume from a previous session ID (use `"latest"` for most recent) | ❌ | - |
107+
| `log-level` | Log level: `"none"`, `"error"`, `"warning"`, `"info"`, `"debug"`, `"all"`, `"default"` | ❌ | `all` |
108+
| `upload-artifact` | Upload Copilot logs as workflow artifacts | ❌ | `true` |
109+
110+
### MCP Server Configuration
111+
112+
The action supports Model Context Protocol (MCP) servers for extending Copilot's capabilities. Configure MCP servers using JSON format with an `mcpServers` object where each key is the server name and the value contains its configuration.
113+
114+
> [!IMPORTANT]
115+
> See the [official MCP server configuration docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers) for complete details.
116+
117+
## Examples
118+
119+
<details>
120+
<summary>📋 <strong>View All Example Workflows</strong></summary>
121+
122+
| Workflow | Description |
123+
|----------|-------------|
124+
| [CI Fix](.github/workflows/copilot-ci-fix.yml) | Automatically analyzes failed workflow runs and creates a pull request with fixes |
125+
| [Comment Trigger](.github/workflows/copilot-comment.yml) | Responds to issue comments starting with `/copilot` and executes the requested task |
126+
| [Dependabot Analysis](.github/workflows/copilot-dependabot-update.yml) | Reviews Dependabot PRs with detailed dependency analysis, breaking changes, and migration guidance |
127+
| [PR Review](.github/workflows/copilot-pr-review.yml) | Performs comprehensive autonomous code reviews on pull requests with severity-based feedback |
128+
| [Research](.github/workflows/copilot-research.yml) | Conducts deep research on GitHub issues using Firecrawl to gather and synthesize information |
129+
| [Security Triage](.github/workflows/copilot-security-triage.yml) | Triages all security alerts (Dependabot, Secret Scanning, Code Scanning) into a single comprehensive report |
130+
| [Issue Triage](.github/workflows/copilot-triage.yml) | Automatically labels issues based on their title and content using existing repository labels |
131+
| [Usage Report](.github/workflows/copilot-usage-report.yml) | Generates comprehensive Copilot usage reports and analytics |
132+
133+
</details>
134+
135+
## Troubleshooting
136+
137+
> [!NOTE]
138+
> Most issues stem from token configuration.
139+
140+
### Common Issues
141+
142+
1. **"Copilot token required" / Permission Denied**
143+
- The default `GITHUB_TOKEN` does NOT have Copilot access
144+
- You must use a PAT with the "Copilot Requests" permission
145+
- Make sure your token is saved as a secret and referenced correctly
146+
147+
2. **Organization Repository Access Issues**
148+
- **Problem:** Fine-grained PATs cannot have both "Copilot Requests" permission AND organization repository access
149+
- **Root Cause:** This is a GitHub platform limitation:
150+
- Personal account tokens: ✅ Copilot Requests permission, ❌ Limited org repo access
151+
- Organization tokens: ❌ No Copilot Requests permission, ✅ Full org repo access
152+
- **Solution:** Use the two-token pattern:
153+
```yaml
154+
- uses: austenstone/copilot-cli@v2
155+
with:
156+
copilot-token: ${{ secrets.COPILOT_TOKEN }} # User PAT with Copilot Requests
157+
repo-token: ${{ secrets.GITHUB_TOKEN }} # Default token for repo operations
158+
```
159+
- The `copilot-token` authenticates with Copilot API
160+
- The `repo-token` handles repository operations (commits, PRs, etc.)
161+
- Ensure your user PAT has appropriate repository access for the repositories you want Copilot to analyze
162+
163+
3. **Copilot starts but permission denied**
164+
- The repo-token default to `GITHUB_TOKEN`.
165+
- Add `permissions: write-all` to your workflow file.
166+
- Check Settings > Actions > General > Workflow permissions.
167+
- Verify the token is correctly configured in your workflow.
168+
169+
4. **Tool Access Denied**
170+
- Check your `allowed-tools` and `denied-tools` configuration
171+
- If `allow-all-tools: false`, you must explicitly allow needed tools
172+
173+
5. **MCP Server Connection Issues**
174+
- Verify MCP server URLs are accessible from GitHub-hosted runners
175+
- Check authentication headers and tokens
176+
- Ensure `type` is set correctly (`local`, `http`, or `sse`)
177+
178+
6. **Session Resume Not Working**
179+
- Session data is stored in logs; ensure `upload-artifact: true`
180+
- Use `resume-session: latest` to continue the most recent session
181+
182+
7. **Large Output Truncation**
183+
- Set `log-level: error` or `log-level: warning` to reduce verbosity
184+
- Break complex prompts into smaller, focused tasks
185+
186+
## Related Resources
187+
188+
- [GitHub Copilot CLI Documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli)
189+
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
190+
- [MCP Server Configuration Docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers)
191+
- [Search for workflow examples](https://github.com/search?q=%22copilot+-p%22+path%3A.github%2Fworkflows%2F*.yml&ref=opensearch&type=code)
192+

‎action.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ branding:
55
color: 'purple'
66
inputs:
77
copilot-token:
8-
description: 'GitHub Personal Access Token (PAT) with "Copilot Requests" permission. The default github.token does NOT have Copilot access - you must provide a PAT with the "Copilot Requests" scope. See: https://github.com/settings/tokens/new?scopes=copilot'
8+
description: 'GitHub Personal Access Token (PAT) with "Copilot Requests" permission. The default github.token does NOT have Copilot access - you must provide a user-owned PAT with the "Copilot Requests" scope. Note: Organization-owned fine-grained PATs cannot have this permission due to GitHub platform limitations. See: https://github.com/settings/tokens/new?scopes=copilot'
99
required: true
1010
repo-token:
11-
description: 'Token for standard GitHub repository operations (e.g., pushing commits, creating PRs). Defaults to copilot-token if not specified. You can use the default GITHUB_TOKEN here if you only need repo access.'
11+
description: 'Token for standard GitHub repository operations (e.g., pushing commits, creating PRs). Defaults to copilot-token if not specified. For organization repositories, you can use the default GITHUB_TOKEN here while using a user PAT for copilot-token.'
1212
required: false
1313
default: ${{ github.token }}
1414
prompt:

0 commit comments

Comments
 (0)