docs: add token permissions documentation for autodiscovery #11

Merged

alex merged 1 commit from pi/issue10-token-perms-docs into master

2026-07-08 11:09:56 +00:00

forgejo-actions commented

2026-07-07 12:53:43 +00:00

Summary

Updates the README with comprehensive token permissions documentation, addressing the root cause of #10 (token discovers only one repo).

Changes

Token setup section — fully rewritten

Required scopes table: repo (RW), issue (RW), organization (R), user (R) — the previous README only listed repo + user, which is insufficient on modern Forgejo (≥ 1.20) since pull requests are modeled as issues and require the issue scope.
Classic PAT vs fine-grained PAT: explains why autodiscovery fails with a single-repo-scoped token. A classic PAT grants account-wide access (what autodiscover needs), while a fine-grained PAT scoped to one repo will only discover that one repo — the most common cause of the bug.
Troubleshooting subsection ("only one repository discovered"): step-by-step checklist to diagnose the issue.

Other fixes

Secret name: corrected from RENOVATE_TOKEN → PI_TOKEN to match the actual workflow (secrets.PI_TOKEN), with a note explaining the internal mapping.
Schedule description: corrected from "every Sunday" to "every day at 2 AM" (matches the cron in renovate.yml).
Troubleshooting sections: updated to reference the token permissions section and highlight that Renovate silently skips repos where the token lacks write permission.
Resources: added links to official Forgejo access token and OAuth2 scope docs alongside the existing Renovate docs.

Links to official docs

Renovate — Forgejo Platform (authoritative scope list)
Forgejo — Access Tokens
Forgejo — OAuth2 / Token Scopes

Closes #10

## Summary Updates the README with comprehensive token permissions documentation, addressing the root cause of #10 (token discovers only one repo). ## Changes ### Token setup section — fully rewritten - **Required scopes table**: `repo` (RW), `issue` (RW), `organization` (R), `user` (R) — the previous README only listed `repo` + `user`, which is insufficient on modern Forgejo (≥ 1.20) since pull requests are modeled as issues and require the `issue` scope. - **Classic PAT vs fine-grained PAT**: explains why autodiscovery fails with a single-repo-scoped token. A classic PAT grants account-wide access (what autodiscover needs), while a fine-grained PAT scoped to one repo will only discover that one repo — the most common cause of the bug. - **Troubleshooting subsection** ("only one repository discovered"): step-by-step checklist to diagnose the issue. ### Other fixes - **Secret name**: corrected from `RENOVATE_TOKEN` → `PI_TOKEN` to match the actual workflow (`secrets.PI_TOKEN`), with a note explaining the internal mapping. - **Schedule description**: corrected from "every Sunday" to "every day at 2 AM" (matches the cron in `renovate.yml`). - **Troubleshooting sections**: updated to reference the token permissions section and highlight that Renovate silently skips repos where the token lacks **write** permission. - **Resources**: added links to official Forgejo access token and OAuth2 scope docs alongside the existing Renovate docs. ## Links to official docs - [Renovate — Forgejo Platform](https://docs.renovatebot.com/modules/platform/forgejo/) (authoritative scope list) - [Forgejo — Access Tokens](https://forgejo.org/docs/latest/user/access-tokens/) - [Forgejo — OAuth2 / Token Scopes](https://forgejo.org/docs/latest/user/oauth2-provider/) Closes #10

forgejo-actions added 1 commit

2026-07-07 12:53:43 +00:00

docs: add token permissions documentation for autodiscovery 8f0927adbf

Update README with comprehensive token permissions docs addressing the
root cause of #10 (token discovers only one repo).

- Add required scopes table: repo (RW), issue (RW), organization (R), user (R)
  (previous README only listed repo + user, insufficient on Forgejo >= 1.20)
- Add Classic PAT vs fine-grained PAT section explaining why single-repo
  scoped tokens cause autodiscovery to find only one repo
- Add troubleshooting subsection for 'only one repository discovered'
- Fix secret name from RENOVATE_TOKEN to PI_TOKEN (matches actual workflow)
- Fix schedule description (daily 2AM, not weekly Sunday)
- Update troubleshooting sections with token permission references
- Add links to official Forgejo access token and OAuth2 scope docs

Closes #10

pi referenced this pull request

2026-07-07 12:53:56 +00:00

Token discovers only one repo #10