Forgejo

Host Git repositories, issues and code reviews over HTTP.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Forgejo

Editable Compose files in your own directory.

Enable the installation lock and restart after reviewing database and public URL settings.
Run Create administrator with an explicitly chosen account, then verify sign-in.

selfhost app --directory ./forgejo init forgejo

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./forgejo start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd forgejo
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Forgejo, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "forgejo",
  "name": "Forgejo",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Before configuring integrations

The OIDC action configures a named authentication source.
Dedicated, shared and external PostgreSQL choices apply to fresh deployments.
Database placement includes PostgreSQL, MySQL and MariaDB using app-specific connection settings. Select a fresh or already migrated database before first start; changing the engine does not convert existing data.
MySQL and MariaDB TLS uses server certificate verification whenever enabled. A source configured as require therefore still needs a certificate trusted by the app; private CA certificates must be installed in the app trust store.
Changing the database connection is not a data migration. Back up repositories, configuration and database before moving an existing installation.

Forgejo integrations

Compose service: forgejo. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (4)

Public URL public-url: string
Disable registration registration: stringChoices: true, false
Require login to view content require-login: stringChoices: true, false
Disable web installation wizard install-lock: Set true and restart before creating an administrator with the reviewed action. stringChoices: true, false

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./forgejo config forgejo
selfhost app --directory ./forgejo plan forgejo changes.json
selfhost app --directory ./forgejo apply forgejo changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /user/oauth2/selfhost/callback.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell.

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "Forgejo"
}

selfhost app --directory ./forgejo connect-account forgejo connection.json
selfhost app --directory ./forgejo connect-plan forgejo connection.json
selfhost app --directory ./forgejo connect forgejo connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

Database placement

This recipe supports postgres, mysql, mariadb. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

postgres adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
mysql adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
mariadb adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App actions

Create administrator

Create an explicitly selected administrator. Existing users are never changed. Restart after enabling installation lock first.

Username username: stringLength: 1 to 255 characters
Password password: secretLength: 12 to 255 characters
Email email: stringLength: 1 to 255 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./forgejo action forgejo create-admin --inputs action-inputs.json

List users

Show local users and administrator status.

selfhost app --directory ./forgejo action forgejo list-users

List identity providers

Show configured authentication sources.

selfhost app --directory ./forgejo action forgejo list-auth

Connect OpenID provider

Create a login source called selfhost. An existing source with that name causes an error; it is never replaced.

Client ID client-id: stringLength: 1 to 255 characters
Client secret client-secret: secretLength: 12 to 255 characters
Discovery URL discovery-url: stringLength: 1 to 255 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./forgejo action forgejo connect-oidc --inputs action-inputs.json

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

forgejo: codeberg.org/forgejo/forgejo:16

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Forgejo documentation