GitComet Pro Forge connections Gitea and Forgejo
Gitea and Forgejo
Connect GitComet Pro to Gitea, Forgejo, Codeberg, or your own server with browser sign-in or an access token. Lists the exact token permissions each feature needs and where to create the token.
GitComet Pro works with Gitea and Forgejo, including the hosted services gitea.com and Codeberg, and your own servers. Once connected, you can review pull requests and their conversations, approve or request changes, merge, work with labels and attachments, and follow, run, and rerun Gitea and Forgejo Actions.
| Your server | Use |
|---|---|
| gitea.com or codeberg.org | Browser sign-in, or an access token |
| Your own Gitea or Forgejo server | An access token |
Sign in with your browser
- Open Settings (
Cmd+,on macOS,Ctrl+,on Windows and Linux) and choose Forge connections. - Choose Create connection, then Gitea / Forgejo.
- Select Gitea.com or Codeberg, then choose the connect button. Your browser opens the sign-in page. Sign in and authorize GitComet Pro.
- Return to GitComet Pro. The connection is saved and lists your repositories.
On gitea.com, GitComet Pro asks for read:user, read:organization, write:repository, and write:issue. That is the token's permissions below plus read access to your organizations. Codeberg authorizes the whole account at once.
If the connect button is disabled and the form says Browser sign-in is unavailable for this host in this build, this build has no registered app for that service. Use an access token instead.
Create an access token
- On your server, open Settings → Applications (
https://<server>/user/settings/applications). In GitComet Pro, Create token in browser opens this page once you have entered the server's address. - Under Generate New Token, enter a name, such as
GitComet Pro. - Under Repository and Organization Access, choose All (public, private, and limited). With Public only, the token cannot see your private repositories or those of your organizations.
- Set the permissions from the next section. Leave every other row at No Access.
- Choose Generate Token, then copy the token right away. The server shows it only once.
If the page says You must select at least one permission to create a token, no row is set above No Access yet.
Token permissions
| Permission | Access | What GitComet Pro uses it for |
|---|---|---|
| repository | Read and Write | List your repositories, and read pull requests, changed files, diffs, commits, branches, tags, files, and commit statuses. With write access, it can also create, edit, update, and merge pull requests, submit and dismiss reviews, reply to review comments, request reviewers, and run, rerun, and cancel Actions workflows. |
| issue | Read and Write | Read a pull request's conversation, timeline, labels, and attachments, and the repository's issues. With write access, it can also comment, edit and delete comments, change labels, subscribe to notifications, and attach files. Gitea treats a pull request's conversation as an issue, so this is needed alongside repository. |
| user | Read | Identify the account the token belongs to when you connect, and mark your own comments and reviews. |
Add one more permission only if you need it:
- organization: Read and Write: publish a local repository as a new repository owned by an organization. Publishing to your own account does not need it.
Choose a narrower set if you need less:
- Browse only: repository: Read, issue: Read, and user: Read. You can see pull requests, conversations, and Actions runs, but every action that changes something fails with a permission error from the server.
GitComet Pro does not use activitypub, misc, notification, or package. Leave them at No Access.
A token never gives you more than your own permissions on the server. If you cannot merge a pull request in the browser, a token with repository: Read and Write will not let you do it either.
For what each permission covers, see Forgejo's Access token scope and Codeberg's Generating an access token.
Connect with the token
- In Forge connections, choose Create connection, then Gitea / Forgejo, then Use a token.
- Fill in the form:
- Instance URL (HTTPS): your server's address, such as
https://git.example.com. For the hosted services, enterhttps://gitea.comorhttps://codeberg.org. - Personal / API / access token: paste the token.
- Repository URL (optional): leave blank.
- Instance URL (HTTPS): your server's address, such as
- Choose Connect with token.
GitComet Pro checks the token by asking the server who it belongs to, then saves it in your operating system's keychain. The token never leaves your device except to go to your server.
When the connection is saved, its Repository access list shows your repositories. Select each repository you want to use in GitComet Pro to approve it on this device.
When the token expires or is deleted
The server rejects a deleted token, and the connection shows Reconnect required. To fix it:
- Generate a new token with the same permissions.
- In GitComet Pro, open the connection's menu and choose Reconnect.
- Choose Use a token, paste the new token, and choose Reconnect with token.
- Approve your repositories again. Reconnecting clears the approvals.
Troubleshooting
The token is rejected straight away. Check that user is set to Read. GitComet Pro cannot identify the token's owner without it.
"Connected, but repositories could not be loaded." The token has no repository access. Set repository to Read or higher, then choose Refresh repositories.
Private repositories are missing. The token was created with Public only. Create one with All (public, private, and limited) and reconnect.
Pull requests load, but the conversation is empty or commenting fails. The token is missing issue, or has it at Read where commenting needs Read and Write.
Merging, reviewing, or running a workflow fails. The token has repository: Read only. Create one with Read and Write and reconnect.
Publishing to an organization fails. The token needs organization: Read and Write, and your account needs permission to create repositories in that organization.