How to Create a New Organization in Fedora Forge

DRAFT DOCUMENTATION: This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.

Purpose

This document outlines the steps required to create a new organization within the Fedora Forge, ensuring proper configuration for repository creation and team management.

Scope

This SOP applies to Fedora Project contributors with administrator privileges on the Fedora Forge.

Prerequisites

  • Administrator Privileges: The user must possess administrator privileges on the Fedora Forge. Membership in the sysadmin-main group automatically grants these privileges on Fedora Forge.

  • Fedora Account Group: Identify the specific Fedora Accounts group that will be designated as the "Owners" team for the new organization.

Procedure

The organization creation process involves six main steps: logging in as an administrator, initiating organization creation, completing the organization form, navigating to settings, configuring organization details, setting repository limits, and assigning Fedora Accounts groups as owners.

Log In as Administrator

  1. Navigate to the Fedora Forge login page.

  2. Log in using a user account that possesses administrator privileges.

  3. Verification: Upon successful login, observe the top-right corner of the Fedora Forge page. The presence of a "+" icon indicates that you have administrator privileges. If this icon is absent, you don’t have the necessary permissions and can’t proceed with this procedure.

Initiate New Organization Creation

  1. Click on the "+" icon located in the top-right corner of the Fedora Forge page.

  2. From the dropdown menu, select "New Organization."

Complete "New Organization" Form

  1. The "New Organization" form will be displayed.

  2. In the "Organization Name" field, enter the desired name for the new organization.

  3. Click the "Create Organization" button.

Navigate to Organization Settings

  1. Upon creating the organization, you’ll be redirected to the organization’s dashboard page.

  2. To access the main organization page, click the "View <organization_name>" button located in the top-right corner of the dashboard.

  3. On the main organization page, click the "Settings" tab.

  4. Alternative Navigation: You can directly access the settings page using the following URL, replacing <organization_name> with the actual name of your organization: https://forge.fedoraproject.org/org/<organization_name>/settings

Configure Organization Details

  1. On the organization settings page, populate the following fields with the relevant information:

    1. Full Name: Enter the full, descriptive name of the organization.

    2. Description: Provide a brief overview or purpose of the organization.

    3. Website: (Optional) Enter the URL of the organization’s official website.

    4. Avatar: (Optional) Upload an avatar or logo for the organization.

Set Maximum Number of Repositories (CRITICAL STEP)

  1. Locate the field labeled "Maximum Number of Repositories."

  2. By default, this value is often set to -1. This effectively prevents any repositories from being created within the organization.

  3. Manually update this value from -1 to a positive integer. A value of 1000 is generally recommended to ensure sufficient capacity for Fedora organizations and Special Interest Groups (SIGs) without encountering limitations.

  4. [WARNING] ==== Failure to manually set this value will prevent anyone from creating repositories within this organization. ====

Assign Fedora Accounts Group as Organization Owners

  1. This step requires access to the system-wide administration settings.

  2. Navigate to the following URL: https://forge.fedoraproject.org/admin/auths/1

  3. Locate the field labeled "Map claimed groups to organization teams." This field contains a JSON snippet.

  4. Identify the Fedora Accounts group that will serve as the "Owners" team for the newly created organization. The "Owners" team is an immutable, automatically created team in Fedora Forge with specific permissions.

  5. Add or update the following key-value pair within the JSON snippet:

    "<Fedora_Accounts_Group>":{
    "<Fedora Forge_Organization>": ["Owners"]
}

    1. Replace <Fedora_Accounts_Group> with the actual name of the Fedora Accounts group (e.g., sysadmin-main).

    2. Replace <Fedora_Forge_Organization> with the exact name of the Fedora Forge organization you just created (e.g., Infrastructure). +.. Example: If the sysadmin-main group members are to be the Owners team of the Packages organization, the JSON snippet should include:

      "sysadmin-main": {
    "Packages": ["Owners"]
}

  6. Save the changes to the system-wide administration settings.

Verification

  • Confirm that the organization details are correctly displayed on the organization’s main page.

  • Attempt to create a new repository within the organization to verify that the "Maximum Number of Repositories" setting is correctly applied.

  • Verify that members of the designated Fedora Accounts group have "Owner" permissions within the new organization by attempting to perform owner-level actions.

Want to help? Learn how to contribute to Fedora Docs ›