1# Using third-party platforms via bridges<a name="using-bridges"></a>
  2
  3This page provides an overview of how to use _bridges_ to sync issues to and
  4from third-party platforms.
  5
  6<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
  7
  8- [Overview](#overview)
  9- [Supported bridges](#supported-bridges)
 10- [Getting started](#getting-started)
 11- [Interacting with the bridge](#interacting-with-the-bridge)
 12
 13<!-- mdformat-toc end -->
 14
 15## Overview<a name="overview"></a>
 16
 17Bridges within `git-bug` are bi-directional, incremental, and speedy gateways to
 18third-party platforms. Configuring a bridge allows you to push and pull issues
 19to and from a third party platform.
 20
 21This expands the utility and function of `git-bug`: because issues are just
 22objects in your git repository, you can import issues from a bridge to work on
 23them in bulk, offline, in your preferred environment, at your own pace. When
 24you're ready to push your issues back to the external platform again, you'll be
 25able to synchronize the changes you made with one simple command.
 26
 27<p align="center">
 28    <img src="../assets/bridge-workflow.png" alt="Bridge workflow">
 29</p>
 30
 31This has several benefits:
 32
 33- works offline, including edition
 34- browsing is pretty much instant
 35- you get to choose the UI you prefer between CLI, interactive TUI or in your
 36  browser with the WEBUI
 37- you have a near-complete archive of issues locally, embedded in your git
 38  repository, in case the external platform becomes inaccessible
 39- you are free to move to another platform -- your issues follow wherever your
 40  repo goes!
 41
 42## Supported bridges<a name="supported-bridges"></a>
 43
 44We support a number of bridges:
 45
 46- Jira
 47- GitHub
 48- GitLab
 49- Launchpad
 50
 51_For a full list of the features enabled for each bridge, see the
 52[feature matrix][docs/feature-matrix]._
 53
 54## Getting started<a name="getting-started"></a>
 55
 561. From within a git repository, run `git bug bridge new` to start the
 57   configuration wizard
 582. Choose the type of bridge you want to configure, e.g. `github`
 593. Type a name for the bridge configuration. As you can configure multiple
 60   bridges, this name will allow you to choose when there is an ambiguity.
 614. If you already have a repository created on the external platform, and your
 62   local git repository has that as a remote, the configuration wizard will
 63   automatically detect the URL. Otherwise, please ensure you enter the
 64   appropriate URL for the remote project: something like
 65   `https://github.com/git-bug/git-bug`
 665. Create an access token. You can either use the interactive token creation,
 67   enter it on your own token, or use an existing token if you already have one
 68
 69That's it! Once you've completed the wizard, you'll have successfully configured
 70a bridge.
 71
 72## Interacting with the bridge<a name="interacting-with-the-bridge"></a>
 73
 74To push issues out to the bridge, run:
 75
 76```bash
 77git bug bridge push [NAME]
 78```
 79
 80To pull and integrate updates for issues from the bridge:
 81
 82```bash
 83git bug bridge pull [NAME]
 84```
 85
 86> [!TIP]
 87> See the [CLI documentation][doc/cli/bridge] for more information on the
 88> command line arguments and options.
 89
 90The command line is primarily meant for programmatic usage or to interface with
 91`git-bug` with scripts or other tools. For day to day usage, we recommend taking
 92a look at [the supported interfaces][docs/usage/interfaces], which include a
 93robust TUI and an in-progress Web UI.
 94
 95______________________________________________________________________
 96
 97##### See more
 98
 99- [A bird's-eye view of the internal architecture][docs/design/arch]
100- [A description of the data model][docs/design/model]
101- [An overview of the native interfaces][docs/usage/interfaces]
102- [Filtering query results][docs/usage/filter]
103- [Understanding the workflow models][docs/usage/workflows]
104- :house: [Documentation home][docs/home]
105
106[doc/cli/bridge]: ../md/git-bug_bridge.md
107[docs/design/arch]: ../design/architecture.md
108[docs/design/model]: ../design/data-model.md
109[docs/feature-matrix]: ../feature-matrix.md
110[docs/home]: ../README.md
111[docs/usage/filter]: ./query-language.md
112[docs/usage/interfaces]: ./interfaces.md
113[docs/usage/workflows]: ./workflows.md