Federating Forgejo: Cross‑Instance Collaboration with ForgeFed

Why Federation Matters for Your Forgejo Instance

Running multiple Forgejo installations is common in large organizations or open‑source ecosystems. Without a shared network, developers must copy code, manually sync issues, and manage pull‑request workflows across instances. Forgejo’s ForgeFed feature, built on the ActivityPub protocol, lets repositories, issues, and pull requests flow between independent servers without a central authority. The result is a seamless, decentralized collaboration layer that keeps each instance autonomous yet interconnected.

Enabling Federation: The Minimum Prerequisites

Before you can exchange data, both the source and destination instances must opt‑in. The following steps assume you’re running Forgejo 1.21+ on Debian‑based Docker containers.

1. Set the federation flag. Edit app.ini (or the FORGEJO_FEDERATION_ENABLED env var) on each instance:

   app.ini
   [server]
   # Enable federation
   FEDERATION_ENABLED = true
   

2. Restart the service. The change takes effect on the next restart.

3. Configure peer discovery. In app.ini, list the other instance’s public URL in the allow list and optionally block any that should not communicate:

   [federation]
   ALLOWED_INSTANCES = https://forgejo.example.org
   BLOCKED_INSTANCES = https://untrusted.example.net
   

4. Verify the instance can reach the peer by inspecting the admin dashboard under Admin → Federation or by querying /api/v1/federation/stats with an admin token.

Per‑Repository Granularity: Who Can Federate?

Even with federation globally enabled, each repository owner decides whether to expose the repo to the network. In the repository settings under Advanced → Federation, toggle Allow federation. Private repositories are automatically excluded. This fine‑grained control prevents accidental data leaks and keeps sensitive projects isolated.

Cross‑Instance Pull Requests: A Step‑by‑Step Walkthrough

Let’s walk through a typical scenario where a developer on forgejo.devops.local wants to contribute to a repository hosted on forgejo.opensource.org.

1. Fork the upstream repository. On forgejo.opensource.org, click Fork. The fork resides on forgejo.devops.local and inherits the same ActivityPub actor identity.

2. Push changes. Clone the fork locally, make changes, and push to forgejo.devops.local:

   git clone https://forgejo.devops.local/user/forked-repo.git
   cd forked-repo
   # make changes
   git add .
   git commit -m "Add new feature"
   git push origin main
   

3. Open a pull request on the upstream instance. Navigate to the forked repo on forgejo.devops.local, click New Pull Request, then choose forgejo.opensource.org/user/forked-repo:main as the base branch. The PR appears in the upstream UI as a normal PR, but the underlying ActivityPub Announce activity propagates the PR object to forgejo.opensource.org.

4. Review and merge. On forgejo.opensource.org, reviewers can comment, approve, or merge the PR locally. Once merged, the merge commit is pushed back to forgejo.devops.local via an ActivityPub Create activity, keeping both instances in sync.

All of this happens without any manual data transfer—only standard HTTP requests carrying JSON‑LD payloads. No separate message broker is required because the core Go code reuses existing models.

Monitoring and Debugging Federation

Forgejo ships a small admin CLI to inspect the federation state. Run the following commands on the instance that receives the activity:

# Show current delivery statistics
forgejo admin federation stats

# Force a cache refresh for remote actors
forgejo admin federation sync

The stats output shows inbound/outbound activity counts and any delivery failures. If you suspect a delivery issue, look at the federation_delivery table in PostgreSQL:

SELECT id, activity_id, status, attempts FROM federation_delivery ORDER BY created_at DESC LIMIT 20;

Typical errors include 4xx responses (e.g., 403 Forbidden) if the peer blocks you, or 5xx responses indicating a temporary outage. Adjust the ALLOWED_INSTANCES list or investigate the peer’s logs accordingly.

Trade‑Offs and Limitations

• Interoperability risk. ForgeFed is still a draft; other ActivityPub‑based Git platforms may not fully understand Forgejo’s object extensions. A minor version bump can break cross‑instance PRs.
• Database load. Every inbound activity writes a row to federation_activity. Large instances (>10k users) can hit ~500 activities/minute, increasing write contention. Consider a dedicated worker queue or read‑replica if you see high latency.
• Privacy leakage. Misconfigured allow/blocked lists can expose private repo metadata (e.g., existence, description). Audit app.ini regularly and run forgejo admin federation stats to spot unexpected inbound objects.
• CI/CD isolation. Forgejo Actions and other workflow artifacts do not federate; they remain local to the instance where the workflow is defined.

Bottom Line: Is Federation Right for You?

If your organization runs multiple Forgejo instances and wants to avoid manual code duplication while keeping data ownership local, enabling ForgeFed is a low‑overhead solution. It gives you the flexibility of a decentralized network without the operational complexity of a full‑blown federation platform. Just be mindful of the performance and privacy considerations outlined above, and keep your instances up to date with the latest Forgejo releases.

Ready to federate? Start by enabling the flag, toggling repository federation, and letting your developers create cross‑instance pull requests. The rest will happen automatically over HTTP.