Skip to content

Docs : clarify permissions problem causing TagBot failures. #434

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
IanButterworth merged 9 commits into from
Dec 9, 2025
Merged

Docs : clarify permissions problem causing TagBot failures. #434

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
eecb4df
feat: add rate limit checking on 403 errors (#298)
arnavk23 Dec 8, 2025
a28bfb6
fix: normalize UUID to lowercase for registry lookup (#315)
arnavk23 Dec 8, 2025
f6c2fd7
fixes
IanButterworth Dec 8, 2025
3003854
tests: cover rate limit messaging
IanButterworth Dec 8, 2025
524d705
Fix #267: Clarify that explicit permissions block breaks TagBot
arnavk23 Dec 9, 2025
01bc3c7
Merge branch 'master' into fix/issue-267
arnavk23 Dec 9, 2025
45c30e6
Update README.md
arnavk23 Dec 9, 2025
7369b8a
Update README.md
arnavk23 Dec 9, 2025
ac2e998
Merge branch 'master' into fix/issue-267
IanButterworth Dec 9, 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
10 changes: 8 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@ Check that workflows have the correct permissions on your repo.

![Workflow permissions](workflow_permissions.png)

> [!IMPORTANT]
> **Do not add explicit `permissions:` to your TagBot workflow!**
> Adding explicit permissions (even with `contents: write`) will prevent TagBot from creating releases.
> The default GitHub Actions token permissions are sufficient and necessary for TagBot to work correctly.

> [!NOTE]
> No further action should be required on your part, but if TagBot fails and you see `403: Resource not accessible by integration`
errors, try adding (or refreshing) an SSH key with the correct permissions. See the [SSH Deploy Keys](#ssh-deploy-keys) section below.
Expand Down Expand Up @@ -502,8 +507,9 @@ $ poetry run python -m tagbot.local --help

### I am seeing some kind of permissions error

* Check that your configuration matches the one shown in [Setup](#Setup), especially the `permissions` block
* Try using an [ssh deploy key](#SSH-Deploy-Keys) even if you aren't using Documenter or otherwise need to trigger workflows from TagBot-generated tags
* **First, check if you have a `permissions:` block in your TagBot workflow file.** If you do, **remove it entirely**. Explicit permissions (even with `contents: write`) prevent TagBot from creating releases due to GitHub's permission model. The default GitHub Actions token permissions are what TagBot needs.
* Check that your repository settings allow GitHub Actions to create releases (see [Setup](#setup))
* Try using an [ssh deploy key](#ssh-deploy-keys) even if you aren't using Documenter or otherwise need to trigger workflows from TagBot-generated tags

### I am missing old tags

Expand Down