Back to documentation
GitHub Integration

Deploy from Gitea or Forgejo

Connect a self-hosted Gitea, Forgejo or Codeberg account with an access token and deploy private repositories, with the SSH key and a custom SSH port handled for you.

Intermediate6 min readUpdated 2026-11-22

What you need

A self-hosted Gitea 1.19 or newer, any Forgejo release, or a Codeberg account, and an access token for it. One account type covers all three, because Forgejo keeps Gitea's API.

Create the token in your instance under Avatar → Settings → Applications → Generate New Token. Give it user: Read and write (to add the SSH key) and repository: Read. Add organization: Read if you deploy organization repositories. Copy the token before leaving the page.

Connect the account

  1. Open a server's Git tab and choose Add New, then Gitea / Forgejo. The same form is on the sidebar's Git page and behind Add Gitea / Forgejo account in Server Settings
  2. Enter an Account name
  3. Enter the Instance URL: the address you open in the browser, including any port or sub-path, for example http://10.0.1.78:3000. Do not add /api/v1
  4. Paste the Access token
  5. Leave Generate and upload an SSH key on
  6. Choose Connect account

Server Compass checks every permission the token needs before it saves anything. A token with too few permissions is refused with the missing one named, for example it is missing write:user.

Instances on plain HTTP

When the Instance URL starts with http://, the form shows This instance uses unencrypted HTTP with Allow HTTP for this account. Connect account stays disabled until you tick it, and the token is never sent over HTTP without that choice. Only enable it on a network you trust, such as your LAN or a VPN.

For an HTTPS instance with a self-signed certificate, open Show advanced trust options and tick Trust a self-signed HTTPS certificate for this account.

SSH keys and custom SSH ports

Generate and upload an SSH key creates a key on your server, adds it to your Gitea or Forgejo account, and writes an SSH alias for the account into the server's SSH config. The account card shows it as the Clone URL prefix, for example git@gitea-yourname:.

You do not need to enter the SSH port. Gitea and Forgejo advertise it in each repository's clone address (for example ssh://git@10.0.1.78:2222/owner/repo.git), and Server Compass reads it when you connect, before each SSH test and before each deploy. If the account has no repositories yet when you connect, the port is picked up once one exists.

Deploy a repository

In the Stack Wizard, choose a Git repository and your connected Gitea or Forgejo account, then pick the repository and branch. Server Compass reads the repository's Dockerfile and compose file, clones it on your server over SSH and builds it there. Redeploying with the latest code pulls new commits through the same account.

If something goes wrong

  • No Gitea or Forgejo API answered: the Instance URL is not the web root. Use the address you open in the browser
  • did not advertise an SSH clone URL: SSH is disabled on the instance. Set DISABLE_SSH = false in the [server] section of app.ini
  • The SSH test fails on the right key: check SSH_DOMAIN and SSH_PORT in app.ini, because Server Compass uses the host and port the instance advertises

Screenshots

Deploy from Gitea or Forgejo - Screenshot 1
Deploy from Gitea or Forgejo - Screenshot 2
Deploy from Gitea or Forgejo - Screenshot 3

Frequently Asked Questions

Does this work with Codeberg?

Yes. Codeberg runs Forgejo, so connect it with Instance URL https://codeberg.org and a Codeberg access token.

Can I connect two accounts on the same instance?

Yes. Each account gets its own SSH key and alias, so their clone URL prefixes differ and they never share a key.

Related Features

Ready to try Server Compass?

Download the app and deploy your first application in under 5 minutes.

Download Server Compass