A new hosted project on AFNix

Step 0: Check whether the project belongs on AFNix

AFNix hosted projects have a few requirements:

Related to the Nix ecosystem.
Temporary: willing to accept short-to-mid-term instability as we figure out things on the fly.
(TODO: in compliance with our overall Code of Conduct)
(TODO: in compliance with our overall AI Policy)

While we are bootstrapping AFNix, we also require agreement of a majority of AFNix board members to onboard a new project. This is not intended to be the final process, and we'd like more objective and/or democratic processes, but we're not set up for this yet.

Step 1: Create Forgejo org

Permissions required: Forgejo admin.

For most projects, we prefer namespacing their repository/repositories under their own org. Preferred naming convention: lowercase-dash-separated.

Create a new org on git.afnix.fr under your own user. Initially it contains your user as one of the owners of the org - this will be removed in a later step.

All org defaults can be left as-is, customization can be handled by project maintainers themselves.

Step 2: Create Keycloak group

Permissions required: Keycloak admin, AFNix Terraform access.

We track user<->project role mappings in Keycloak via a terraformed configuration.

In https://git.afnix.fr/afnix/infra/src/branch/main/terraform/afnix_superadmin/keycloak/org-groups.nix, update the memberships attrset with the usernames of the project maintainers.

E.g. if toto maintains the new project tata, add underneath # Hosted projects:

let
  ...

  memberships = {
    "afnix" = [ ... ];

    # Hosted projects
    ...

    "tata" = [ "toto" ];
  };

Then, redeploy the keycloak configuration.

Step 3: Update Forgejo group/role mapping

Permissions required: AFNix infra.

In https://git.afnix.fr/afnix/infra/src/branch/main/hosts/afnix/yuki/forgejo.nix also update the initial provisioning script to match. This should be as easy as adding the org name to keycloakManagedOrgs.

At this point, the project maintainer should be able to log out/in from git.afnix.fr and have owner permissions on the org for their project. They can create new repositories within the org and invite new collaborators.

Step 4: Optional: Add Forgejo actions runners

Permissions required: AFNix infra.

Make sure the project maintainer is aware of the limitations of the Forgejo actions runners (esp. regarding security). This should ideally be a documentation page, but we do not have it now.

Follow the template from https://git.afnix.fr/afnix/infra/commit/fee791f487b8785d4714938e4c096d89e3960cba for how to deploy new actions runners. The secret file should contain a single line of text: TOKEN=registration token value with registration token value being the value shown by Forgejo when going to the "Runners" tab of the Org settings page. If you are still a member of the Forgejo org, you can get it yourself, or you can ask the project maintainer to get it for you.

Don't forget to apply the changes.

Step 5: Remove yourself from the org owners

This should happen automatically on next Forgejo login, but if it doesn't: don't forget to remove yourself from the owners of the Forgejo org you created.

Keyboard shortcuts