Add forge runner admin documentation

Signed-off-by: Lenka Segura <lsegura@redhat.com>

.forgejo/workflows/docs.yml

@@ -0,0 +1,13 @@
+on:
+  pull_request:
+    types: [opened, synchronize]
+  workflow_dispatch:
+jobs:
+  test:
+    runs-on: podman
+    container:
+      image: registry.gitlab.com/fedora/docs/docs-website/docs-fp-o:latest
+    steps:
+      - run: microdnf -y install git tar
+      - uses: actions/checkout@v6
+      - run: antora --html-url-extension-style=indexify site.yml --log-failure-level=warn

README.md

@@ -5,7 +5,7 @@ The official Fedora Forge documentation is available at: https://docs.fedoraproj
 This repository contains the source documentation for Fedora Forge, the official collaboration platform for Fedora teams, SIGs, and subprojects. The documentation covers:
 
 - **User Documentation**: Guides for creating organization front pages, requesting new organizations and teams, and using HTTPS authentication.
-- **Admin Documentation**: Procedures for creating new organizations and teams.
+- **Admin Documentation**: Procedures for creating new organizations, teams, runners, OCI image build pipeline.
 - **Migration Guides**: Step-by-step instructions for migrating projects from Pagure.io to Fedora Forge, including restoring issue dependencies and assignments.
 - **Known Issues**: Workarounds for common problems encountered on Fedora Forge.
 

modules/ROOT/nav.adoc

@@ -5,10 +5,12 @@
  ** xref:organizations_and_teams_mapping.adoc[Organizations and Teams Mapping]
  ** xref:team_permissions_management.adoc[Team Membership Management with Fedora Accounts]
  ** xref:using_http_auth.adoc[How to Clone a Repo with HTTPS]
+ ** xref:pull_requests.adoc[How to use pull requests in Fedora Forge]
  ** xref:email_notifications.adoc[Email Notifications]
  ** xref:matrix_notifications.adoc[Matrix Notifications]
  ** xref:issue_pull_request_templates.adoc[Issue and Pull Request Templates]
  ** xref:webhook_to_fedora_messaging.adoc[Webhook to Fedora Messaging for Forgejo]
+ ** xref:webhook_openshift.adoc[Webhook for build trigger in Fedora OpenShift]
  ** 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]
@@ -19,5 +21,7 @@
  ** xref:creating_a_new_org.adoc[Creating a new Organization]
  ** xref:creating_a_new_team.adoc[Creating a new Team]
  ** xref:admin_email_sync_script.adoc[Email Sync Script for Migrated Users]
+ ** xref:oci_image_pipeline.adoc[OCI Image Build Pipeline]
+ ** xref:creating_a_new_runner.adoc[Forgejo Actions Runner Management]
 * Known Issues
  ** xref:known_issue_organization_projects.adoc[Adding Issues to Organization Projects Doesn't "Stick"]

modules/ROOT/pages/create_org_profile_page.adoc

@@ -1,10 +1,5 @@
 = Create a Custom Front Page for an Organization using a `.profile` Repository on Fedora Forge
 
-[WARNING]
-====
-**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 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.
 

modules/ROOT/pages/creating_a_new_org.adoc

@@ -1,14 +1,9 @@
 = How to Create a New Organization in Fedora Forge
 
-[WARNING]
-====
-**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
+organization within the https://forge.fedoraproject.org/[Fedora Forge], ensuring proper configuration for
 repository creation and team management.
 
 == Scope
@@ -30,7 +25,7 @@ The organization creation process involves six main steps: logging in as an admi
 
 === Log In as Administrator
 
-. Navigate to the Fedora Forge login page.
+. Navigate to the https://forge.fedoraproject.org/user/login[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

modules/ROOT/pages/creating_a_new_runner.adoc

@@ -0,0 +1,472 @@
+= Forgejo Actions Runner Management
+
+== Purpose
+
+This document is a Standard Operating Procedure for adding, removing, and
+managing Forgejo Actions runners on Fedora Forge.
+
+== Scope
+
+This SOP applies to Fedora Infrastructure team members who manage Forgejo
+Actions runners on https://forge.fedoraproject.org[forge.fedoraproject.org]
+and http://forge.stg.fedoraproject.org[forge.stg.fedoraproject.org].
+
+== Overview
+
+Forgejo Actions runners execute lightweight workflows on Fedora Forge. Runners are defined in the
+https://forge.fedoraproject.org/infra/ansible/src/branch/main/roles/openshift-apps/forgejo/runners[ansible repo],
+registered in the Forgejo application via its CLI, and run as podman
+containers on a KubeVirt VM (`forgejo-runnerhost-vm`) in the `forgejo`
+OpenShift namespace.
+
+NOTE: This document covers Fedora-specific runner management. For detailed
+runner configuration options, refer to the official
+https://forgejo.org/docs/latest/admin/actions/[Forgejo Actions documentation].
+
+=== Architecture
+
+....
+  Ansible repo                      Private repo (batcave01)
+  ============                      ========================
+  runners/<env>/<name>.yml              forgejo_runner_secrets:
+  (name, scope, labels, image)            <name>: "<40-char hex>"
+            \                                    /
+             \                                  /
+              v                                v
+        load-forgejo-runners.yaml  ──>  forgejo_runners[]
+                    |
+          ┌─────────┼──────────────────────────┐
+          v         v                          v
+    K8s Secret    Control host              Forgejo pod
+   forgejo-       forgejo-runners-          forgejo-cli
+   runner-config   vars.yaml               actions register
+          |                                    |
+          v                                    v
+    Runner host VM                     Runner appears in
+   (watcher syncs secret               Forgejo admin UI
+    to local file)                     with correct labels
+          |
+          v
+    ansible-role-forgejo-runner
+   (ansible-pull on boot, then
+    starts runner containers)
+....
+
+=== Key components
+
+[cols="1,2,3",options="header"]
+|===
+| Component | Location | Purpose
+
+| Runner definitions
+| `roles/openshift-apps/forgejo/runners/{production,staging}/`
+| Public config (name, scope, labels, image)
+
+| Runner secrets
+| `/srv/private/ansible/vars.yml` on batcave01
+| Registration secrets (40-char hex)
+
+| Forgejo playbook
+| `playbooks/openshift-apps/forgejo.yml`
+| Orchestrates everything
+
+| Runner host VM
+| KubeVirt VM `forgejo-runnerhost-vm` in `forgejo` namespace
+| Runs all runners as unprivileged systemd user services (rootless podman containers)
+
+| External runner role
+| https://codeberg.org/fedora/ansible-role-forgejo-runner[codeberg.org/fedora/ansible-role-forgejo-runner]
+| Configures runner daemons on the VM
+|===
+
+== Adding a new runner
+
+=== Step 1: Create the runner definition file
+
+Create a YAML file in `roles/openshift-apps/forgejo/runners/<env>/` where
+`<env>` is `production` or `staging`. The filename must match the `name`
+field.
+
+*Simple label example* (`runners/production/roadrunner-1.yml`):
+
+[source,yaml]
+----
+---
+name: roadrunner-1
+scope: roadrunner
+labels:
+  - meep-meep
+image: code.forgejo.org/forgejo/runner:12
+----
+
+*Custom image mapping example* (`runners/production/roadrunner-2.yml`):
+
+[source,yaml]
+----
+---
+name: roadrunner-2
+scope: roadrunner
+labels:
+  - "docker:docker://node:22-bookworm"
+  - "docker-slim:docker://node:22-alpine"
+image: code.forgejo.org/forgejo/runner:12
+----
+
+*With capacity* (optional, limits concurrent jobs):
+
+[source,yaml]
+----
+---
+name: roadrunner-3
+scope: roadrunner
+labels:
+  - meep-meep
+image: code.forgejo.org/forgejo/runner:12
+capacity: 4
+----
+
+==== Field reference
+
+[cols="1,1,4",options="header"]
+|===
+| Field | Required | Description
+
+| `name`
+| Yes
+| Unique runner name. Must match the filename (without `.yml`).
+
+| `scope`
+| Yes
+| Forgejo organization name for org-scoped runners, or `global` for instance-wide. On the production instance the standard is org-scoped runners.
+
+| `labels`
+| Yes
+| List of workflow `runs-on` labels. Quote values containing colons.
+
+| `image`
+| Yes
+| Runner container image (e.g., `code.forgejo.org/forgejo/runner:12`).
+
+| `capacity`
+| No
+| Maximum concurrent jobs for this runner.
+|===
+
+See also the
+https://code.forgejo.org/forgejo/runner/src/branch/main/internal/pkg/config/config.example.yaml[Forgejo Runner Configuration example]
+for details on label types and runner options.
+
+==== Label format
+
+Labels can be simple names or include an image mapping:
+
+* *Simple*: `podman`, `docker`, `fedora` — the runner uses its default container image.
+* *With image*: `"docker:docker://node:22-bookworm"` — the part before `:` is the label name (what workflows use in `runs-on`), the part after is the container image the runner uses for that label.
+
+During registration in the Forgejo application, only the label name (before
+`:`) is used. The full `label:image` mapping is passed to the runner daemon
+configuration.
+
+=== Step 2: Add the registration secret to private vars
+
+On batcave01, edit `/srv/private/ansible/vars.yml` and add the runner's
+secret to the appropriate dict.
+
+Generate a new secret:
+
+[source,bash]
+----
+openssl rand -hex 20
+----
+
+Add it to the private vars:
+
+[source,yaml]
+----
+# For production
+forgejo_runner_secrets:
+  roadrunner-1: "a1b2c3d4e5f6..."   # 40-char hex
+
+# For staging
+forgejo_stg_runner_secrets:
+  roadrunner-1: "f6e5d4c3b2a1..."
+----
+
+=== Step 3: Commit and deploy
+
+[source,bash]
+----
+# Commit the runner definition (public repo)
+cd /srv/web/infra/ansible
+git add roles/openshift-apps/forgejo/runners/<env>/<name>.yml
+git commit -m "forgejo: add <name> runner for <env>"
+git push
+
+# Run the playbook
+sudo rbac-playbook openshift-apps/forgejo.yml -l <limit>
+----
+
+Where `<limit>` is:
+
+* `staging` for staging runners
+* `production` for production runners
+
+=== What the playbook does automatically
+
+. *Loads runner definitions* — scans `runners/<env>/*.yml`, merges each with its secret from private vars.
+. *Renders runner config* — produces `forgejo-runners-vars.yaml` containing the Forgejo instance URL, full runner list (with secrets and `label:image` mappings), and Zabbix agent config.
+. *Updates K8s Secret* — deploys the rendered config as `forgejo-runner-config` Secret in the `forgejo` namespace.
+. *Registers runners in Forgejo* — execs `forgejo-cli actions register` inside the Forgejo application pod for each runner (idempotent with `--secret`). Label names are extracted (stripping `:image` suffixes).
+. *Watcher syncs to VM* — the watcher service on `forgejo-runnerhost-vm` detects the Secret update and writes the config to `/home/<user>/forgejo-runners-vars.yaml`.
+. *Runner daemon picks up config* — the `ansible-role-forgejo-runner` on the VM reads the updated config and starts/restarts runner containers.
+
+== Removing a runner
+
+=== Step 1: Delete the runner definition file
+
+[source,bash]
+----
+git rm roles/openshift-apps/forgejo/runners/<env>/<name>.yml
+git commit -m "forgejo: remove <name> runner from <env>"
+git push
+----
+
+=== Step 2: Run the playbook
+
+[source,bash]
+----
+sudo rbac-playbook openshift-apps/forgejo.yml -l <limit>
+----
+
+This updates the K8s Secret (the runner will no longer be in the config), and
+the watcher syncs the change to the VM. The runner daemon stops the removed
+runner's container.
+
+=== Step 3: Remove from the Forgejo application (manual)
+
+The playbook does not automatically deregister runners from Forgejo. Remove
+it via the Forgejo admin UI:
+
+. Go to *Site Administration > Actions > Runners*.
+. Find the runner by name.
+. Delete it.
+
+=== Step 4: Clean up the secret (optional)
+
+Remove the runner's secret from `/srv/private/ansible/vars.yml` on batcave01.
+
+== Modifying a runner
+
+To change labels, image, scope, or capacity:
+
+. Edit the runner definition file in `runners/<env>/<name>.yml`.
+. Commit and push.
+. Run the playbook: `sudo rbac-playbook openshift-apps/forgejo.yml -l <limit>`
+. If the watcher doesn't pick up the change, restart it on the VM (see Troubleshooting).
+
+NOTE: If you change a runner's labels, the `forgejo-cli actions register`
+command with the same `--secret` will update the existing registration.
+Workflows using the old label will stop matching; workflows using the new
+label will start matching.
+
+== Runner host VM operations
+
+=== Accessing the VM console
+
+[source,bash]
+----
+virtctl console forgejo-runnerhost-vm -n forgejo
+----
+
+=== Checking runner status on the VM
+
+[source,bash]
+----
+# Check if runner containers are running
+podman ps
+
+# Check the watcher service
+systemctl --user list-units | grep -iE 'watch|secret|sync|forgejo'
+
+# Check ansible-pull log (from initial boot)
+cat ~/ansible-pull.log
+
+# Check the synced config
+cat ~/forgejo-runners-vars.yaml
+----
+
+=== Restarting the VM
+
+[source,bash]
+----
+# Restart (preserves data volume, cloud-init does NOT re-run)
+virtctl restart forgejo-runnerhost-vm -n forgejo
+
+# Full rebuild (deletes data volume, cloud-init runs fresh)
+oc delete vm forgejo-runnerhost-vm -n forgejo
+# Then re-run the playbook to recreate
+sudo rbac-playbook openshift-apps/forgejo.yml -l <limit>
+----
+
+=== Re-running ansible-pull on the VM
+
+If you need to re-apply the external runner role without rebuilding the VM:
+
+[source,bash]
+----
+ansible-pull -U https://codeberg.org/fedora/ansible-role-forgejo-runner.git -C main \
+  playbooks/ansible-pull.yml >> ~/ansible-pull.log 2>&1
+----
+
+== Troubleshooting
+
+=== Runner not appearing in Forgejo UI
+
+. Check if the playbook ran the registration task successfully:
++
+[source,bash]
+----
+sudo rbac-playbook openshift-apps/forgejo.yml -l <limit> -v
+----
+. Verify the runner's secret matches between the definition and private vars.
+. Check if the Forgejo pod is running:
++
+[source,bash]
+----
+oc get pods -n forgejo -l app.kubernetes.io/name=forgejo
+----
+
+=== Runner registered but not picking up jobs
+
+. Check if the runner daemon is running on the VM:
++
+[source,bash]
+----
+virtctl console forgejo-runnerhost-vm -n forgejo
+podman ps
+----
+. Verify the config was synced to the VM:
++
+[source,bash]
+----
+cat ~/forgejo-runners-vars.yaml | grep -A5 <runner-name>
+----
+. Verify labels match between the runner definition, Forgejo UI, and the workflow `runs-on`.
+
+=== K8s Secret updated but VM config is stale
+
+The watcher service may have lost its watch connection. Restart it:
+
+[source,bash]
+----
+# On the VM
+systemctl --user restart forgejo-runner-config-watcher.service
+
+# Verify the file was updated
+cat ~/forgejo-runners-vars.yaml | grep -A5 <runner-name>
+----
+
+=== Cloud-init failures on VM boot
+
+Cloud-init only runs on first boot. Common issues:
+
+* *Home directory owned by root*: Fixed by `defer: true` on `write_files` and `chown -R` in `runcmd`.
+* *ansible-pull fails*: Check `~/ansible-pull.log` on the VM.
+* *Packages fail to install*: Check `/var/log/cloud-init-output.log` on the VM.
+
+=== Non-breaking space characters in runner secrets
+
+If runner definitions were copy-pasted from web pages, they may contain
+invisible `\xa0` (non-breaking space) characters. Detect with:
+
+[source,bash]
+----
+grep -rP '\xc2\xa0' /srv/private/ansible/vars.yml
+----
+
+Fix by retyping the affected lines or:
+
+[source,bash]
+----
+sed -i 's/\xc2\xa0/ /g' /srv/private/ansible/vars.yml
+----
+
+== Reference
+
+=== Playbook command
+
+[source,bash]
+----
+# Staging
+sudo rbac-playbook openshift-apps/forgejo.yml -l staging
+
+# Production
+sudo rbac-playbook openshift-apps/forgejo.yml -l production
+----
+
+=== File locations on batcave01
+
+[cols="2,3",options="header"]
+|===
+| Path | Purpose
+
+| `/srv/web/infra/ansible/roles/openshift-apps/forgejo/runners/`
+| Runner definitions
+
+| `/srv/private/ansible/vars.yml`
+| Runner secrets
+
+| `/srv/web/infra/ansible/playbooks/openshift-apps/forgejo.yml`
+| Playbook
+|===
+
+=== File locations on runner host VM
+
+[cols="2,3",options="header"]
+|===
+| Path | Purpose
+
+| `~/forgejo-runners-vars.yaml`
+| Synced runner config (from K8s Secret)
+
+| `~/ansible-pull.log`
+| ansible-pull output from boot
+
+| `/mnt/sa-token/`
+| Mounted SA token for K8s API access
+|===
+
+=== Kubernetes resources in `forgejo` namespace
+
+[cols="1,2,3",options="header"]
+|===
+| Resource | Name | Purpose
+
+| Secret
+| `forgejo-runner-config`
+| Runner config (synced to VM)
+
+| Secret
+| `forgejo-runner-vm-token`
+| SA token for VM K8s API access
+
+| ServiceAccount
+| `forgejo-runner-vm`
+| VM identity
+
+| Role
+| `forgejo-runner-config-reader`
+| Read secrets permission
+
+| RoleBinding
+| `forgejo-runner-config-reader`
+| Binds SA to Role
+
+| VirtualMachine
+| `forgejo-runnerhost-vm`
+| Runner host VM
+
+| Service
+| `forgejo-runnerhost`
+| Headless service for VM DNS
+|===

modules/ROOT/pages/creating_a_new_team.adoc

@@ -1,10 +1,5 @@
 = How to Create a New Team in Fedora Forge
 
-[WARNING]
-====
-**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

modules/ROOT/pages/email_notifications.adoc

@@ -1,10 +1,5 @@
 = Email Notifications in Fedora Forge
 
-[WARNING]
-====
-**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 provides guidance on how to enable and configure email notifications in Fedora Forge. Email notifications help you stay informed about activities in repositories and organizations you're interested in.

modules/ROOT/pages/fas_group_naming_standards.adoc

@@ -1,13 +1,8 @@
 = Fedora Accounts Groups, Forge Organizations, and Team Naming Standards
 
-[WARNING]
-====
-**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.
-====
-
 == Overview
 
-This document establishes the standard naming conventions for Fedora Accounts groups, Fedora Forge organizations, and team names used in Fedora Forge. Consistent naming helps administrators create appropriately named groups and organizations, and helps contributors understand what access different groups provide.
+This document establishes the standard naming conventions for https://accounts.fedoraproject.org/[Fedora Accounts] groups, https://forge.fedoraproject.org/[Fedora Forge] organizations, and team names used in Fedora Forge. Consistent naming helps administrators create appropriately named groups and organizations, and helps contributors understand what access different groups provide.
 
 == Standard Naming Convention
 

modules/ROOT/pages/index.adoc

@@ -2,12 +2,8 @@ include::partial$attributes.adoc[]
 
 = Fedora Forge: Your Home for Fedora Collaboration
 
-[WARNING]
-====
-**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.
-====
-
-Welcome to Fedora Forge, the official home for Fedora teams, SIGs, and
+Welcome to https://forge.fedoraproject.org/[Fedora Forge], the official
+home for Fedora teams, SIGs, and
 subprojects. Built on the open-source Forgejo platform, Fedora Forge is a
 dedicated space designed to streamline development and collaboration across the
 Fedora Project.

modules/ROOT/pages/matrix_notifications.adoc

@@ -2,11 +2,6 @@ include::partial$attributes.adoc[]
 
 = Setting Up Matrix Notifications for Your Repository
 
-[WARNING]
-====
-**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 provides a comprehensive guide for setting up automated Matrix notifications for your Fedora Forge repository using the custom nonbot webhook. This allows you to receive real-time notifications about repository activities directly in your Matrix chat rooms.

modules/ROOT/pages/migrating_issue_dependencies.adoc

@@ -2,11 +2,6 @@ include::partial$attributes.adoc[]
 
 = Migrating Issue Dependencies and Assignments from Pagure.io to Fedora Forge
 
-[WARNING]
-====
-**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 provides a comprehensive guide for using the `assign_and_depend.py` script to restore issue dependencies and assignments after migrating a project from Pagure.io to Fedora Forge. The built-in migrator does not handle this critical metadata, making this script an essential post-migration step.

modules/ROOT/pages/migration/github.adoc

@@ -1,10 +1,5 @@
 = How to Migrate Repository from GitHub
 
-[WARNING]
-====
-**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 migrate repositories from GitHub

modules/ROOT/pages/migration/gitlab.adoc

@@ -1,10 +1,5 @@
 = How to Migrate Repository from GitLab
 
-[WARNING]
-====
-**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 migrate repositories from GitLab

modules/ROOT/pages/migration/pagure.adoc

@@ -1,10 +1,5 @@
 = Migrating from Pagure
 
-[WARNING]
-====
-**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 provides an overview of migrating repositories from Pagure to Fedora Forge, with links to specific migration procedures based on your repository's content and requirements.

modules/ROOT/pages/migration/pagure_private_tickets.adoc

@@ -1,10 +1,5 @@
 = How to Migrate Private Tickets from Pagure to a New Private Repository
 
-[WARNING]
-====
-**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 migrate private/restricted issue tickets from a Pagure.io repository to a new private repository on Fedora Forge, ensuring the confidentiality of sensitive information while maintaining access control.

modules/ROOT/pages/migration/pagure_repository.adoc

@@ -1,12 +1,5 @@
 = How to Migrate Repository from Pagure
 
-[WARNING]
-====
-**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 migrate repositories from Pagure to Fedora Forge, ensuring proper transfer of repository contents, issue tickets, and pull requests to the new Forgejo-based platform.

modules/ROOT/pages/oci_image_pipeline.adoc

@@ -0,0 +1,198 @@
+= OCI Image Build Pipeline for Fedora Forge
+
+== Purpose
+
+This document describes the OCI image build pipeline for the Forge and Src
+Forgejo instances in Fedora Infrastructure. It covers the repository layout,
+branching strategy, Konflux integration, and tenant configuration used to
+produce container images.
+
+== Scope
+
+This document is intended for Fedora Infrastructure team members who maintain
+the Forgejo deployment, manage Konflux pipelines, or need to understand how
+OCI images are built and promoted through staging to production.
+
+== Repository overview
+
+The https://codeberg.org/fedora/oci-image-definitions[oci-image-definitions]
+repository contains the Dockerfiles used to build OCI images for Forgejo
+deployment in Fedora Infrastructure. Images are built automatically by the
+https://konflux-ci.fedoraproject.org/[Fedora Konflux instance] whenever
+changes are pushed to the repository.
+
+Two websites are built from this repo, each in staging and production
+variants, each for stable and rawhide Fedora:
+
+[cols="1,1,2",options="header"]
+|===
+| Website | Directory | Description
+
+| *forge*
+| `forgejo/`
+| Forge instance
+
+| *src*
+| `distgit/`
+| Dist-git instance
+|===
+
+Each website directory contains:
+
+....
+<website>/
+├── staging/
+│   ├── Dockerfile.staging_rawhide
+│   ├── Dockerfile.staging_stable
+│   └── VERSION
+└── production/
+    ├── Dockerfile.prod_rawhide
+    ├── Dockerfile.prod_stable
+    └── VERSION
+....
+
+This produces *8 images* total (2 websites x 2 environments x 2 Fedora versions).
+
+== Branching and release strategy
+
+This repository has 5 branches:
+
+[cols="1,3",options="header"]
+|===
+| Branch | Purpose
+
+| `main`
+| Regularly rebased on upstream Forgejo LTS releases with Fedora-specific commits cherry-picked on top
+
+| `forge-staging`
+| Forge staging image builds
+
+| `forge-production`
+| Forge production image builds
+
+| `src-staging`
+| Src staging image builds
+
+| `src-production`
+| Src production image builds
+|===
+
+We track only Forgejo *LTS releases* to ensure long-term stability and
+security support. Pushing to any of these branches (except `main`) triggers a Konflux
+image build and outputs the image to Quay. Only the image corresponding to
+the target branch is built. Images are tagged with a composite version:
+`{upstream forgejo version}-{fedora/forgejo last commit SHA}-{oci-image-definitions commit SHA}`.
+
+=== Deployment path
+
+Images must follow this deployment path:
+
+. *Build* — push to a staging branch to trigger a Konflux image build.
+. *Local testing* — pull the built staging image from Quay and verify it locally before deploying.
+. *Staging deployment* — deploy the verified image to the staging environment and test there.
+. *Production* — only after staging is validated, push to the production branch for the final build and deployment.
+
+== Tekton pipelines
+
+The `.tekton/` directory contains hand-crafted PipelineRun definitions for
+Pipelines-as-Code (PaC). Each image has a push and pull-request pipeline,
+triggered on relevant path changes.
+
+== Konflux tenant configuration
+
+This repo is onboarded to the `fedora-infra-tenant` namespace on the
+https://konflux-ci.fedoraproject.org/[kflux-fedora-01] Konflux cluster.
+The tenant configuration lives in the
+https://gitlab.com/fedora/infrastructure/konflux/tenants-config[tenants-config]
+GitLab repo at `clusters/kflux-fedora-01/tenants/fedora-infra-tenant/`.
+
+The tenant uses Kustomize-based
+https://konflux-ci.dev/docs/building/configuration-as-code/[Configuration-as-Code]
+with bases and overlays to define 4 Applications and 8 Components from a
+single shared component template:
+
+....
+fedora-infra-tenant/
+├── kustomization.yaml              # Top-level: ns, rbac, quota, applications
+├── ns.yaml                         # Namespace definition
+├── rbac.yaml                       # RBAC: admin users, viewer access
+└── applications/
+    ├── kustomization.yaml          # Aggregates forge + src
+    ├── base/
+    │   ├── component.yaml          # Shared component template (git URL,
+    │   │                           #   provider, pipeline — common to all 8)
+    │   └── kustomization.yaml
+    ├── forge/                      # Forge website application
+    │   ├── kustomization.yaml      # Aggregates staging + production
+    │   ├── base/
+    │   │   ├── application.yaml    # Base Application resource
+    │   │   ├── rawhide/            # Component overlay: sets name to forge-rawhide
+    │   │   └── stable/             # Component overlay: sets name to forge-stable
+    │   ├── staging/                # Environment overlay → Application: forge-staging
+    │   │   ├── application-patch.yaml
+    │   │   ├── component-patch.yaml
+    │   │   ├── rawhide-patch.yaml
+    │   │   └── stable-patch.yaml
+    │   └── production/             # Environment overlay → Application: forge-production
+    │       └── ...                 # (same patch structure as staging)
+    └── src/                        # Src website application (mirrors forge/)
+        └── ...                     # (same structure, using distgit/ paths)
+....
+
+=== Rendered resources
+
+[cols="1,1,1,1",options="header"]
+|===
+| Application | Component | Context | Dockerfile
+
+| `forge-staging`
+| `forge-rawhide-staging`
+| `forgejo/staging`
+| `Dockerfile.staging_rawhide`
+
+| `forge-staging`
+| `forge-stable-staging`
+| `forgejo/staging`
+| `Dockerfile.staging_stable`
+
+| `forge-production`
+| `forge-rawhide-production`
+| `forgejo/production`
+| `Dockerfile.prod_rawhide`
+
+| `forge-production`
+| `forge-stable-production`
+| `forgejo/production`
+| `Dockerfile.prod_stable`
+
+| `src-staging`
+| `src-rawhide-staging`
+| `distgit/staging`
+| `Dockerfile.staging_rawhide`
+
+| `src-staging`
+| `src-stable-staging`
+| `distgit/staging`
+| `Dockerfile.staging_stable`
+
+| `src-production`
+| `src-rawhide-production`
+| `distgit/production`
+| `Dockerfile.prod_rawhide`
+
+| `src-production`
+| `src-stable-production`
+| `distgit/production`
+| `Dockerfile.prod_stable`
+|===
+
+== References
+
+* https://konflux-ci.dev/docs/building/configuration-as-code/[Konflux CaC best practices]
+* https://konflux-ci.dev/docs/building/creating-forgejo/[Onboarding a Forgejo component]
+* https://gitlab.com/fedora/infrastructure/konflux/tenants-config[Fedora tenants-config repo]
+* https://konflux-ci.dev/architecture/ADR/0052-gitops-onboarding-redesign/[ADR 52: GitOps Onboarding Redesign]
+
+'''
+
+_This document was written with the assistance of Claude (Anthropic), May 2026._

modules/ROOT/pages/organizations_and_teams_mapping.adoc

@@ -1,10 +1,5 @@
 = Organizations and Teams Mapping for Fedora Forge
 
-[WARNING]
-====
-**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.
-====
-
 == Overview
 
 This document explains the relationship between Organizations and Teams in Fedora Forge, and how they map to concepts from Pagure.io. Understanding this mapping is crucial for teams migrating from Pagure.io to Fedora Forge.

modules/ROOT/pages/pull_requests.adoc

@@ -0,0 +1,65 @@
+= How to use pull requests in Fedora Forge
+
+== Overview
+Pull requests are used to review and discuss changes before they are added to the main project. They help teams collaborate, find mistakes, improve quality, and keep the project history clear and organized.
+
+This allows you to contribute changes from your fork of a project to the upstream project. To contribute a change to a project you first open a pull request with original project. The project maintainer then merges the pull request if they are satisfied with the changes you have proposed.
+
+== Open a Pull Request
+
+=== Forge to Forge pull request
+When you've pushed changes to your fork of a project you want to contribute to, you can open a pull request:
+
+. Go to the `Pull requests` tab in the repo you want to merge into. This page shows existing pull requests and is where you start a new one.
+. Click `New pull request`. If the button is not visible, check that you are in the correct repository and on the right branch.
+. Select the branch to merge into (usually something like `docs:main`) and the branch to pull from (your fork). Before continuing, make sure the source and target branches are the ones you actually want to compare.
+
+image::pull_request_tab.png[Pull requests tab]
+This is the main page of the repo you want to merge into.
+
+image::new_pull_request_button.png[New pull request button]
+In this tab you can see all open pull requests or you can go into closed tab and look for closed PRs.
+
+image::branch_comparing.png[Branch comparison]
+
+TIP: Always double-check before continuing to make sure you don't create a PR to or from the wrong branch.
+
+image::new_pull_request_button2.png[Create pull request button]
+
+image::title.png[Title and description]
+Use a clear title and description so reviewers understand the change. The title should briefly summarize the change, while the description can explain the details or mention anything a reviewer should know.
+
+TIP: Title and description will be populated the last commit message, so if it's just a small change you can just easily click `Create pull request`.
+
+=== Remote Git to Forge pull request
+You can create a pull request from another git hosting platform (e.g. GitHub, GitLab). This is a remote pull request.
+
+==== From the pull requests list
+. Go to the main project's (not your fork) pull requests list and press the `File Pull Request` button.
+. Select the `Remote pull-request` option from the dropdown menu.
+. Fill the New remote pull-request form (Title, Git repo address and Git branch) and create your remote pull-request.
+
+Congratulations! It is now up to the project maintainer to accept your changes by merging them.
+
+== Updating Your Pull Request
+It is likely that project maintainers will request changes to your proposed code by commenting on your pull request. Don't be discouraged! This is an opportunity to improve your contribution and for both reviewer and contributor to become better programmers/writers.
+
+Adding to your pull request is as simple as pushing new commits to the branch you used to create the pull request. These will automatically be displayed in the commit list for the pull request.
+
+== Rebasing
+You may encounter a situation where you want to include changes from the master branch that were made after you created your pull request. You can do this by https://git-scm.com/docs/git-rebase[rebase] your pull request branch and pushing it to your remote fork.
+
+To rebase your branch onto latest upstream changes, run:
+[source,bash]
+----
+git fetch upstream
+git rebase upstram/main
+----
+
+After resolving any conflicts, run:
+[source,bash]
+----
+git push --force-with-lease origin your-branch-name
+----
+
+NOTE: Use `--force-with-lease` instead of `--force`. It is safer because it will refuse to overwrite the remote branch if someone else has pushed changes to it in the meantime.

modules/ROOT/pages/requesting_new_org_or_team.adoc

@@ -1,10 +1,5 @@
 = Requesting a New Organization and/or Team in Fedora Forge
 
-[WARNING]
-====
-**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 standardized process for Fedora Project contributors
@@ -26,15 +21,23 @@ existing Fedora Forge organization to manage permissions and user access.
 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).
+* **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.
++
+[IMPORTANT]
+====
+This Fedora Accounts group must already exist when you open the ticket. 
+If it does not, ask Infra to create one first - see 
+link:https://docs.fedoraproject.org/en-US/infra/howtos/groups_in_fedora/[infra docs].
+Make sure to specify a group name that follows the xref:fas_group_naming_standards.adoc[naming standards], 
+and to set the group type to `tracking`.
+====
+* **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
 
@@ -95,7 +98,11 @@ Specify the existing Fedora Accounts group whose members will automatically beco
 
 [IMPORTANT]
 ====
-This Fedora Accounts group must already exist.
+This Fedora Accounts group must already exist when you open the ticket. 
+If it does not, ask Infra to create one first - see 
+link:https://docs.fedoraproject.org/en-US/infra/howtos/groups_in_fedora/[infra docs].
+Make sure to specify a group name that follows the xref:fas_group_naming_standards.adoc[naming standards], 
+and to set the group type to `tracking`.
 ====
 
 === 2. New Team Request Details (For New or Existing Organizations)
@@ -141,7 +148,16 @@ Choose one of: `Read`, `Write`, `Admin`.
 **This is critical.** Specify the existing Fedora Accounts group
 whose members will automatically be added to this new team in Forgejo.
 
-`forge-infra-members` (ensure this Fedora Accounts group already exists).
+`forge-infra-members`
+====
+
+[IMPORTANT]
+====
+This Fedora Accounts group must already exist when you open the ticket. 
+If it does not, ask Infra to create one first - see 
+link:https://docs.fedoraproject.org/en-US/infra/howtos/groups_in_fedora/[infra docs].
+Make sure to specify a group name that follows the xref:fas_group_naming_standards.adoc[naming standards], 
+and to set the group type to `tracking`.
 ====
 
 *   **Include all repositories? (Yes/No):**
@@ -220,4 +236,4 @@ Please let me know if any further information is required.
 Thank you,
 
 [Your Name/Fedora Account]
-----
+----

modules/ROOT/pages/team_permissions_management.adoc

@@ -1,10 +1,5 @@
 = Team Membership Management with Fedora Accounts
 
-[WARNING]
-====
-**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.
-====
-
 == Overview
 
 This document explains how team membership is managed on Fedora Forge through Fedora Accounts (FAS) groups, and why we don't use Forgejo's built-in team management interface. Understanding this system is crucial for administrators and team members who need to manage team membership and access to repositories and organizations.

modules/ROOT/pages/using_http_auth.adoc

@@ -1,14 +1,9 @@
 = How to Clone a Repository using HTTPS Authentication in Fedora Forge
 
-[WARNING]
-====
-**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 provides a step-by-step guide on how to clone a repository from
-the Fedora Forge instance using HTTPS authentication. This method is
+the https://forge.fedoraproject.org/[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.
@@ -54,7 +49,7 @@ token with `+repository+` read/write access instead of clicking through the Web
 . Click on your *profile picture/icon* in the top-right corner.
 . Select *"Settings"* from the dropdown menu.
 
-. In the left-hand navigation sidebar, click on *"Applications"*.
+. In the left-hand navigation sidebar, click on https://forge.fedoraproject.org/user/settings/applications[*"Applications"*].
 
 . Under the "Access Tokens" section, click the *"Generate Token"* button.
 . *Token Name:* Give your token a descriptive name (e.g., `my-laptop-git`).

modules/ROOT/pages/webhook_openshift.adoc

@@ -0,0 +1,93 @@
+= Webhook for build trigger in Fedora OpenShift
+
+== Purpose
+
+This document explains how to setup an automatic build trigger for OpenShift deployment from
+Forgejo instance.
+
+== Setting up the OpenShift trigger
+
+. Request a new secret for your project from Fedora Infrastructure. Open a ticket on
+  https://forge.fedoraproject.org/infra/tickets/issues and request a secret
+  for your OpenShift project for both staging and/or production.
+
+. Add this secret to secret file in your OpenShift project. The secret file could look like this:
++
+....
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: generic-webhook-secret
+data:
+  WebHookSecretKey: "{{ (env == 'production')|ternary(<project>_prod_generic_secret, <project>_stg_generic_secret) | b64encode }}"
+type: Opaque
+....
+
+. Add generic build trigger to `buildconfig` file.
++
+....
+  triggers:
+    - type: Generic
+      generic:
+        secretReference:
+          name: generic-webhook-secret
+....
+
+== Obtain webhook URL
+
+. Install the OpenShift client from OKD tools. See
+  link:https://docs.okd.io/latest/cli_reference/openshift_cli/getting-started-cli.html#cli-getting-started[Kubernetes documentation].
+
+. Login to OpenShift instance you want to work with (
+  link:https://console-openshift-console.apps.ocp.fedoraproject.org/[production] or
+  link:https://console-openshift-console.apps.ocp.stg.fedoraproject.org/[staging]) and copy the
+  login command (you can find it under your profile in top right corner)
+
+. Login using the `oc` tool.
++
+....
+oc login --token=XXX --server=https://api.ocp.[stg.]fedoraproject.org:6443
+....
+
+. Switch to your project
++
+....
+oc project <project>
+....
+
+. Get the webhook url from the buildconfig
++
+....
+oc describe bc
+....
++
+And look for the Webhook Generic section, where you will find the URL.
+
+. Obtain the secret to fill in to URL.
++
+....
+oc get secret generic-webhook-secret -o jsonpath='{.data.WebHookSecretKey}' | base64 -d
+....
+
+Now you should have everything to construct the URL for webhook.
+
+== Add webhook to Forgejo project
+
+. Go to project `Settings` and `Webhooks`
+
+. Add webhook and choose Forgejo
+
+. Fill in the webhook
++
+....
+Target URL: https://api.ocp.fedoraproject.org:6443/apis/build.openshift.io/v1/namespaces/poddlers/buildconfigs/toddlers/webhooks/<secret>/generic
+HTTP method: POST
+Post content type: application/json
+Secret: 
+Trigger on: Push events
+Branch filter: <branch you want to trigger the build from>
+Authorization header:
+....
+
+Now the trigger should work everytime you push in the selected branch.

modules/ROOT/pages/webhook_to_fedora_messaging.adoc

@@ -1,10 +1,5 @@
 = Webhook to Fedora Messaging for Forgejo
 
-[WARNING]
-====
-**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 explains how to quickly establish events from a Forgejo repository to be conveyed to the Fedora Messaging bus.

modules/ROOT/partials/access_fedora_forge_migration_tool.adoc

@@ -1,4 +1,4 @@
-. Log into Fedora Forge using your Fedora Account credentials and navigate to the destination organization where you want to create the migrated repository.
+. Log into https://forge.fedoraproject.org/[Fedora Forge] using your https://accounts.fedoraproject.org/[Fedora Accounts] credentials and navigate to the destination organization where you want to create the migrated repository.
 . Click on the *New migration* button to begin the migration process.
    image:pagure_migration_new_migration_button.png[]
 . Click on the *Pagure* button at the bottom of the migration page.