Connecting a git provider
Plexus opens and tracks pull requests directly on GitHub and Bitbucket. Connecting a provider is a one-click sign-in — no CLI to install, no personal access tokens to paste.
Connect a provider
Open Settings → Git providers and click Connect GitHub or Connect Bitbucket. Your browser opens the provider's normal authorization screen; approve it and you're returned to Plexus, connected. The status line shows the account you're signed in as.
Once a provider is connected you can also search your repositories and clone one straight into a new project — the same on-device token authenticates private clones. See Add a repository.
Fetching, pulling and pushing
A connection is also a fallback credential for git itself. Fetch, Pull, Push and background fetching all run the real git on your machine, so they use your own setup first — a credential helper, an SSH key, whatever git fetch would use in a terminal. Nothing about that changes when you connect a provider.
What changes is what happens when that setup has nothing to offer. Plexus never shows a password prompt (a desktop app has no terminal for git to ask on, and a hidden prompt would just hang), so on a machine with no stored credentials an https remote used to fail outright. Now, if the repository's remote points at a provider you've connected, Plexus retries the operation once using that connection — and it usually just works.
Some details worth knowing:
- Your own credentials always win — for Fetch, Pull and Push. The connection is only tried after git's own attempt has failed, so a credential helper with wider access than your Plexus connection keeps being the one that authenticates. (Cloning from the repository search is the exception, and uses your connection directly: there is no repository yet for a helper to hold credentials for.)
- The token is bound to that host. A GitHub connection is only ever offered to
github.com, and a Bitbucket one only tobitbucket.org. It is passed to git for that one command — never written into.git/config, and never into a remote URL. - Only the host that actually refused is retried. If a repository has several remotes and the one that failed isn't on a provider you've connected — a company git server, say — Plexus doesn't try again; there is nothing it could authenticate with.
- A connection that gets refused is rested for a few minutes. If the provider itself turns the connection down — the account can't reach that repository, the grant was revoked, your organization hasn't authorized it — Plexus stops offering it for a short while rather than doubling every fetch with an attempt it knows will fail. Reconnecting the provider clears that straight away, so you never have to wait after following the error's own advice.
sshremotes are untouched. They authenticate with your keys and agent; no token applies, so nothing is retried.
If it still can't authenticate, the message says which host refused and what to do about it — connect the provider, fix your credential helper, or switch the remote to ssh. See Session Git and the Project Git client.
Where your token lives — what leaves your device
Plexus uses a small managed sign-in service we run in the EU. When you connect, the provider hands back a short-lived authorization code; Plexus sends only that code to the service, which holds the OAuth app secret and exchanges it for your access token.
The token is returned to your device and stored in your operating system's keychain — we don't keep it. From then on, Plexus talks to GitHub or Bitbucket directly from your machine; your repository names, code, and pull-request contents never pass through our servers. Because the token lives locally, PR features keep working offline after you've signed in.
This is the managed connection service only — a broker, not a proxy. It is separate from the anonymous usage analytics Plexus collects, and neither one sends us Your Content.
Reconnect
Providers grant a token the permissions the app had at the moment you signed in. If that set later changes — Plexus starts needing a permission it didn't before — your existing token keeps the narrower access, and refreshing it in the background won't widen it. Click Reconnect GitHub (or Reconnect Bitbucket) in Settings → Git providers to sign in again and pick up the new access.
Reconnecting never leaves you signed out: Plexus only replaces the stored token once the new sign-in succeeds, so cancelling the browser tab changes nothing.
You don't have to go looking for it: when Plexus can't reach your repositories, the repository picker offers the same Reconnect inline and re-runs your search as soon as you're done.
Plexus also checks on its own, rather than waiting for something to fail. Shortly after startup — and every six hours or so while you work — it asks GitHub or Bitbucket what your stored token is actually allowed to do. That's one small request made from your machine with the token that's already there; nothing extra is sent to us.
If the access no longer covers what Plexus needs, a notice names the missing permission — spelled the way the provider labels it, such as Workspace membership: Read or Account: Read — and offers Reconnect GitHub (or Reconnect Bitbucket) right there, so you sign in without leaving what you were doing. Plexus re-checks the access before telling you it worked. Not now puts that notice away and it stays away; Settings → Git providers keeps warning you, with the status line reading Connected as your account — limited access, until the access is confirmed restored. Signing in again is not what clears it — the confirmation is. So if a reconnect happens to land on the same narrow access, the warning correctly stays up. If the permissions change again later you'll get a fresh notice — dismissing one never silences the next.
That background check can only confirm part of what a connection needs. On Bitbucket it confirms that your workspaces are still visible, and there is no way to ask Bitbucket what else a connection covers, so everything beyond that is discovered when something is genuinely refused. A notice raised by a refusal is therefore only cleared by something that covers the same permission — a check that passed for something else is not an all-clear, and Plexus no longer treats it as one.
If you have been caught in a loop — a notice asking you to reconnect, a Bitbucket access restored message moments later, then the identical notice at the next repository search or pull-request refresh, and Not now never making it stop — that is the loop this closes.
Reconnecting is the first thing to try. It is the whole fix whenever your token simply predates a permission Plexus now needs, which is the common case. The other case is a permission that has to be enabled on the Plexus app registration at the provider — signing in again can't widen that one, however many times you do it. Plexus can only tell the two apart by trying, so it re-checks your access the moment you're back from the browser; if it still comes up short, it says plainly that signing in again did not widen the grant, stops offering the button, and asks you to report the permission it named. Reporting it is what fixes it. That outcome is remembered between restarts, so you don't meet the same round trip every time you open the app — and if the permission is later enabled and something else is missing, that's a different problem and you'll get a fresh notice.
Settings → About lists every connected account under Connected accounts, with the access the provider recorded for that connection. When Plexus asks you to report a permission it named, that list is the thing to copy into the report. A provider that recorded nothing says so rather than showing a blank.
Sometimes the provider stops accepting the sign-in altogether rather than narrowing it — a token that was revoked, or an account that changed. There is no missing permission to name in that case, so Plexus says so instead: the notice reads Bitbucket no longer accepts this connection (or GitHub), and the status line reads Connected as your account — sign-in no longer accepted. Reconnecting is the whole fix here, and it says that plainly.
You can change how this works in Settings → Git & PRs. Check that provider connections still work (default On) turns the whole thing off — no request is made and no notice appears — and How often to check provider connections (hours) (default 6) sets the wait between checks of the same connection. Raise it on a metered connection or an account that's close to its provider's rate limits. Whatever the interval, Plexus still checks shortly after starting and straight away when a provider refuses one of its requests.
When Plexus can't list your repositories
If the repository picker reports that it couldn't access your repositories, Details on that message carries the provider's own explanation, which is usually enough to tell you what to do next. It opens on its own whenever signing in again isn't the whole answer, and sits collapsed when it is. On Bitbucket, where Plexus lists each of your workspaces separately, the explanation names the workspace that refused.
The message offers two ways forward, and leads with whichever suits the failure: Try again re-runs the search on the spot (the right first move for a dropped connection or a provider hiccup), while Reconnect signs you in again (what fixes an expired token or a missing permission). Try again stays available even while a sign-in tab is still open, so a search that failed for an unrelated reason is always one click from a retry.
Bitbucket: "your credentials lack one or more required privilege scopes." Listing your repositories needs Bitbucket's Workspace membership: Read permission. Bitbucket grants permissions to the app itself rather than per sign-in, so a token issued before Plexus needed this one won't carry it — Reconnect to get a fresh token. If reconnecting doesn't clear it, the permission is missing on the Plexus side and no amount of re-signing-in will help. Plexus checks your access again as soon as you're back from the browser, and only if that check still comes up short does it tell you the sign-in didn't widen anything and stop asking — instead of sending you round the same loop. That outcome is remembered between restarts, so a fresh start doesn't put you back at the beginning of the loop. It reports what the check found, never a guess at why, so please report it. Either way the URL tab still works: cloning only needs repository access, which you already have.
Disconnect
Click Disconnect GitHub or Disconnect Bitbucket in Settings → Git providers to remove the stored token from your keychain. You can reconnect any time.
Next: open and track pull requests. For how connections relate to what data leaves your device, see our Privacy Policy.