Magic git repository to manage the settings of an organization #66

wetneb commented 2026年05月19日 16:01:19 +02:00

Warning

Please read this section of the README before interacting in the issue tracker.
We might remove comments that don't fit here. This is unfortunately necessary, because respect for design work is not yet common in Free/Libre Software projects.

Content

Motivation

Owners of Forgejo organizations can perform sensitive actions with little scrutiny. A lot of those actions don't generate any notifications or audit log, so they are hardly traceable after the fact.
It would be useful if there could be a way to propose changes, let them be reviewed by other team members and only perform them once a consensus has been reached. See also forgejo/forgejo#12451.

One possible way to add this oversight would be to use a Git repository to mirror organization settings, and discuss changes as pull requests on this repository.

There already exist various tools to synchronize organization settings in this way: for instance, a Terraform provider for Forgejo could be used for that, and there are a couple of other tools developed for GitHub that could be ported to Forgejo, such as Peribolos or github-org-manager.
Still, setting those up requires some time and resources (CI infrastructure) and using API tokens with owner permissions.

Idea

Instead of going through an external tool, Forgejo itself could offer such "magic" repositories (when the corresponding option would be enabled for the organization).
Forgejo would take care of the synchronization between the repository contents and the organization settings by itself.

The scope of the settings that are reflected in the repository could potentially be configured. For instance, an organization could decide to only use this magic repository for membership management and leave the other settings to be managed manually, outside of the git repository. The UI and API would forbid direct changes to the parts of org settings which are managed via Git.

Proposals to have special interfaces for reviewing changes, such as forgejo/forgejo#12451 or #65, could potentially be implemented as some sort of UI coating on top of this feature.

> **Warning** > Please read [this section of the README](https://codeberg.org/forgejo/design#what-you-can-do-here) before interacting in the issue tracker. > We might remove comments that don't fit here. This is unfortunately necessary, because respect for design work is not yet common in Free/Libre Software projects. ### Content ### Motivation Owners of Forgejo organizations can perform sensitive actions with little scrutiny. A lot of those actions don't generate any notifications or audit log, so they are hardly traceable after the fact. It would be useful if there could be a way to propose changes, let them be reviewed by other team members and only perform them once a consensus has been reached. See also https://codeberg.org/forgejo/forgejo/issues/12451. One possible way to add this oversight would be to use a Git repository to mirror organization settings, and discuss changes as pull requests on this repository. There already exist various tools to synchronize organization settings in this way: for instance, a [Terraform provider for Forgejo](https://github.com/svalabs/terraform-provider-forgejo) could be used for that, and there are a couple of other tools developed for GitHub that could be ported to Forgejo, such as [Peribolos](https://docs.prow.k8s.io/docs/components/cli-tools/peribolos/) or [github-org-manager](https://github.com/OpenRailAssociation/github-org-manager). Still, setting those up requires some time and resources (CI infrastructure) and using API tokens with owner permissions. ### Idea Instead of going through an external tool, Forgejo itself could offer such "magic" repositories (when the corresponding option would be enabled for the organization). Forgejo would take care of the synchronization between the repository contents and the organization settings by itself. The scope of the settings that are reflected in the repository could potentially be configured. For instance, an organization could decide to only use this magic repository for membership management and leave the other settings to be managed manually, outside of the git repository. The UI and API would forbid direct changes to the parts of org settings which are managed via Git. Proposals to have special interfaces for reviewing changes, such as https://codeberg.org/forgejo/forgejo/issues/12451 or https://codeberg.org/forgejo/design/issues/65, could potentially be implemented as some sort of UI coating on top of this feature.

wetneb commented 2026年05月20日 07:48:00 +02:00

Another potential benefit of GitOps-based management of organization settings would be to ease the portability across Forgejo instances. If you want to migrate your project to another Forgejo instance, having your org settings materialized in this way would be helpful to import them again in the new instance. (But the existing work on federation might also help.) Caveats apply of course: for instance, users might have different names on the instances, so some small edits to the files might be needed.

Another potential benefit of GitOps-based management of organization settings would be to ease the portability across Forgejo instances. If you want to migrate your project to another Forgejo instance, having your org settings materialized in this way would be helpful to import them again in the new instance. (But the existing work on federation might also help.) Caveats apply of course: for instance, users might have different names on the instances, so some small edits to the files might be needed.

Gusted commented 2026年05月22日 13:01:38 +02:00

I have concerns with the implementation of such proposal. Fetching contents out of a git repository is not relatively fast, and in general you can't query for it. I have a feeling it would be necessary to still synchronize such settings to a database table.

I have concerns with the implementation of such proposal. Fetching contents out of a git repository is not relatively fast, and in general you can't query for it. I have a feeling it would be necessary to still synchronize such settings to a database table.

wetneb commented 2026年05月22日 14:32:12 +02:00

Absolutely - there would still be a need for a synchronization mechanism between the existing SQL storage of those settings and the git repo. This synchronization would only need to happen when the main branch of the magic repo is updated. This would hopefully make the feature not too intrusive in the code base, as the rest of the code could continue to fetch this information where it has been stored so far.

I imagine that the main impact would come from the need to disable some parts of the web UI and API if the settings they act on are managed via the special git repository (because a commit on the repo needs to be made instead), or changing them so that they initiate the corresponding PR on the magic repo. For instance, if I try to add a member to the organization via the web UI and that organization uses a git repo to manage its members, it would either forbid it or lead me to making a PR on the magic repo instead.

Absolutely - there would still be a need for a synchronization mechanism between the existing SQL storage of those settings and the git repo. This synchronization would only need to happen when the main branch of the magic repo is updated. This would hopefully make the feature not too intrusive in the code base, as the rest of the code could continue to fetch this information where it has been stored so far. I imagine that the main impact would come from the need to disable some parts of the web UI and API if the settings they act on are managed via the special git repository (because a commit on the repo needs to be made instead), or changing them so that they initiate the corresponding PR on the magic repo. For instance, if I try to add a member to the organization via the web UI and that organization uses a git repo to manage its members, it would either forbid it or lead me to making a PR on the magic repo instead.

mfenniak commented 2026年05月22日 16:46:28 +02:00

@wetneb wrote in #66 (comment):

This synchronization would only need to happen when the main branch of the magic repo is updated. This would hopefully make the feature not too intrusive in the code base, as the rest of the code could continue to fetch this information where it has been stored so far.

This could be quite a frustrating experience in handling any errors -- if invalid settings are pushed into the repo, or, changes made through the UI/API have some failure to sync to the repo, the user experiencing for error detection and recovery could be quite ugly.

I think the concept presented here is interesting. My thought is that before this kind of enhancement could be fully considered for inclusion in Forgejo, it would be best to be developed as a proof-of-concept implementation. For example, using a repository, a Forgejo terraform provider, and a CI system could demonstrate the concept end-to-end and reach motivated users who want a solution in this space. Specific challenges arising from that could lead to specific narrow solutions being incorporated into Forgejo first, which would both serve as a building block to this enhancement, and ease challenges in the proof-of-concept -- for example, "An admin can still edit a repo's settings bypassing the automated system" could lead to improvements in access control granularity to support the external integration and a potential future internal implementation.

@wetneb wrote in https://codeberg.org/forgejo/design/issues/66#issuecomment-15662543: > This synchronization would only need to happen when the main branch of the magic repo is updated. This would hopefully make the feature not too intrusive in the code base, as the rest of the code could continue to fetch this information where it has been stored so far. This could be quite a frustrating experience in handling any errors -- if invalid settings are pushed into the repo, or, changes made through the UI/API have some failure to sync to the repo, the user experiencing for error detection and recovery could be quite ugly. I think the concept presented here is interesting. My thought is that before this kind of enhancement could be fully considered for inclusion in Forgejo, it would be best to be developed as a proof-of-concept implementation. For example, using a repository, a Forgejo terraform provider, and a CI system could demonstrate the concept end-to-end and reach motivated users who want a solution in this space. Specific challenges arising from that could lead to specific narrow solutions being incorporated into Forgejo first, which would both serve as a building block to this enhancement, and ease challenges in the proof-of-concept -- for example, "An admin can still edit a repo's settings bypassing the automated system" could lead to improvements in access control granularity to support the external integration and a potential future internal implementation.

wetneb commented 2026年05月22日 20:30:55 +02:00

This could be quite a frustrating experience in handling any errors -- if invalid settings are pushed into the repo, or, changes made through the UI/API have some failure to sync to the repo, the user experiencing for error detection and recovery could be quite ugly.

There are a lot of corner cases to consider very carefully, it's definitely not a straightforward feature. Concerning invalid settings, I was thinking that this integrated approach would perhaps make it possible to reject invalid pushes via a git hook, offering more guarantees than an implementation via a third-party tool. But I'm not well-versed enough in Forgejo's internals to understand to what extent that would be doable.

I completely agree with you that it's worth prototyping with a third-party tool first.
This design proposal mostly stands as an alternative to #65, to explore various approaches.

> This could be quite a frustrating experience in handling any errors -- if invalid settings are pushed into the repo, or, changes made through the UI/API have some failure to sync to the repo, the user experiencing for error detection and recovery could be quite ugly. There are a lot of corner cases to consider very carefully, it's definitely not a straightforward feature. Concerning invalid settings, I was thinking that this integrated approach would perhaps make it possible to reject invalid pushes via a git hook, offering more guarantees than an implementation via a third-party tool. But I'm not well-versed enough in Forgejo's internals to understand to what extent that would be doable. I completely agree with you that it's worth prototyping with a third-party tool first. This design proposal mostly stands as an alternative to #65, to explore various approaches.