forked from forge/documentation
Standardize documentation formatting and structure
- Fix heading levels across all documents (level 1 titles, level 2 sections) - Convert procedure ordered lists to headings for better navigation - Add procedure summaries to admin documentation - Simplify ordered list formatting by removing unnecessary * formatting - Update navigation to include new Pagure migration sub-documents This improves consistency and usability across all Fedora Forge documentation.
This commit is contained in:
parent
dcc76b6749
commit
c51d535130
5 changed files with 107 additions and 102 deletions
|
|
@ -7,6 +7,8 @@
|
|||
** xref:creating_a_new_org.adoc[Creating a new Organization]
|
||||
** xref:creating_a_new_team.adoc[Creating a new Team]
|
||||
** xref:migration/pagure.adoc[Migrating from Pagure]
|
||||
*** xref:migration/pagure_repository.adoc[Migrate Repository from Pagure]
|
||||
*** xref:migration/pagure_private_tickets.adoc[Migrate Private Tickets from Pagure]
|
||||
** xref:migration/github.adoc[Migrating from GitHub]
|
||||
** xref:migration/gitlab.adoc[Migration from GitLab]
|
||||
* Known Issues
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
== How to Create a New Organization in Fedora Forge
|
||||
= How to Create a New Organization in Fedora Forge
|
||||
|
||||
== Purpose
|
||||
|
||||
|
|
@ -21,66 +21,75 @@ privileges on the Fedora Forge.
|
|||
|
||||
== Procedure
|
||||
|
||||
. *Log In as Administrator:*
|
||||
.. Navigate to the Fedora Forge login page.
|
||||
.. Log in using a user account that possesses administrator privileges.
|
||||
.. *Verification:* Upon successful login, observe the top-right corner of the
|
||||
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
|
||||
|
||||
. Navigate to the Fedora Forge login page.
|
||||
. Log in using a user account that possesses administrator privileges.
|
||||
. *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:*
|
||||
.. Click on the *"+" icon* located in the top-right corner of the Fedora Forge
|
||||
=== Initiate New Organization Creation
|
||||
|
||||
. Click on the *"+" icon* located in the top-right corner of the Fedora Forge
|
||||
page.
|
||||
.. From the dropdown menu, select *"New Organization."*
|
||||
. From the dropdown menu, select *"New Organization."*
|
||||
|
||||
. *Complete "New Organization" Form:*
|
||||
.. The "New Organization" form will be displayed.
|
||||
.. In the *"Organization Name"* field, enter the desired name for the new
|
||||
=== Complete "New Organization" Form
|
||||
|
||||
. The "New Organization" form will be displayed.
|
||||
. In the *"Organization Name"* field, enter the desired name for the new
|
||||
organization.
|
||||
.. Click the *"Create Organization"* button.
|
||||
. Click the *"Create Organization"* button.
|
||||
|
||||
. *Navigate to Organization Settings:*
|
||||
.. Upon creating the organization, you'll be redirected to the organization's
|
||||
=== Navigate to Organization Settings
|
||||
|
||||
. Upon creating the organization, you'll be redirected to the organization's
|
||||
dashboard page.
|
||||
.. To access the main organization page, click the *"View <organization_name>"*
|
||||
. To access the main organization page, click the *"View <organization_name>"*
|
||||
button located in the top-right corner of the dashboard.
|
||||
.. On the main organization page, click the *"Settings"* tab.
|
||||
.. *Alternative Navigation:* You can directly access the settings page using the
|
||||
. On the main organization page, click the *"Settings"* tab.
|
||||
. *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:*
|
||||
.. On the organization settings page, populate the following fields with the
|
||||
relevant information:
|
||||
*** *Full Name:* Enter the full, descriptive name of the organization.
|
||||
*** *Description:* Provide a brief overview or purpose of the organization.
|
||||
*** *Website:* (Optional) Enter the URL of the organization's official website.
|
||||
*** *Avatar:* (Optional) Upload an avatar or logo for the organization.
|
||||
=== Configure Organization Details
|
||||
|
||||
. *Set Maximum Number of Repositories (CRITICAL STEP):*
|
||||
.. Locate the field labeled *"Maximum Number of Repositories."*
|
||||
.. By default, this value is often set to `-1`. This effectively prevents any
|
||||
. On the organization settings page, populate the following fields with the
|
||||
relevant information:
|
||||
.. *Full Name:* Enter the full, descriptive name of the organization.
|
||||
.. *Description:* Provide a brief overview or purpose of the organization.
|
||||
.. *Website:* (Optional) Enter the URL of the organization's official website.
|
||||
.. *Avatar:* (Optional) Upload an avatar or logo for the organization.
|
||||
|
||||
=== Set Maximum Number of Repositories (CRITICAL STEP)
|
||||
|
||||
. Locate the field labeled *"Maximum Number of Repositories."*
|
||||
. By default, this value is often set to `-1`. This effectively prevents any
|
||||
repositories from being created within the organization.
|
||||
.. *Manually update this value from `-1` to a positive integer.* A value of
|
||||
. *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.
|
||||
.. [WARNING]
|
||||
. [WARNING]
|
||||
====
|
||||
Failure to manually set this value will prevent anyone from creating
|
||||
repositories within this organization.
|
||||
====
|
||||
|
||||
. *Assign Fedora Accounts Group as Organization Owners:*
|
||||
.. This step requires access to the system-wide administration settings.
|
||||
.. Navigate to the following URL: `https://forge.fedoraproject.org/admin/auths/1`
|
||||
.. Locate the field labeled *"Map claimed groups to organization teams."* This
|
||||
=== Assign Fedora Accounts Group as Organization Owners
|
||||
|
||||
. This step requires access to the system-wide administration settings.
|
||||
. Navigate to the following URL: `https://forge.fedoraproject.org/admin/auths/1`
|
||||
. Locate the field labeled *"Map claimed groups to organization teams."* This
|
||||
field contains a JSON snippet.
|
||||
.. *Identify the Fedora Accounts group* that will serve as the "Owners" team
|
||||
. *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.
|
||||
.. *Add or update the following key-value pair* within the JSON snippet:
|
||||
. *Add or update the following key-value pair* within the JSON snippet:
|
||||
+
|
||||
[source,json]
|
||||
----
|
||||
|
|
@ -89,9 +98,9 @@ privileges on the Fedora Forge.
|
|||
}
|
||||
----
|
||||
+
|
||||
... Replace `<Fedora_Accounts_Group>` with the actual name of the Fedora
|
||||
.. Replace `<Fedora_Accounts_Group>` with the actual name of the Fedora
|
||||
Accounts group (e.g., `sysadmin-main`).
|
||||
... Replace `<Fedora_Forge_Organization>` with the exact name of the Fedora
|
||||
.. 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:
|
||||
|
|
@ -103,7 +112,7 @@ privileges on the Fedora Forge.
|
|||
}
|
||||
----
|
||||
+
|
||||
.. Save the changes to the system-wide administration settings.
|
||||
. Save the changes to the system-wide administration settings.
|
||||
|
||||
== Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
= How to Create a New Team in Fedora Forge
|
||||
|
||||
== Purpose
|
||||
|
||||
This document outlines the steps required to create a new team within
|
||||
|
|
@ -23,38 +25,44 @@ within a specific organization to manage teams.
|
|||
|
||||
== Procedure
|
||||
|
||||
. *Log In and Navigate to the Organization:*
|
||||
.. Log in to the Fedora Forge instance with an account that has the required
|
||||
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
|
||||
|
||||
. Log in to the Fedora Forge instance with an account that has the required
|
||||
permissions.
|
||||
.. Navigate to the specific organization where you wish to create a new team.
|
||||
. 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:*
|
||||
.. Once on the organization's main page, click on the *"Teams"* tab.
|
||||
=== Access Organization Teams Settings
|
||||
|
||||
. *Initiate New Team Creation:*
|
||||
.. On the Teams page, click the *"New Team"* button.
|
||||
. Once on the organization's main page, click on the *"Teams"* tab.
|
||||
|
||||
. *Complete "New Team" Form:*
|
||||
.. The "New Team" form will be displayed.
|
||||
.. *Team Name:* Enter a unique and descriptive name for the new team (e.g.,
|
||||
=== Initiate New Team Creation
|
||||
|
||||
. On the Teams page, click the *"New Team"* button.
|
||||
|
||||
=== Complete "New Team" Form
|
||||
|
||||
. The "New Team" form will be displayed.
|
||||
. *Team Name:* Enter a unique and descriptive name for the new team (e.g.,
|
||||
`Developers`, `Documentation`, `Triagers`).
|
||||
.. *Description (Optional):* Provide a brief description of the team's purpose
|
||||
. *Description (Optional):* Provide a brief description of the team's purpose
|
||||
or responsibilities.
|
||||
.. *Permission Level:* Select the appropriate permission level for the team.
|
||||
. *Permission Level:* Select the appropriate permission level for the team.
|
||||
Common options include:
|
||||
*** *Read:* Members can only view repositories and issues.
|
||||
*** *Write:* Members can push to repositories, open/close issues, etc.
|
||||
*** *Admin:* Members have administrative control over repositories, including
|
||||
.. *Read:* Members can only view repositories and issues.
|
||||
.. *Write:* Members can push to repositories, open/close issues, etc.
|
||||
.. *Admin:* Members have administrative control over repositories, including
|
||||
managing settings and collaborators.
|
||||
*** *Owner:* This level is generally reserved for the main "Owners" team of the
|
||||
.. *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.
|
||||
.. *Include all repositories:* Check this box if you want this team to have the
|
||||
. *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.
|
||||
|
|
@ -64,16 +72,17 @@ within a specific organization to manage teams.
|
|||
organization as well. Ensure this aligns with your security requirements
|
||||
before proceeding.
|
||||
|
||||
.. Click the *"Create Team"* button.
|
||||
. Click the *"Create Team"* button.
|
||||
|
||||
. *Assign Fedora Accounts Group to the Team:*
|
||||
.. This step requires access to the system-wide administration settings.
|
||||
.. Navigate to the following URL: `https://forge.fedoraproject.org/admin/auths/1`
|
||||
.. Locate the field labeled *"Map claimed groups to organization teams."* This
|
||||
=== Assign Fedora Accounts Group to the Team
|
||||
|
||||
. This step requires access to the system-wide administration settings.
|
||||
. Navigate to the following URL: `https://forge.fedoraproject.org/admin/auths/1`
|
||||
. Locate the field labeled *"Map claimed groups to organization teams."* This
|
||||
field contains a JSON snippet.
|
||||
.. *Identify the Fedora Accounts group* whose members will be part of this new
|
||||
. *Identify the Fedora Accounts group* whose members will be part of this new
|
||||
team.
|
||||
.. *Add or update the following key-value pair* within the JSON snippet to map
|
||||
. *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:
|
||||
+
|
||||
[source,json]
|
||||
|
|
@ -83,11 +92,11 @@ within a specific organization to manage teams.
|
|||
}
|
||||
----
|
||||
+
|
||||
... Replace `<Fedora_Accounts_Group>` with the actual name of the Fedora
|
||||
.. Replace `<Fedora_Accounts_Group>` with the actual name of the Fedora
|
||||
Accounts group (e.g., `sig-cloud-devs`).
|
||||
... Replace `<Forgejo_Organization>` with the exact name of the Fedora Forge
|
||||
.. Replace `<Forgejo_Organization>` with the exact name of the Fedora Forge
|
||||
organization (e.g., `Fedora-Cloud`).
|
||||
... Replace `<Team_Name>` with the exact name of the team you just created
|
||||
.. 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
|
||||
|
|
@ -104,16 +113,16 @@ 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"]}`.
|
||||
.. Save the changes to the system-wide administration settings.
|
||||
. Save the changes to the system-wide administration settings.
|
||||
|
||||
. *Assign Repositories to the Team (If "Include all repositories" was
|
||||
unchecked):*
|
||||
.. If you did not check "Include all repositories" during team creation, you
|
||||
=== Assign Repositories to the Team (If "Include all repositories" was unchecked)
|
||||
|
||||
. If you did not check "Include all repositories" during team creation, you
|
||||
will need to manually assign repositories.
|
||||
.. From the team's page, click the *"Repositories"* tab.
|
||||
.. Click the *"Add Repository"* button.
|
||||
.. Select the repositories you want to grant this team access to.
|
||||
.. Click "Add" for each chosen repository.
|
||||
. From the team's page, click the *"Repositories"* tab.
|
||||
. Click the *"Add Repository"* button.
|
||||
. Select the repositories you want to grant this team access to.
|
||||
. Click "Add" for each chosen repository.
|
||||
|
||||
== Verification
|
||||
|
||||
|
|
|
|||
|
|
@ -29,20 +29,11 @@ This issue is specific to the Fedora Forge implementation of the Pagure migrator
|
|||
|
||||
An administrator can manually fix this issue for a single user by performing the following steps in the Forgejo UI:
|
||||
|
||||
. *Log in as Administrator:*
|
||||
.. Log in as a Fedora Forge administrator to Fedora Forge.
|
||||
|
||||
. *Navigate to Admin Panel:*
|
||||
.. Navigate to the Admin Panel.
|
||||
|
||||
. *Access User Management:*
|
||||
.. Go to the User Management section.
|
||||
|
||||
. *Locate and Edit User Account:*
|
||||
.. Find and click on the user's account to open their settings.
|
||||
|
||||
. *Update User Account:*
|
||||
.. Without making any changes, click the *"Update user account"* button to save changes.
|
||||
. Log in as a Fedora Forge administrator to Fedora Forge.
|
||||
. Navigate to the Admin Panel.
|
||||
. Go to the User Management section.
|
||||
. Find and click on the user's account to open their settings.
|
||||
. Without making any changes, click the *"Update user account"* button to save changes.
|
||||
|
||||
=== Automated Workaround (For Multiple Users)
|
||||
|
||||
|
|
|
|||
|
|
@ -95,27 +95,21 @@ Using a Access Token is the recommended way to authenticate with Git over
|
|||
HTTPS. *Remember, you will use your Access Token for Git authentication, not
|
||||
your Fedora Account password.*
|
||||
|
||||
. *Log in to Fedora Forge:* Go to `https://forge.fedoraproject.org/` and log
|
||||
in using your Fedora Account.
|
||||
. Go to `https://forge.fedoraproject.org/` and log in using your Fedora Account.
|
||||
|
||||
. *Navigate to User Settings:*
|
||||
.. Click on your *profile picture/icon* in the top-right corner.
|
||||
.. Select *"Settings"* from the dropdown menu.
|
||||
. Click on your *profile picture/icon* in the top-right corner.
|
||||
. Select *"Settings"* from the dropdown menu.
|
||||
|
||||
. *Go to Applications:* In the left-hand navigation sidebar, click on
|
||||
*"Applications"*.
|
||||
. In the left-hand navigation sidebar, click on *"Applications"*.
|
||||
|
||||
. *Generate New Token:*
|
||||
.. Under the "Access Tokens" section, click the *"Generate Token"* button.
|
||||
.. *Token Name:* Give your token a descriptive name (e.g., `my-laptop-git`).
|
||||
.. *Token Permissions:* Select the permissions you want to grant to this
|
||||
. Under the "Access Tokens" section, click the *"Generate Token"* button.
|
||||
. *Token Name:* Give your token a descriptive name (e.g., `my-laptop-git`).
|
||||
. *Token Permissions:* Select the permissions you want to grant to this
|
||||
token. For general cloning and pushing, you will typically just need: Read
|
||||
and Write on Repository.
|
||||
.. Click the *"Generate Token"* button.
|
||||
. Click the *"Generate Token"* button.
|
||||
|
||||
. *Copy Your Token:* Your new Access Token will be displayed. *Copy this token
|
||||
immediately and store it securely.* You will not be able to see it again
|
||||
once you leave this page. Treat it like a password.
|
||||
. Your new Access Token will be displayed. *Copy this token immediately and store it securely.* You will not be able to see it again once you leave this page. Treat it like a password.
|
||||
|
||||
== Troubleshooting and Tips
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue