| <!-- | |
| Licensed to the Apache Software Foundation (ASF) under one | |
| or more contributor license agreements. See the NOTICE file | |
| distributed with this work for additional information | |
| regarding copyright ownership. The ASF licenses this file | |
| to you under the Apache License, Version 2.0 (the | |
| "License"); you may not use this file except in compliance | |
| with the License. You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, | |
| software distributed under the License is distributed on an | |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| KIND, either express or implied. See the License for the | |
| specific language governing permissions and limitations | |
| under the License. | |
| --> | |
| # Contributing a Copilot token for the agentic workflows | |
| This repo runs scheduled [GitHub Agentic Workflows](https://github.github.com/gh-aw/) (the | |
| `*.lock.yml` files compiled from `*.md` in `.github/workflows/`) that drive the GitHub Copilot | |
| CLI. Each run needs a GitHub token from an account with an active Copilot license. So that no | |
| single person's Copilot quota gets burned through, runs rotate day by day across a pool of | |
| volunteer tokens. | |
| If you have a Copilot license and want to help share the load, add your token to the pool. | |
| ## What kind of token | |
| - A fine-grained personal access token. Classic PATs don't work with the Copilot CLI. | |
| - Resource owner: your own personal account. | |
| - Permission: Account permissions > "Copilot Requests" > Read. That's the only permission it | |
| needs, no repo access. | |
| - Your account must have an active Copilot seat. | |
| Create it at <https://github.com/settings/personal-access-tokens/new>. Give it a sensible | |
| expiration; when it lapses the health check (below) will flag it and you can re-add it. | |
| ## How to add it | |
| 1. Pick a short alias for yourself, e.g. `t1`, `t2`, `vol3`. The alias shows up in workflow logs, | |
| so keep it non-identifying if you prefer. | |
| 2. Add your token as a repository secret named `COPILOT_GITHUB_TOKEN_<alias>` | |
| (e.g. `COPILOT_GITHUB_TOKEN_t1`). Repo admins do this via | |
| *Settings > Secrets and variables > Actions > New repository secret*, or: | |
| ``` | |
| gh secret set COPILOT_GITHUB_TOKEN_t1 --body "github_pat_xxx" | |
| ``` | |
| 3. Ask a repo admin to register the alias by appending it to the repository variable | |
| `GH_AW_COPILOT_TOKEN_NAMES`, which is a JSON array: | |
| ``` | |
| gh variable set GH_AW_COPILOT_TOKEN_NAMES --body '["t1","t2","t3"]' | |
| ``` | |
| The workflows can't enumerate secrets, so this variable is the source of truth for the pool. | |
| A token isn't used until its alias is listed there. | |
| ## How rotation works (for maintainers) | |
| Each agent workflow (`weekly-repo-status`, `daily-issue-triage`) defines a `pick_copilot_token` | |
| job in its `.md` source. The job has to run outside the agent job because strict mode forbids | |
| reading secrets there. It picks today's alias by day-of-year mod N, checks the token is live | |
| (`GET /user` returns 200, otherwise it moves on to the next candidate) and outputs the chosen | |
| alias. The token value itself never crosses jobs. The two workflows use different | |
| `ROTATION_SLOT`s, which start them half the pool apart so they don't land on the same | |
| volunteer on the same day (with at least two tokens in the pool). | |
| The agent job resolves the secret itself via | |
| `secrets[format('COPILOT_GITHUB_TOKEN_{0}', needs.pick_copilot_token.outputs.name)]` and falls | |
| back to the base `COPILOT_GITHUB_TOKEN` when the pick job outputs an empty name. Keep the base | |
| secret set to one reliable token. | |
| `gh aw compile` doesn't know about this wiring, so after editing the `.md` sources run: | |
| ``` | |
| gh aw compile && bash .github/scripts/post-compile.sh | |
| ``` | |
| See the header of `.github/scripts/post-compile.sh` for what it patches. | |
| To check the pool, trigger the "Copilot token health" workflow | |
| (`.github/workflows/copilot-token-health.yml`) from the Actions tab. It prints an HTTP status | |
| code per alias and nothing else, so no account identities end up in logs. Note it can't tell | |
| when a token is live but has used up its monthly Copilot requests. | |
| ## Removing a token | |
| Delete the `COPILOT_GITHUB_TOKEN_<alias>` secret and remove `<alias>` from | |
| `GH_AW_COPILOT_TOKEN_NAMES`. |