Skip to content

Document required token permissions for each bridge target - #1632

Merged
MichaelMure merged 2 commits into
git-bug:trunkfrom
openSUSE-Python:tokens
Sep 29, 2026
Merged

MichaelMure merged 2 commits into
git-bug:trunkfrom
openSUSE-Python:tokens

Conversation

@mcepl

@mcepl mcepl commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Part of stack: #1629 → #1632 → #1628

Builds on #1629 (pnpm-overrides).

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.

Comment thread commands/bridge/bridge_new.go Outdated
Comment thread doc/usage/third-party.md

@MichaelMure MichaelMure left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM overall, but I don't think it should be part of the command's example.

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
MichaelMure added this pull request to the merge queue Sep 29, 2026
@MichaelMure

Copy link
Copy Markdown
Contributor

Thanks!

Merged via the queue into git-bug:trunk with commit d3e9d76 Sep 29, 2026
8 checks passed
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.
@mcepl
mcepl deleted the tokens branch October 3, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants