t0xic0der/forge-documentation
1
0
Fork 0
forked from forge/documentation
Code Pull requests Activity

migrate documentation from wiki

Browse source 
This commit migrates five documents from the old Markdown-based wiki at
https://codeberg.org/fedora/fedoraforge_documentation/wiki to this
new AsciiDoc-based documentation.

The following documents were migrated:
- How to create an Organization Front Page
- How to Clone a Repository using HTTPS Authentication in Fedora Forge
- Creating a new Organization
- Creating a new Team
- Requesting a New Organization and/or Team
This commit is contained in:
Ryan Lerch 2025-09-12 15:00:20 +10:00
commit f7d1a16635
6 changed files with 693 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

7
modules/ROOT/nav.adoc
View file

@ -1,4 +1,7 @@
* xref:user_docs.adoc[User Documentation]
// ** xref:pizza-oven.adoc[Pizza Oven]
// ** xref:pizza-dough.adoc[Pizza Dough]
** xref:create_org_profile_page.adoc[How to create an Organization Front Page]
** xref:requesting_new_org_or_team.adoc[Requesting a New Organization and/or Team]
** xref:using_http_auth.adoc[How to Clone a Repo with HTTPS]
* xref:admin_docs.adoc[Admin Documentation]
** xref:creating_a_new_org.adoc[Creating a new Organization]
** xref:creating_a_new_team.adoc[Creating a new Team]

88
modules/ROOT/pages/create_org_profile_page.adoc Normal file
View file

@ -0,0 +1,88 @@
= Create a Custom Front Page for an Organization using a `.profile` Repository on Fedora Forge
== Purpose
This guide demonstrates how to leverage the special `.profile` repository feature in https://forge.fedoraproject.org[Fedora Forge] to display a custom Markdown-based front page directly on your organization's main profile page. This allows for a richer and more informative landing experience for your organization.
== Scope
This guide applies to all Fedora Project contributors who are administrators or maintainers of an organization on Fedora Forge.
== Prerequisites
* An existing organization on Fedora Forge.
* Push access (e.g., maintainer, owner) to the organization on Fedora Forge.
* Basic familiarity with Git and Markdown.
== Procedure
=== 1. Log In and Navigate to Your Organization
* Log in to your Fedora Forge account.
* Navigate to the specific organization for which you want to create a custom front page. You can do this by clicking your profile icon (top-right), selecting "Your Organizations," and then clicking on the desired organization.
=== 2. Create the `.profile` Repository
* Once on your organization's main page, locate and click the *"New Repository"* button (usually near the top right, or within the "Repositories" tab).
* In the "New Repository" form:
** *Owner:* Ensure your organization's name is selected.
** *Repository Name:* *Crucially, name this repository exactly `.profile`* (with the leading dot). This specific name is recognized by Fedora Forge (Gitea/Forgejo) to display its README content as the organization's front page.
** *Description (Optional):* Add a brief description, e.g., "Custom front page for the organization."
** *Visibility:* It is highly recommended to set this to *"Public"* if you want everyone to see your custom front page. If it's private, only organization members with access will see it.
** *Initialize this repository with a README:* *Check this box.* This will create an initial `README.md` file, which you will customize.
* Click the *"Create Repository"* button.
=== 3. Clone the `.profile` Repository
Clone the `.profile` repository using the following command (replace `your-org` with your organization's name):
[source,bash]
----
git clone https://forge.fedoraproject.org/your-org/.profile.git
----
Replace `your-org` with the actual name of your organization on Fedora Forge. For example, if your organization is named `fedora-docs`, the command would be:
`git clone https://forge.fedoraproject.org/fedora-docs/.profile.git`
=== 4. Customize the `README.md` (Your Front Page Content)
*Example `README.md` content:*
[,markdown]
----
# Welcome to the [Your Organization Name]!
We are the official Fedora **[Your Organization Name]** organization on Fedora Forge.
---
## Our Mission
[Briefly describe your organization's mission or purpose.]
## Key Projects
* [Project A](https://forge.fedoraproject.org/org/your-org/repo-a) - Description of Project A.
* [Project B](https://forge.fedoraproject.org/org/your-org/repo-b) - Description of Project B.
## Get Involved!
* **Discussions:** Join our [Mailing List](https://lists.fedoraproject.org/archives/list/your-list@lists.fedoraproject.org/)
* **Chat:** Find us on IRC/Matrix: `#your-channel`
* **Website:** Visit our [Official Website](https://your-org-website.org)
----
=== 5. Commit and Push Your Changes
Inside your local `.profile` repository directory, run the following commands to stage, commit, and push your `README.md` file:
[source,bash]
----
# Add the file to the staging area
git add README.md
# Commit the changes
git commit -m "Add custom organization profile"
# Push the commit to the remote repository
git push origin main
----
Once the push is complete, visit your organization's page on Fedora Forge. The content of your `README.md` will now be displayed as the main page.

116
modules/ROOT/pages/creating_a_new_org.adoc Normal file
View file

@ -0,0 +1,116 @@
== How to Create a New Organization in Fedora Forge
== 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
. *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
page.
.. 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
organization.
.. Click the *"Create Organization"* button.
. *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>"*
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
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.
. *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
`1000` is generally recommended to ensure sufficient capacity for Fedora
organizations and Special Interest Groups (SIGs) without encountering
limitations.
.. [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
field contains a JSON snippet.
.. *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:
+
[source,json]
----
"<Fedora_Accounts_Group>":{
"<Fedora Forge_Organization>": ["Owners"]
}
----
+
... 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
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:
+
[source,json]
----
"sysadmin-main": {
"Packages": ["Owners"]
}
----
+
.. 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.

127
modules/ROOT/pages/creating_a_new_team.adoc Normal file
View file

@ -0,0 +1,127 @@
== 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
. *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.
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.
. *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
or responsibilities.
.. *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
managing settings and collaborators.
*** *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
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.
.. 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
field contains a JSON snippet.
.. *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
the Fedora Accounts group to the new team within the specific organization:
+
[source,json]
----
"<Fedora_Accounts_Group>":{
"<Forgejo_Organization>":["<Team_Name>"]
}
----
+
... 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
organization (e.g., `Fedora-Cloud`).
... 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:
+
[source,json]
----
"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"]}`.
.. 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
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.
== 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.

217
modules/ROOT/pages/requesting_new_org_or_team.adoc Normal file
View file

@ -0,0 +1,217 @@
= Requesting a New Organization and/or Team in Fedora Forge
== Purpose
This document outlines the standardized process for Fedora Project contributors
to formally request the creation of a new organization within Fedora Forge, or
the addition of new teams to an existing organization. By following this
procedure, users can ensure their requests are complete, contain all necessary
configuration details, and can be processed efficiently by the `fedora-infra`
team.
== Scope
This Standard Operating Procedure (SOP) applies to all Fedora Project
contributors who require a new organization for their project, Special Interest
Group (SIG), or working group, or who need to establish new teams within an
existing Fedora Forge organization to manage permissions and user access.
== Prerequisites
Before submitting a request, please ensure you have the following information
ready:
* **Clear Justification:** A clear understanding of why a new organization or
team is needed.
* **Existing Fedora Accounts Group(s):** Identify the specific
Fedora Accounts group(s) whose members will be mapped to the `Owners` team of a new
organization, and/or to any new teams you are requesting. Ensure these Fedora Accounts
groups exist and contain the correct members.
* **All Required Details:** Gather all the specific information outlined in
the "Procedure" section below for your request type (new organization, new
team, or both).
== Procedure: Filing a Request Ticket
All requests for new organizations and/or teams in Fedora Forge must be
submitted by filing a ticket in the **`fedora-infra` ticket tracker**.
When creating your ticket, provide all the relevant details as specified below.
The more complete and accurate your request, the faster it can be processed.
=== 1. New Organization Request Details
If you are requesting a *new organization*, include the following information in
your ticket:
==== Desired Organization Name (Short Name)
This will be the short URL component for your organization (e.g., `forge.fedoraproject.org/org/myawesomesig`). It should be unique, lowercase, and typically hyphen-separated.
====
`myawesomesig`
====
==== Full Name of Organization
This is the human-readable, full name of your organization that will appear in the UI.
====
`My Awesome Special Interest Group`
====
==== Description of Organization's Purpose
A brief description of your organization's purpose or mission.
====
`This organization will host repositories and manage collaboration
for the My Awesome SIG, focusing on [briefly describe focus].`
====
==== Website URL *(Optional)*
An optional URL to a website for your organization.
====
`https://fedoraproject.org/wiki/My_Awesome_SIG`
====
==== Avatar/Logo *(Optional)*
An optional link to an image file for your organization's avatar/logo. You can also state that you will provide one later.
====
`https://fedoraproject.org/wiki/My_Awesome_SIG/logo.png`
====
==== Fedora Accounts Group for Organization Owners
Specify the existing Fedora Accounts group whose members will automatically become the `Owners` of this new organization. The "Owners" team is a special, immutable team with full administrative control over the organization.
====
`forge-myawesomesig-owners`
====
[IMPORTANT]
====
This Fedora Accounts group must already exist.
====
=== 2. New Team Request Details (For New or Existing Organizations)
If you are requesting *new teams* (either within a new organization you're
requesting, or an existing one), include the following information for *each*
team:
* **Target Organization Name:**
====
`myawesomesig` (if part of a new org request) or
`existing-fedora-org` (if adding to an existing org).
====
* **Team Name:**
====
`members`
====
* **Description of Team's Purpose (Optional):**
====
`Team for core developers working on the main project
repositories.`
====
* **Desired Permission Level in Forgejo:**
====
Choose one of: `Read`, `Write`, `Admin`.
====
[NOTE]
====
`Owner` is reserved for the organization's primary owners team.
====
* **Fedora Accounts Group to Map to Team:**
====
**This is critical.** Specify the existing Fedora Accounts group
whose members will automatically be added to this new team in Forgejo.
`forge-myawesomesig-members` (ensure this Fedora Accounts group already exists).
====
* **Include all repositories? (Yes/No):**
====
Indicate if this team should have the specified permission level on *all*
current and future repositories within the organization.
====
[WARNING]
====
If your organization contains **private repositories**, selecting
"Yes" will grant the chosen permission level to **all private repositories**
within the organization as well. Ensure this aligns with your security
requirements.
If "No," you will need to manually request repository assignments later (or
specify them in the ticket if known).
====
== Example Request Ticket Content
You can copy and paste the following template into your `fedora-infra` ticket,
filling in the bracketed information.
[source,text]
----
Subject: [Forgejo] New Organization and Teams Request: My Awesome SIG
----
Body:
[source,text]
----
Hello Fedora Infra Team,
I would like to request the creation of a new organization and associated
teams in Fedora Forge.
1. New Organization Details:
Desired Organization Name (Short Name): myawesomesig
Full Name of Organization: My Awesome Special Interest Group
Description of Organization's Purpose: This organization will host repositories
and manage collaboration for the My Awesome SIG, focusing on developing and
maintaining [specific software/project].
Website URL (Optional): https://fedoraproject.org/wiki/My_Awesome_SIG
Avatar/Logo (Optional): (Will provide a link to an image file later / No avatar
at this time)
Fedora Accounts Group for Organization Owners: forge-myawesomesig-owners
2. New Team Details (within 'myawesomesig' organization):
Team 1:
Target Organization Name: myawesomesig
Team Name: members
Description of Team's Purpose: Core team responsible for code contributions and
repository management.
Desired Permission Level in Forgejo: Write
Fedora Accounts Group to Map to Team: forge-myawesomesig-members
Include all repositories?: Yes (This team should have write access to all
current and future repositories in 'myawesomesig'.)
Please let me know if any further information is required.
Thank you,
[Your Name/Fedora Account]
----

140
modules/ROOT/pages/using_http_auth.adoc Normal file
View file

@ -0,0 +1,140 @@
= How to Clone a Repository using HTTPS Authentication in Fedora Forge
== Purpose
This document provides a step-by-step guide on how to clone a repository from
the Fedora Forge instance using HTTPS authentication. This method is
recommended as SSH cloning is currently not supported. It will also cover how
to use Access Tokens for authentication, which is the secure and recommended
practice for automated or repeated access.
== Scope
This guide is intended for all Fedora Project contributors and users who need
to clone repositories from Fedora Forge to their local machine for
development, contribution, or viewing.
== Prerequisites
Before you begin, ensure you have the following:
* *Git Installed:* You must have Git installed on your local machine.
* *Fedora Forge Account:* An active user account on the Fedora Forge instance,
authenticated via Fedora Accounts (OpenIDC).
* *Access Token:* For secure and convenient authentication, it is highly
recommended to generate and use a Access Token instead of relying on your
Fedora Account credentials directly for Git operations. See the section
below on "Generating an Access Token."
== Procedure: Cloning a Repository via HTTPS
Follow these steps to clone a repository using HTTPS:
=== 1. Locate the Repository's HTTPS URL
. Navigate to the repository you wish to clone on the Fedora Forge instance
(e.g., `https://forge.fedoraproject.org/<org>/<repo_name>`).
. On the repository's main page, locate the blue *"HTTPS"* button (or similar
clone button).
. Copy the provided HTTPS URL to your clipboard. It will typically look
something like: `https://forge.fedoraproject.org/<org>/<repo_name>.git`
=== 2. Clone the Repository Using Git
. Open your terminal or command prompt.
. Navigate to the directory where you want to clone the repository.
. Use the `git clone` command followed by the copied HTTPS URL:
+
----
git clone https://forge.fedoraproject.org/<org>/<repo_name>.git
----
+
*Replace `https://forge.fedoraproject.org/<org>/<repo_name>.git` with the
actual URL you copied.*
. When you try to push changes back to this repository, you will prompted for a
username and password:
+
* *Username:* Enter your Fedora Forge username (the same one you use to log in
to the web interface).
+
* *Password:* *Instead of your Fedora Account password (which is not used for
Git authentication), enter your Access Token.*
+
----
Username for 'https://forge.fedoraproject.org': your_username
Password for 'https://your_username@forge.fedoraproject.org': <paste_your_access_token_here>
----
+
[NOTE]
====
When you type or paste your Access Token, it will likely not be
displayed on the screen for security reasons.
====
. To avoid entering your Access Token every time you interact with the
repository, you can use a Git credential helper.
+
----
git config --global credential.helper store
----
+
The first time you clone or push, you'll be prompted for your username and
Access Token. Git will then store it in a plain-text file
(`~/.git-credentials`)
== Generating a Access Token in Fedora Forge
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.
. *Navigate to User Settings:*
.. 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"*.
. *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
token. For general cloning and pushing, you will typically just need: Read
and Write on Repository.
.. 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.
== Troubleshooting and Tips
* *"Authentication failed" error:*
** Double-check your username.
** Ensure you are using the correct Access Token, not your Fedora Account
password.
** Verify the Access Token has the necessary `read:repository` and
`write:repository` permissions.
** If you've recently changed your Access Token, ensure your credential helper
(if used) has been updated. You might need to clear cached credentials.
* *"Repository not found" error:*
** Verify the repository URL is correct and that you have access to the
repository.
* *SSH Not Supported:* Remember that Fedora Forge currently does *not* support
cloning via SSH. Always use the HTTPS URL.
* *Token Security:* Keep your Access Tokens secure. If you suspect a token has
been compromised, revoke it immediately from your Fedora Forge
"Applications" settings.