Forge Connections

A forge connection links GitComet Pro to your account on a code hosting service. With it, GitComet Pro can show pull requests, review threads, and pipeline runs for your repositories, and lets you comment, vote, and merge without leaving the app.

GitComet Pro supports these forges:

Connections stay on your device

GitComet Pro talks to the forge straight from your computer. Your forge credential is stored in your operating system's keychain and never reaches GitComet Pro's servers. Connections are not synced between devices, so you connect again on each computer.

A connection does not open your repositories to GitComet Pro on its own. Each repository has to be approved on this device first. Until it is, GitComet Pro loads nothing about it from the forge, even when your token could read it. Approval applies only to forge features: fetching, pulling, and pushing with Git work as before.

A forge connection is not used for Git itself. To fetch and push over SSH, add an SSH key to your forge account as described in SSH Keys for Git Hosts.

Create a connection

1. Open Settings (Cmd+, on macOS, Ctrl+, on Windows and Linux) and choose Forge connections.
2. Choose Create connection, then choose your forge.
3. Connect in one of two ways:
   • Browser sign-in. Choose Connect followed by the forge's name. GitComet Pro either opens the forge's sign-in page or shows a code to enter there. Browser sign-in is available only for the hosted services that GitComet Pro has a registered app for. When it is not available for your server, the connect button is disabled and the form says Browser sign-in is unavailable for this host in this build. Use a token instead; every forge can connect with one.
   • A token. Choose Use a token, then fill in the form. Create token in browser opens the forge's token page for you. Paste the token and choose Connect with token.
4. When the connection is saved, the repository list appears. Select each repository you want to use to approve it on this device.

Every setup form has a Setup guide button that opens the instructions for that forge on this site.

The token form

Create the token with the fewest permissions you need. A token can never do more than its scopes allow, whatever GitComet Pro offers.

Approve repositories

Open a connection to see its Repository access list. Select a repository to approve it, and select it again to remove the approval. If a repository is missing, choose Refresh repositories, or choose Verify repository URL… and paste its clone URL.

The forge's own permissions and the local approval are separate. A forge permission alone never approves a repository, and an approval gives you nothing that your forge account cannot already do.

Reconnect, disable, or remove a connection

• Reconnect (from the connection's menu) replaces the credential. Do this when a token has expired or been revoked. Reconnecting clears the connection's repository approvals, so approve the repositories again afterwards.
• The Enabled switch turns a connection off without deleting anything. Its credential, approvals, and local reviews are kept until you enable it again.
• Remove connection deletes the credential from your keychain along with the connection's approvals. It does not revoke the token at the forge. Revoke it there too if you no longer need it.

Forge setup

GitHub

Choose Connect GitHub to sign in. GitComet Pro shows a code first, and you decide when to open GitHub and enter it. GitHub App access and local approval are separate: Choose repositories on GitHub changes which repositories the app can reach, and you still approve each one on this device.

Browser sign-in works for github.com only. GitHub Enterprise Server always connects with a token.

To use a token instead, create a fine-grained personal access token limited to the repositories you need. Leave Instance URL blank for github.com. For GitHub Enterprise Server, enter your server's address. GitHub's instructions: Creating a fine-grained personal access token.

GitLab

Choose Connect GitLab to sign in through your browser on gitlab.com. If the browser cannot return to GitComet Pro, Use device sign-in in the token form shows a code to enter instead.

To use a token, create a personal access token with the api scope. GitLab calls this a legacy token, and the form's field is labelled Personal access token (Legacy token in GitLab). Create token in browser opens GitLab's token page with that scope already chosen. GitLab Self-Managed always connects with a token. A project access token works too when you also enter a Repository URL. GitLab's instructions: Personal access tokens and Project access tokens.

Azure DevOps

Azure DevOps needs a personal access token with specific scopes, and its sign-in works only with work or school accounts. See Azure DevOps for the full walkthrough, and Microsoft's Use personal access tokens.

Bitbucket

Bitbucket connects with a token only. For Bitbucket Cloud, choose Create token in browser, then Create API token with scopes, choose Bitbucket as the app, and select the scopes GitComet Pro needs. A token created with plain Create API token has no scopes and does not work with Bitbucket. App passwords are not supported.

For Bitbucket Data Center, enter your server's address and use an HTTP access token. Data Center tokens cannot identify their owner, so also enter a Repository URL.

See Bitbucket for the full walkthrough and the exact scopes, and Atlassian's Create an API token and HTTP access tokens.

Gitea and Forgejo

Choose Gitea / Forgejo, then Gitea.com or Codeberg, and sign in through your browser. For your own Gitea or Forgejo server, choose Use a token, enter the server's address, and create an access token under Settings → Applications on that server. Under Repository and Organization Access, choose All, and set repository and issue to Read and Write and user to Read. Add organization: Read and Write only to publish new repositories into an organization.

See Gitea and Forgejo for the full walkthrough and what each permission is used for, and Forgejo's Access token scope and Codeberg's Generating an access token.

Troubleshooting

"Browser sign-in is unavailable for this host in this build." This build has no registered sign-in app for that server, so the connect button is disabled. This is always the case for self-hosted servers. Choose Use a token.

"Connected, but repositories could not be loaded." The token was accepted but cannot list repositories. Usually a scope is missing. Check the forge's section above, then choose Refresh repositories.

"Reconnect required." The forge rejected the saved credential, usually because the token expired or was revoked. Create a new token and choose Reconnect from the connection's menu.

"This credential belongs to a different connection." The token belongs to an account that is already connected under another connection. Add it as a new connection, or reconnect that other connection.