from forgejo
This issue tracks the progress of implementing [federation](https://nlnet.nl/project/Gitea/) in Forgejo and Gitea. We're planning on merging federation into Forgejo first, then upstreaming it to Gitea.
# Task list
## Discovery
This is done.
- [x] Nodeinfo endpoint [go-gitea@github.com/gitea#16758](https://github.com/go-gitea/gitea/issues/16758) [#19561](https://github.com/go-gitea/gitea/pull/19561)
- [x] WebFinger [go-gitea@github.com/gitea#19462](https://github.com/go-gitea/gitea/pull/19462) [go-gitea@github.com/gitea#19133](https://github.com/go-gitea/gitea/pull/19133)
- [ ] Delegation? (WebFinger responses to a different domain, kinda like what Mastodon does with its WEB_DOMAIN variable)
- [ ] Gitea federation for instances using a subdirectory?
## Actors
This is almost done.
- [x] Create public/private keypair [go-gitea@github.com/gitea#17071](https://github.com/go-gitea/gitea/pull/17071)
- [x] HTTP signature middleware [go-gitea@github.com/gitea#19133](https://github.com/go-gitea/gitea/pull/19133)
- [x] Mapping Gitea's concepts ("People", "Teams") into AP "Actor" concepts
- [x] Mapping Gitea's actor concepts into the ontology
- [x] Assign Actor IRIs [go-gitea@github.com/gitea#19133](https://github.com/go-gitea/gitea/pull/19133)
- [x] Manage inbox and outbox
- [x] Generate user outbox from actions table
- [ ] Send out activities to followers
- [ ] Render followed user updates in your user feed
- [ ] Periodically fetch and update cached remote users' data
- [ ] Clean out avatar cache
## ForgeFed
- [x] Adapt Commit forgefed vocabulary for the needs of Gitea
- [x] Adapt Repository forgefed vocabulary for the needs of Gitea
- [x] Figure out the best way to represent pull requests in ForgeFed [ForgeFed@codeberg.org/ForgeFed#88](https://codeberg.org/ForgeFed/ForgeFed/issues/88)
- [ ] Merge [F3](https://forum.forgefriends.org/t/about-the-friendly-forge-format-f3/681) and ForgeFed
- [ ] Issue state changes [ForgeFed@codeberg.org/ForgeFed#98](https://codeberg.org/ForgeFed/ForgeFed/issues/98)
- [ ] Add milestones to ForgeFed
- [ ] Add project board federation to ForgeFed
- [ ] Add migrations to ForgeFed spec [ForgeFed@codeberg.org/ForgeFed#149](https://codeberg.org/ForgeFed/ForgeFed/issues/149)
## go-ap
We need to add ForgeFed types to go-ap. [Mastodon discussion](https://social.exozy.me/@ta180m/108466642486831048), [mailing list discussion](https://lists.sr.ht/~mariusor/activitypub-go/%3C6aivY9YmilsvQ6CauRoaXbvXX2bdZEXOEv-xnaTD0JLvodqKPZ2FMdQHmXYKmEOdzrPZU9Ipro5sOynfe-hJbi5f31MiqOV8EI4rDOw88wg%3D%40proton.me%3E), [current code](https://gitea.com/Ta180m/gitea/src/branch/main/models/forgefed)
- [x] Implement Commit type
- [x] Implement Repository type
- [x] Implement Branch type
- [x] Implement Push type
- [x] Implement Ticket type
- [ ] Tests
- [x] Export more JSON functions from go-ap/activitypub (solved by using a fork https://gitea.com/Ta180m/activitypub)
## Serving ActivityStreams
- [ ] Addressing (currently we just send to the IRI in the `To` field which is a bad hack)
- [x] Transport (HTTPS with HTTP signatures) [go-gitea@github.com/gitea#19133](https://github.com/go-gitea/gitea/pull/19133)
- [ ] Retry sending activities to servers that are down or have an outgoing activity queue
- [x] Serve AS representation of users
- [ ] Use F3 to serve AS representation of repos and repo contents
- [ ] Serve AS representation of organizations
## Processing ActivityStreams
- [x] Verify that actor or `attributedTo` matches HTTP signature.
- [ ] sharedInbox? (not necessary)
- [ ] C2S ActivityPub? (not necessary)
- [x] Process Follow and Undo Follow activities
- [ ] Process Like and Undo Like activities
- [ ] Use F3 to process repo-related activities
- [ ] Process organization-related activities
- [ ] Cross-instance Git push
- [ ] Federated private repos (use HTTP signatures for auth)
- [ ] Federated discussions? (like GitHub discussions?)
## Database representation of remote data
- [x] Remote federated users
- [ ] Remote organizations
- [x] Remote repositories
- [ ] Database field for storing IRIs
- [ ] External issues (and reference in comments)
- [ ] External PRs (and reference in comments)
- [ ] External projects (and reference in comments)
## User eXperience and User Interface
See https://gitea.com/xy/gitea/issues/8 for discussions
- [ ] Use cases ([federated issues](https://forum.forgefriends.org/t/forgefriends-full-description/13#presentation-1) etc.)
- [ ] Drafting UX in PenPot
- [ ] Remote interactions pop-up UI (like Mastodon)
- [x] `authorize_interaction?uri=` page (like Mastodon)
- [x] Federation handling for Gitea internal functions for creating issues, starring repos, etc
- [ ] Global search bar
- [ ] Discoverability (See https://sepiasearch.org/, https://github.com/forgeflux-org/northstar)
## Migrations
See https://gitea.com/xy/gitea/issues/9
- [ ] Username or repo renames
- [ ] Moving a user or repo to a different instance
- [ ] Official way to migrate entire GitHub account to a Gitea instance
- [ ] Official way to migrate entire GitHub organization to a Gitea instance
- [ ] Configurable cooldown period in which usernames cannot be claimed
## Interoperability
- [x] Federated following with Mastodon, Pleroma, etc
- [ ] Federated commenting on issues from Mastodon, etc [mastodon@github.com/mastodon#18806](https://github.com/mastodon/mastodon/issues/18806)
- [ ] Handle Mastodon delegation
- [ ] Federation with GitHub by redirecting github.com resources to a different domain that generates AS representations of GitHub data and can proxy issues and PRs via a bot account on GitHub, something like Forgeflux or Forgefriends?
## Moderation
See https://gitea.com/xy/gitea/issues/10
- [x] Disable all federation features by default
- [ ] Blocking a user
- [ ] Blocking a server
- [ ] Moderation UI
- [ ] Limited federation mode where your instance only federates with whitelisted instances
- [ ] Rate limit federation requests
- [ ] Rate limit user signups
- [ ] Rate limit issue creation/commenting in UI
# Contributing
If you'd like to help out with forge federation but don't know where to start, the links below might be helpful.
## General
Some high-level links for learning about forge federation and the bigger picture
- https://matrix.to/#/#general-forgefed:matrix.batsense.net General forge federation chatroom
- https://matrix.to/#/#forgefederation:matrix.batsense.net Forge federation Matrix space
- https://forum.forgefriends.org/ ForgeFriends forum
- https://forgeflux.org/ Forge federation using forge APIs
- https://coding.social/ Social Coding movement
- https://forgefriends.org/blog/2022/06/30/2022-06-state-forge-federation/ The state of forge federation, 2021-2023
## ActivityPub
Resources for learning ActivityPub (AP)
- https://activitypub.rocks/ Official ActivityPub website
- https://www.w3.org/TR/activitypub/ ActivityPub specification
- https://socialhub.activitypub.rocks/pub/guide-for-new-activitypub-implementers Guide for AP implementers
- https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ Tutorial for implementing a very basic AP server
- https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/ Tutorial for federated following
- https://docs.joinmastodon.org/spec/activitypub/ Mastodon's AP subset
- https://tinysubversions.com/notes/reading-activitypub/ How to read the AP spec
- https://flak.tedunangst.com/post/ActivityPub-as-it-has-been-understood Lots of AP resources
- https://delightful.club/delightful-activitypub-development/ AP developer resources
## ForgeFed
Forge federation protocol based on AP
- https://forgefed.org/ ForgeFed website
- https://codeberg.org/ForgeFed/ForgeFed ForgeFed repo
- https://matrix.to/#/#forgefed:libera.chat ForgeFed chatroom
- https://vervis.peers.community/browse Reference ForgeFed implementation
## Go-Ap
A lightweight AP library in Go that Gitea is using for implementing federation
- https://github.com/go-ap/activitypub Lightweight Go implementation of AP
- https://github.com/go-ap/fedbox Reference implementation of a AP server using go-ap
- https://github.com/mariusor/go-littr Federated link aggregator using go-ap
- https://man.sr.ht/~mariusor/go-activitypub/go-ap/index.md go-ap docs
- https://lists.sr.ht/~mariusor/activitypub-go go-ap mailing lists
# Running federated Forgejo
You can also help federation development by running federated Forgejo and reporting bugs and regressions.
- Make backups: This code will make possibly unexpected changes to your database.
- Compile: Clone this repo and checkout the `forgejo-federation` branch. If you would like to build a Docker image, there is a `Dockerfile` in this repo. If you would like to build a binary, install Go and Node.js and then run `TAGS="bindata" make`.
- Configuration: Set `ENABLED=true` in the `[federation]` section of your config file.