How to Create a New Team 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 team within an existing organization in the Fedora Forge instance, and how to assign appropriate permissions and map Fedora Accounts groups to it.

Scope

This SOP applies to Fedora Project contributors with administrator privileges on the Fedora Forge instance, or those with sufficient permissions within a specific organization to manage teams.

Prerequisites

  • Access to Organization: You must have the necessary permissions to manage teams within the target organization on Fedora Forge. This typically means being an administrator on Fedora Forge or an owner of the specific organization.

  • Existing Organization: The organization where the new team will be created must already exist.

  • Fedora Account Group: Identify the specific Fedora Accounts group whose members will be added to this new team.

Procedure

The team creation process involves five main steps: logging in and navigating to the organization, accessing team settings, initiating team creation, completing the team form, assigning Fedora Accounts groups, and optionally assigning repositories.

Log In and Navigate to the Organization

  1. Log in to the Fedora Forge instance with an account that has the required permissions.

  2. Navigate to the specific organization where you wish to create a new team. You can usually do this by clicking on your profile picture/icon in the top right, then selecting "Your Organizations," and then clicking on the desired organization. Alternatively, you can directly access it via its URL (e.g., https://forge.fedoraproject.org/org/<organization_name>;).

Access Organization Teams Settings

  1. Once on the organization’s main page, click on the "Teams" tab.

Initiate New Team Creation

  1. On the Teams page, click the "New Team" button.

Complete "New Team" Form

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

  2. Team Name: Enter a unique and descriptive name for the new team (e.g., Developers, Documentation, Triagers).

  3. Description (Optional): Provide a brief description of the team’s purpose or responsibilities.

  4. Permission Level: Select the appropriate permission level for the team. Common options include:

    1. Read: Members can only view repositories and issues.

    2. Write: Members can push to repositories, open/close issues, etc.

    3. Admin: Members have administrative control over repositories, including managing settings and collaborators.

    4. Owner: This level is generally reserved for the main "Owners" team of the organization and provides full administrative control over the organization itself. Choose this only if the team genuinely needs organizational ownership rights.

  5. Include all repositories: Check this box if you want this team to have the selected permission level on all current and future repositories within this organization. If unchecked, you will need to manually add repositories to the team later. If your organization contains private repositories, exercising caution with "Include all repositories" is crucial. Selecting this option will grant the chosen permission level to all private repositories within the organization as well. Ensure this aligns with your security requirements before proceeding.

  6. Click the "Create Team" button.

Assign Fedora Accounts Group to the Team

  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 whose members will be part of this new team.

  5. Add or update the following key-value pair within the JSON snippet to map the Fedora Accounts group to the new team within the specific organization:

    "<Fedora_Accounts_Group>":{
    "<Forgejo_Organization>":["<Team_Name>"]
}

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

    2. Replace <Forgejo_Organization> with the exact name of the Fedora Forge organization (e.g., Fedora-Cloud).

    3. Replace <Team_Name> with the exact name of the team you just created (e.g., Developers). +.. Example: If you want the sig-cloud-devs group members to be part of the Developers team within the Fedora-Cloud organization, the JSON snippet should include:

      "sig-cloud-devs": {
    "Fedora-Cloud": ["Developers"]
}

      If the Fedora Accounts group is already mapped to other teams or organizations, ensure you correctly update the existing entry without overwriting other mappings. For example, to add TeamA and TeamB to OrgX for my-fas-group, the entry would be: "my-fas-group": {"OrgX": ["TeamA", "TeamB"]}.

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

Assign Repositories to the Team (If "Include all repositories" was unchecked)

  1. If you did not check "Include all repositories" during team creation, you will need to manually assign repositories.

  2. From the team’s page, click the "Repositories" tab.

  3. Click the "Add Repository" button.

  4. Select the repositories you want to grant this team access to.

  5. Click "Add" for each chosen repository.

Verification

  • Confirm the new team appears in the "Teams" list for the organization.

  • Verify that members of the designated Fedora Accounts group are now correctly associated with the newly created team within Fedora Forge.

  • Test the team’s permissions by having a member of the mapped Fedora Accounts group attempt an action consistent with their assigned permission level (e.g., if "Write" permission, try pushing to a repository assigned to the team).

  • If repositories were assigned manually, ensure that the team has access to only the intended repositories.

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