Integrations

1. Octopus Cloud + public HTTPS

Use this when Octopus Cloud can reach your Forgejo instance over public HTTPS. Forgejo also needs outbound HTTPS access to Octopus Cloud for webhooks.

1. Open Octopus Cloud → Settings → Integrations → Forgejo and choose Public HTTPS instance.
2. Enter the public HTTPS instance URL and the Forgejo personal access token. Connect and sync repositories. Octopus stores this token encrypted.
3. Add the signed repository webhooks, then prepare your repository and enable reviews.

2. Octopus Cloud + private LAN/VPN

1. 1

   In Forgejo

   Create the Forgejo access token

   Sign in with a dedicated account that administers only the repositories you want reviewed. It does not need instance administrator access.

   Open that account's Settings → Applications and generate a personal access token with read:user, write:repository and write:issue.

   For private repositories, choose All (public, private, and limited); limit access through the account's repository permissions. Full token requirements.

   Keep this token locally. It becomes FORGEJO_TOKEN in step 3. You do not paste it into Octopus Cloud.

2. 2

   In Octopus Cloud

   Create the connector token

   Open Forgejo settings

   In Settings → Integrations → Forgejo, select Private network connector. Enter your exact HTTPS Forgejo address and click Create connector.

   Click Copy connector token and save it securely; it is shown only once. This separate token pairs your local connector with Octopus and becomes OCTOPUS_CONNECTOR_TOKEN below.

3. 3

   On the connector machine

   Create your configuration file

   Create a file named connector.env and paste this template. Replace the example address and both token placeholders.

   connector.envCopy

   OCTOPUS_URL=https://octopus-review.ai
   OCTOPUS_CONNECTOR_TOKEN=YOUR_CONNECTOR_CREDENTIAL
   FORGEJO_URL=https://forgejo.internal.example
   FORGEJO_TOKEN=YOUR_FORGEJO_PERSONAL_ACCESS_TOKEN

   OCTOPUS_CONNECTOR_TOKEN

   The one-time token from Octopus in step 2.

   FORGEJO_TOKEN

   The personal access token from Forgejo in step 1.

   Keep this file private and out of your Git repositories.

4. 4

   On the connector machine

   Start the connector with Docker

   Open a terminal in the folder containing connector.env and run this command. It downloads the connector and starts it in the background. Keep the container running for indexing and reviews.

   If Forgejo uses an internal certificate authority, use the trusted CA command below instead.

   Terminal — start the connectorCopy

   chmod 600 connector.env
   docker run -d --name octopus-forgejo-connector \
     --restart unless-stopped --stop-timeout 120 --read-only \
     --env-file connector.env \
     ghcr.io/octopusreview/octopus-selfhost:forgejo-connector-1.2.0

   Using an internal certificate authority?

   Before starting the container, add this line to connector.env:

   Add to connector.envCopy

   NODE_EXTRA_CA_CERTS=/certs/forgejo-ca.pem

   Use the command below, replacing /absolute/path/forgejo-ca.pem with the trusted PEM certificate file on your machine. The file is mounted read-only. Keep TLS certificate verification enabled.

   Terminal — start with your trusted CACopy

   chmod 600 connector.env
   docker run -d --name octopus-forgejo-connector \
     --restart unless-stopped --stop-timeout 120 --read-only \
     --env-file connector.env \
     --mount type=bind,src=/absolute/path/forgejo-ca.pem,dst=/certs/forgejo-ca.pem,readonly \
     ghcr.io/octopusreview/octopus-selfhost:forgejo-connector-1.2.0

5. 5

   Back in Octopus Cloud

   Check the connection and sync repositories

   Return to Forgejo settings and click Refresh status. When the status reads Connector online, click Sync repositories.

   Only repositories the Forgejo account administers will appear. If the status stays Waiting for connector or Connector offline, check that its container can reach both Forgejo and Octopus Cloud before continuing.

6. 6

   In each Forgejo repository

   Add the signed webhook

   Open the repository's Settings → Webhooks → Add Webhook → Forgejo. Copy the webhook URL and secret shown in Octopus Forgejo settings.

   • Use POST and application/json.
   • Under Trigger on, choose Custom events….
   • Under Pull request events, select Modification and Synchronized to review new pull requests and pushed commits.
   • In that same group, select Comments for @octopus or /octopus PR commands. Keep Active checked and save the webhook.

   The webhook goes directly from Forgejo to Octopus Cloud. Webhook and review-event details.

7. 7

   In Octopus Cloud

   Confirm readiness and open your first PR

   1. Open Repositories and click your Forgejo repository.
   2. Confirm Auto Review is on in the repository panel; enable it if needed. You can change this setting while preparation is running.
   3. Octopus indexes and analyzes automatically when a review starts. You can open a PR without clicking Index now or Run Analysis. Preparation progress appears in the repository panel and the first-review guide.

   Try your first review

   Open a non-draft pull request in Forgejo and follow it in Review Logs. Check that the review completes and its comments and final commit status appear on Forgejo. A successful webhook test alone does not confirm the full review flow.

3. Self-hosted Octopus + private LAN/VPN

Run your own Octopus web application and review workers where both can reach Forgejo. Enable self-host mode and explicitly allow the exact HTTPS origin through FORGEJO_ALLOWED_PRIVATE_ORIGINS. This direct connection does not require the local connector.

1. Follow the self-hosted network, DNS and certificate setup on both web and review workers.
2. In your Octopus Settings → Integrations → Forgejo, enter the private HTTPS origin and personal access token, then click Connect Forgejo to connect and sync repositories.
3. Add signed webhooks targeting your own Octopus deployment. If the target is private, allow its exact host in Forgejo's [webhook] ALLOWED_HOST_LIST, keeping existing entries.
4. In your own Octopus deployment, open Repositories, select the repository and confirm Auto Review is on. Open a non-draft PR; indexing and analysis run automatically. Follow Review Logs until the first review completes.

Your Octopus deployment and configured AI services determine where reviews are processed. Use local AI services when processing must stay on your network.

Signed webhooks and review events

In each synced Forgejo repository, open Settings → Webhooks → Add Webhook → Forgejo. Use POST, application/json, and the target URL and secret shown in Octopus. Under Trigger on, choose Custom events… → Pull request events, then select Modification and Synchronized. Select Comments in that same group for @octopus or /octopus PR commands. Keep Active checked and save the webhook. A successful Test Delivery checks transport; a real pull request checks the complete review flow.

With automatic reviews enabled, Octopus accepts pull_request events with action opened, reopened or synchronized, plus edited events containing changes.title.from. Removing a draft title prefix can trigger that title-change event. Octopus checks the current PR on Forgejo: only open, non-draft PRs qualify. Body-only edits do not trigger reviews. Automatic events skip a head with a prior review attempt or completed review, and cannot admit a second request while that head is pending, queued or reviewing.

For an explicit re-review of a completed head, post a new comment with the complete @octopus or /octopus command, or request it from Octopus. Longer aliases such as @octopus-review are not accepted. Replaying the same signed webhook payload does not create another review request.