Repository navigation
Document required token permissions for each bridge target - #1632
Merged
Merged
Conversation
MichaelMure
reviewed
Sep 25, 2026
MichaelMure
reviewed
Sep 25, 2026
MichaelMure
requested changes
Sep 25, 2026
MichaelMure
left a comment
Contributor
There was a problem hiding this comment.
LGTM overall, but I don't think it should be part of the command's example.
This was referenced Sep 25, 2026
mcepl
force-pushed
the
tokens
branch
3 times, most recently
from
September 25, 2026 20:29
4c6cb16 to
607b1b3
Compare
Bridges authenticate against their platform with a token, but neither the usage documentation nor the "git bug bridge new" help text told users which scopes/permissions each token must grant, nor that some targets need no token at all. Add a "Tokens and required permissions" section to doc/usage/third-party.md covering each supported bridge: - GitHub: classic PATs only (fine-grained 'github_pat_' tokens are rejected by the input validator), 'public_repo' scope for public repositories and 'repo' for private ones; no permission for code, branches or pull requests is used. - GitLab: personal access token with the 'api' scope (or 'read_api' for pull-only usage) must be created on the target instance, and the token owner needs read access to the project (at least 'Developer' role to push). - Jira: the token (Cloud or Data Center/Server 8.+) authenticates as the user, so the account itself needs permission to view the project and to create, comment on, edit and transition issues; older servers fall back to username/password session authentication. - Launchpad: no token required, the 'launchpad-preview' bridge only queries the public Launchpad API. The required permissions were derived from the API operations each bridge actually performs (issue listing, comment/label/status events on import; issue creation, comments, labels and status changes on export). Also update the examples in "git bug bridge new" with per-target permission notes and fix two pre-existing issues found along the way: a missing line continuation in the GitHub example (which made the command invalid) and the GitLab example pointing at a github.com URL. The man page and markdown CLI documentation were regenerated from the updated command definition. Finally, correct the credentials section of doc/design/bridges/jira.md, which claimed Jira does not support user API tokens and that the bridge requires username/password; the bridge has supported API-token (Basic auth) credentials for a while and both mechanisms are documented with the permissions the underlying account needs.
Per review feedback on PR git-bug#1632, relocate the token permission and scope documentation from the Example section to the Long command description in "git bug bridge new". Keep the Example section focused on clean CLI command invocations for each target, and include an explicit invocation example for Jira. Regenerate man and markdown documentation to reflect the updated command definition.
MichaelMure
approved these changes
Sep 29, 2026
Contributor
|
Thanks! |
mcepl
added a commit
to openSUSE-Python/git-bug
that referenced
this pull request
Oct 1, 2026
Per review feedback on PR git-bug#1632, relocate the token permission and scope documentation from the Example section to the Long command description in "git bug bridge new". Keep the Example section focused on clean CLI command invocations for each target, and include an explicit invocation example for Jira. Regenerate man and markdown documentation to reflect the updated command definition.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Feel free to suggest shortening or (less likely) expanding on these notes.
Bridges authenticate against their platform with a token, but neither the usage documentation nor the "git bug bridge new" help text told users which scopes/permissions each token must grant, nor that some targets need no token at all.