Create a Forgejo service

Apply the following object to your namespace, as specified by its YAML description.

Example to create a Forgejo instance
apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNForgejo
metadata:
  name: forgejo-app1-prod (1)
  namespace: mynamespace (2)
spec:
  parameters:
    service:
      adminEmail: "admin@mydomain.com" (3)
      fqdn:
        - "forgejo.mydomain.com" (3)
      forgejoSettings: (4)
        APP_NAME: ""
        config:
          actions: {}
          openid: {}
          oauth2: {} (5)
          oauth2_client: {} (6)
          service: {}
          service.explore: {}
          mailer: {}
          email.incoming: {}
          cors: {}
          git.timeout: {}
          admin: {}
          repository: {}
          server: {} (7)
      majorVersion: "12.0.0" (8)
  writeConnectionSecretToRef:
    name: forgejo-creds (9)
1 Instance name
2 The namespace where the object will be created
3 Your full qualified domain name
4 Define select app.ini settings, refer to the config cheat sheet to see available fields
5 Settings for Forgejo acting as an OAuth2 provider, see OAuth2 config reference
6 Settings for Forgejo acting as an OAuth2 client (logging in via an external identity provider such as Keycloak), see OAuth2 client config reference
7 Some server keys are managed by AppCat, see AppCat-managed settings below
8 Forgejo major version - Supported Versions
9 The name of the secret where the connection details will be stored, it must be unique per namespace

AppCat-managed settings

Your forgejoSettings.config is merged on top of the AppCat defaults, per key. The following [server] keys are managed by AppCat and cannot be overridden. Any value you set for them is ignored:

Setting Managed value

server.DOMAIN

First entry of spec.parameters.service.fqdn

server.ROOT_URL

https:// + first entry of spec.parameters.service.fqdn

server.DISABLE_SSH

Controlled by spec.parameters.service.ssh.enabled

The first domain in .spec.parameters.service.fqdn becomes server.DOMAIN and server.ROOT_URL, which influences Forgejo’s root URL. Applicable to things like webhook notifications, OAuth, and similar functionalities.

When SSH access is enabled, AppCat also sets server.START_SSH_SERVER, server.SSH_DOMAIN, and server.SSH_PORT. Do not set SSH-related [server] keys (including SSH_LISTEN_PORT), as overriding them can break SSH access to your repositories.

To get more information about all available configuration options, please see the API Reference

Changes to the claim spec take effect immediately on apply and bypass the maintenance window entirely.

Some changes (such as plan upgrades, replica count changes, resource sizing, or pinImageTag updates) can trigger pod restarts or short connection interruptions. Apply disruptive edits at a time that suits your workload.

Inspect your new Forgejo service

$  oc get vshnforgejo.vshn.appcat.vshn.io
NAME                SYNCED   READY   CONNECTION-SECRET   AGE
forgejo-app1-prod   True     True    forgejo-creds       4m23s

When you see True in the READY column, it means the instance is provisioned but the pods might still be starting. It may take some time for the instance to be available especially during the provisioning phase.

Find the connection details

The connection details are stored in a secret. You can retrieve them with the following command:

$ oc get secrets forgejo-creds -o yaml

The output of the command above is a secret specification with the following structure:

apiVersion: v1
kind: Secret
stringData:
  FORGEJO_PASSWORD: a09gGvIF3cKDlD7K (1)
  FORGEJO_URL: forgejo.mydomain.com (2)
  FORGEJO_USERNAME: forgejo_admin (3)
metadata:
  (...) # omitted for brevity
1 Password for the Forgejo instance
2 URL to access the Forgejo instance
3 Username to access the Forgejo instance
Do not rename or change the password of the initial admin user (forgejo_admin) through the Forgejo web UI or admin CLI. The admin credentials are managed internally and stored in the connection secret defined in writeConnectionSecretToRef. Changes made outside of this mechanism will not be reflected in the secret, causing a mismatch between the stored credentials and the actual Forgejo account. If you need to change the admin password, please contact Support.