MichaelMure · Sep 29, 2026 · Sep 25, 2026 · Sep 27, 2026
diff --git a/commands/bridge/bridge_new.go b/commands/bridge/bridge_new.go
@@ -32,7 +32,41 @@ func newBridgeNewCommand(env *execenv.Env) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "new",
 		Short: "Configure a new bridge",
-		Long:  "Configure a new bridge by passing flags or/and using interactive terminal prompts. You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.",
+		Long: `Configure a new bridge by passing flags or/and using interactive terminal prompts.
+You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.
+
+Authentication tokens and required permissions by target:
+
+GitHub:
+  Requires a classic personal access token (https://github.com/settings/tokens;
+  fine-grained tokens starting with 'github_pat_' are not supported).
+  Required scopes:
+    - 'public_repo' for public repositories
+    - 'repo' for private repositories
+  No other scope (code, branches, pull request) is needed or used.
+
+GitLab:
+  Requires a personal access token created on the target GitLab instance
+  ($BASE_URL/-/user_settings/personal_access_tokens).
+  Required scopes:
+    - 'api' (read/write) to import issues and push changes (issues,
+      comments, labels, status). 'read_api' is enough if you only pull.
+    - Read access to the project (at least 'Reporter' role, or public
+      visibility) is required, and at least 'Developer' role to push.
+
+Jira:
+  Authenticates with your user account, so the account itself must have
+  permission to view the project and to create, comment on, edit and
+  transition issues.
+    - Jira Cloud: an API token generated at
+      https://id.atlassian.com/manage-profile/security/api-tokens
+      (sent along with your username).
+    - Jira Data Center / Server: a username and password (session
+      authentication), or an API token.
+
+Launchpad:
+  No token required: the Launchpad bridge is read-only and currently uses
+  the public Launchpad API without any authentication.`,
 		Example: `# Interactive example
 [1]: github
 [2]: gitlab
@@ -69,22 +103,31 @@ Successfully configured bridge: default
 git bug bridge new \
     --name=default \
     --target=github \
-    --owner=example-owner
+    --owner=example-owner \
     --project=example-repo \
     --token=$TOKEN
 
-# For Launchpad
+# For GitLab
 git bug bridge new \
     --name=default \
-    --target=launchpad-preview \
-    --url=https://bugs.launchpad.net/ubuntu/
+    --target=gitlab \
+    --url=https://gitlab.example.com/example-org/example-repo \
+    --token=$TOKEN
 
-# For Gitlab
+# For Jira
 git bug bridge new \
     --name=default \
-    --target=gitlab \
-    --url=https://github.com/example-org/example-repo \
-    --token=$TOKEN`,
+    --target=jira \
+    --base-url=https://jira.example.com \
+    --project=PROJ \
+    [email protected] \
+    --token=$TOKEN
+
+# For Launchpad
+git bug bridge new \
+    --name=default \
+    --target=launchpad-preview \
+    --url=https://bugs.launchpad.net/ubuntu/`,
 		PreRunE: execenv.LoadBackend(env),
 		RunE: execenv.CloseBackend(env, func(cmd *cobra.Command, args []string) error {
 			return runBridgeNew(env, options)

diff --git a/doc/design/bridges/jira.md b/doc/design/bridges/jira.md
@@ -18,20 +18,35 @@ Hopefully the bridge will be able to enable synchronization of these soon.
 
 ### Credentials
 
-JIRA does not support user/personal access tokens. They have experimental
-3-legged oauth support but that requires an API token for the app configured by
-the server administrator. The only reliable authentication mechanism then is the
-username/password and session-token mechanism. We can acquire a session token
-programmatically from the username/password but these are very short lived (i.e.
-hours or less). As such the bridge currently requires an actual username and
-password as user credentials. It supports three options:
+JIRA does not support user/personal access tokens on older servers. Jira
+Cloud and Jira Data Center/Server 8.0.0+ can create user API tokens (Jira
+Cloud at
+<https://id.atlassian.com/manage-profile/security/api-tokens>, Data Center
+from the user profile), which the bridge sends as the password part of the
+`username:api-token` Basic auth header (the "TOKEN" authentication type).
+Older servers (pre October 2019) only support "SESSION" authentication,
+whereby the REST client logs in with an actual username and password, is
+assigned a session, and passes the session cookie with each request. A
+session token can be acquired programmatically from the username/password but
+these are very short lived (i.e. hours or less), so the credentials must be
+stored or re-entered. The bridge supports both mechanism and three ways of
+holding the credentials:
 
 1. Storing both username and password in a separate file referred to by the
    `git-config` (I like to use `.git/jira-credentials.json`)
 2. Storing the username and password in clear-text in the git config
 3. Storing the username only in the git config and asking for the password on
    each `push` or `pull`.
 
+Whichever mechanism is used, the credentials are scoped to a user account (the
+API token is), so the permissions that matter are the ones of the account
+itself, not the token. The account needs to be able to:
+
+- browse the project and its issues (view permission on the project)
+- create, comment on, edit (title/description/labels) and transition issues,
+  for push to work; transitions require additionally that the account is
+  allowed to move issues between the mapped statuses
+
 ### Issue Creation Defaults
 
 When a new issues is created in JIRA there are often certain mandatory fields

diff --git a/doc/man/git-bug-bridge-new.1 b/doc/man/git-bug-bridge-new.1
@@ -10,7 +10,46 @@ git-bug-bridge-new - Configure a new bridge
 
 
 .SH DESCRIPTION
-Configure a new bridge by passing flags or/and using interactive terminal prompts. You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.
+Configure a new bridge by passing flags or/and using interactive terminal prompts.
+You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.
+
+.PP
+Authentication tokens and required permissions by target:
+
+.PP
+GitHub:
+  Requires a classic personal access token (https://github.com/settings/tokens;
+  fine-grained tokens starting with 'github\fIpat\fP\&' are not supported).
+  Required scopes:
+    - 'public_repo' for public repositories
+    - 'repo' for private repositories
+  No other scope (code, branches, pull request) is needed or used.
+
+.PP
+GitLab:
+  Requires a personal access token created on the target GitLab instance
+  ($BASE_URL/-/user_settings/personal_access_tokens).
+  Required scopes:
+    - 'api' (read/write) to import issues and push changes (issues,
+      comments, labels, status). 'read_api' is enough if you only pull.
+    - Read access to the project (at least 'Reporter' role, or public
+      visibility) is required, and at least 'Developer' role to push.
+
+.PP
+Jira:
+  Authenticates with your user account, so the account itself must have
+  permission to view the project and to create, comment on, edit and
+  transition issues.
+    - Jira Cloud: an API token generated at
+      https://id.atlassian.com/manage-profile/security/api-tokens
+      (sent along with your username).
+    - Jira Data Center / Server: a username and password (session
+      authentication), or an API token.
+
+.PP
+Launchpad:
+  No token required: the Launchpad bridge is read-only and currently uses
+  the public Launchpad API without any authentication.
 
 
 .SH OPTIONS
@@ -100,22 +139,31 @@ Successfully configured bridge: default
 git bug bridge new \\
     --name=default \\
     --target=github \\
-    --owner=example-owner
+    --owner=example-owner \\
     --project=example-repo \\
     --token=$TOKEN
 
-# For Launchpad
+# For GitLab
 git bug bridge new \\
     --name=default \\
-    --target=launchpad-preview \\
-    --url=https://bugs.launchpad.net/ubuntu/
+    --target=gitlab \\
+    --url=https://gitlab.example.com/example-org/example-repo \\
+    --token=$TOKEN
 
-# For Gitlab
+# For Jira
 git bug bridge new \\
     --name=default \\
-    --target=gitlab \\
-    --url=https://github.com/example-org/example-repo \\
+    --target=jira \\
+    --base-url=https://jira.example.com \\
+    --project=PROJ \\
+    [email protected] \\
     --token=$TOKEN
+
+# For Launchpad
+git bug bridge new \\
+    --name=default \\
+    --target=launchpad-preview \\
+    --url=https://bugs.launchpad.net/ubuntu/
 .EE
 
 

diff --git a/doc/md/git-bug_bridge_new.md b/doc/md/git-bug_bridge_new.md
@@ -4,7 +4,41 @@ Configure a new bridge
 
 ### Synopsis
 
-Configure a new bridge by passing flags or/and using interactive terminal prompts. You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.
+Configure a new bridge by passing flags or/and using interactive terminal prompts.
+You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge.
+
+Authentication tokens and required permissions by target:
+
+GitHub:
+  Requires a classic personal access token (https://github.com/settings/tokens;
+  fine-grained tokens starting with 'github_pat_' are not supported).
+  Required scopes:
+    - 'public_repo' for public repositories
+    - 'repo' for private repositories
+  No other scope (code, branches, pull request) is needed or used.
+
+GitLab:
+  Requires a personal access token created on the target GitLab instance
+  ($BASE_URL/-/user_settings/personal_access_tokens).
+  Required scopes:
+    - 'api' (read/write) to import issues and push changes (issues,
+      comments, labels, status). 'read_api' is enough if you only pull.
+    - Read access to the project (at least 'Reporter' role, or public
+      visibility) is required, and at least 'Developer' role to push.
+
+Jira:
+  Authenticates with your user account, so the account itself must have
+  permission to view the project and to create, comment on, edit and
+  transition issues.
+    - Jira Cloud: an API token generated at
+      https://id.atlassian.com/manage-profile/security/api-tokens
+      (sent along with your username).
+    - Jira Data Center / Server: a username and password (session
+      authentication), or an API token.
+
+Launchpad:
+  No token required: the Launchpad bridge is read-only and currently uses
+  the public Launchpad API without any authentication.
 
 ```
 git-bug bridge new [flags]
@@ -49,22 +83,31 @@ Successfully configured bridge: default
 git bug bridge new \
     --name=default \
     --target=github \
-    --owner=example-owner
+    --owner=example-owner \
     --project=example-repo \
     --token=$TOKEN
 
-# For Launchpad
+# For GitLab
 git bug bridge new \
     --name=default \
-    --target=launchpad-preview \
-    --url=https://bugs.launchpad.net/ubuntu/
+    --target=gitlab \
+    --url=https://gitlab.example.com/example-org/example-repo \
+    --token=$TOKEN
 
-# For Gitlab
+# For Jira
 git bug bridge new \
     --name=default \
-    --target=gitlab \
-    --url=https://github.com/example-org/example-repo \
+    --target=jira \
+    --base-url=https://jira.example.com \
+    --project=PROJ \
+    [email protected] \
     --token=$TOKEN
+
+# For Launchpad
+git bug bridge new \
+    --name=default \
+    --target=launchpad-preview \
+    --url=https://bugs.launchpad.net/ubuntu/
 ```
 
 ### Options

diff --git a/doc/usage/third-party.md b/doc/usage/third-party.md
@@ -8,6 +8,11 @@ from third-party platforms.
 - [Overview](#overview)
 - [Supported bridges](#supported-bridges)
 - [Getting started](#getting-started)
+- [Tokens and required permissions](#tokens-and-required-permissions)
+  - [GitHub](#github)
+  - [GitLab](#gitlab)
+  - [Jira](#jira)
+  - [Launchpad](#launchpad)
 - [Interacting with the bridge](#interacting-with-the-bridge)
 
 <!-- mdformat-toc end -->
@@ -64,11 +69,85 @@ _For a full list of the features enabled for each bridge, see the
    appropriate URL for the remote project: something like
    `https://github.com/git-bug/git-bug`
 5. Create an access token. You can either use the interactive token creation,
-   enter it on your own token, or use an existing token if you already have one
+   enter it on your own token, or use an existing token if you already have one.
+   The [permissions required for each service](#tokens-and-required-permissions)
+   differ, check the details for your platform below.
 
 That's it! Once you've completed the wizard, you'll have successfully configured
 a bridge.
 
+## Tokens and required permissions<a name="tokens-and-required-permissions"></a>
+
+Bridges authenticate against their platform with a token (except Launchpad,
+which currently does not need one). Every bridge performs at least the following
+API operations, which determine the minimum permissions a token needs:
+
+- **pull**: read the issue list, issue bodies, comments, labels and
+  status/title change events
+- **push** (GitHub, GitLab and Jira only): create issues, edit title and body,
+  add and edit comments, change labels and toggle the status (open/close)
+
+### GitHub<a name="github"></a>
+
+Tokens are created at <https://github.com/settings/tokens>, or via the
+interactive OAuth device flow offered by the `git bug bridge new` wizard.
+
+The bridge accepts classic personal access tokens (legacy 40-character tokens
+and ones starting with `ghp_`, `gho_`, `ghu_`, `ghs_` or `ghr_`). Fine-grained
+tokens (starting with `github_pat_`) are currently rejected when pasted
+manually.
+
+Required scopes (classic tokens): `public_repo` is enough for public
+repositories; the full `repo` scope is required for private repositories.
+These scopes grant read and write access to issues, comments and labels, which
+is what the bridge needs in both directions. No other scope (code, branches,
+pull requests) is used or required.
+
+The interactive device flow creates a token with a single scope, chosen
+according to the repository visibility: `public_repo` for public repositories
+and `repo` for private ones.
+
+### GitLab<a name="gitlab"></a>
+
+Personal access tokens are created on the GitLab instance you want to bridge,
+at `$BASE_URL/-/user_settings/personal_access_tokens` (specify the instance
+with `--base-url`; defaults to `gitlab.com`).
+
+- **Scopes**: the `api` scope (read and write) is required so the bridge can
+  import issues and push changes back. If you only plan to pull issues, the
+  `read_api` scope is enough.
+- **Project role**: the token owner needs read access to the project to pull
+  (any member role, or public project visibility), and at least the *Developer*
+  role to push, since pushing creates issues, comments and label/status
+  changes on your behalf.
+
+### Jira<a name="jira"></a>
+
+The Jira bridge does not use a scoped token; it authenticates as your user so
+the required permissions are the ones of a normal Jira participant:
+
+- **Jira Cloud**: an [API token][jira-cloud-api-token] generated from your
+  Atlassian profile, sent together with your account email as username. The
+  token inherits your account permissions.
+- **Jira Data Center / Server**: an API token generated from your user profile
+  (Data Center 8.0.0 and later, sent the same way as the Cloud token), or
+  username and password ("session" authentication), which is the only option
+  on older servers.
+
+In all cases the account needs permission to view the project, and to create
+and edit issues in it (view, comment and transition), typically through the
+*Jira Software* project role or by being a participant in the project. Note
+that closing/reopening issues is done by executing workflow *transitions*, so
+the account must also be allowed to perform those transitions.
+
+[jira-cloud-api-token]: https://id.atlassian.com/manage-profile/security/api-tokens
+
+### Launchpad<a name="launchpad"></a>
+
+No token or credentials are required. The Launchpad bridge is still
+experimental (`launchpad-preview`) and read-only: it only queries the public
+Launchpad API to import bugs and messages.
+
 ## Interacting with the bridge<a name="interacting-with-the-bridge"></a>
 
 To push issues out to the bridge, run: