Document automatic GitHub -> OBS synchronization for forks (#1206)

Describe how to setup automatic submission from GitHub forks to OBS
branched packages.

---------

Co-authored-by: Imobach González Sosa <[email protected]>

doc/obs_integration.md

@@ -1,5 +1,22 @@
 # The Open Build Service (OBS) Integration
 
+- [The Open Build Service (OBS) Integration](#the-open-build-service-obs-integration)
+  - [Staging Project](#staging-project)
+  - [Development Project](#development-project)
+  - [Releasing a New Version](#releasing-a-new-version)
+  - [OBS Synchronization](#obs-synchronization)
+    - [Details](#details)
+  - [Synchronizing GitHub Fork with OBS Branch](#synchronizing-github-fork-with-obs-branch)
+    - [OBS Branch](#obs-branch)
+    - [GitHub Fork](#github-fork)
+    - [Configuring the GitHub Actions](#configuring-the-github-actions)
+    - [Triggering the Rebuild](#triggering-the-rebuild)
+  - [Package Versioning](#package-versioning)
+    - [Staging](#staging)
+    - [Devel](#devel)
+
+---
+
 The Agama installer packages are built in the openSUSE [Open Build Service](
 https://build.opensuse.org/).
 
@@ -43,6 +60,9 @@ The packages in staging are updated only when a respective source file is
 changed. That saves some resources for rebuilding and makes synchronization
 faster. But that also means the packages might not have exactly same version.
 
+The project to which the packages are submitted is configured in the
+`OBS_PROJECT` GitHub Actions variable.
+
 ### Details
 
 The packages in OBS are updated by running the OBS service which downloads the
@@ -72,7 +92,109 @@ use `*.gem` files which are not supported by OBS services. It uses the
 [osc:commit](https://github.com/openSUSE/packaging_rake_tasks#osccommit) Rake
 task, same as the YaST packages.
 
-### Package Versioning
+## Synchronizing GitHub Fork with OBS Branch
+
+It is possible to synchronize your GitHub fork with your OBS brach
+automatically. This allows easily build your own updated packages or even the
+Live ISO.
+
+### OBS Branch
+
+First you need to create an OBS project where the packages will be built.
+
+The easiest way is to branch the Agama package which you want to modify from the
+[systemsmanagement:Agama:Staging](
+https://build.opensuse.org/project/show/systemsmanagement:Agama:Staging)
+repository. This will inherit the repository setup for building the packages,
+images and containers.
+
+``` shell
+osc branch systemsmanagement:Agama:Staging agama-web-ui
+```
+
+This will create `home:$OBS_USER:branches:systemsmanagement:Agama:Staging`
+project where `$OBS_USER` is your OBS account name. This `$OBS_USER` placeholder
+is also used in the following text.
+
+By default the project will build packages and ISO images for all architectures.
+But if you want to test the packages on a single architecture then it is a good
+idea to remove the other architectures and save some OBS build power.
+
+To remove all architectures except the x86_64 run this command:
+
+``` shell
+osc meta prj home:$OBS_USER:branches:systemsmanagement:Agama:Staging | \
+sed "/<arch>aarch64<\/arch>/d;/<arch>i586<\/arch>/d;/<arch>ppc64le<\/arch>/d;/<arch>s390x<\/arch>/d;" | \
+osc meta prj -F - home:$OBS_USER:branches:systemsmanagement:Agama:Staging
+```
+
+The branched package is still linked to the original package. This might cause
+conflicts after the original package is updated. To avoid this problem you
+should detach the branched package from the original repository:
+
+``` shell
+osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Staging agama-web-ui
+```
+
+If you want to also build the Live ISO from your modified packaged then you need
+to branch (and detach) also the `agama-live` package:
+
+``` shell
+osc branch systemsmanagement:Agama:Staging agama-live
+osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Staging agama-live
+```
+
+*Please delete your branched OBS project once you do not need it anymore, it
+will save quite some OBS build power.*
+
+### GitHub Fork
+
+Then you can fork the [Agama](https://github.com/openSUSE/agama) repository at
+GitHub.
+
+When creating a fork GitHub by default copies only the `master` branch. It does
+not copy the other branches nor tags. The code supports this option, just be
+prepared that the package versions might be different than in the original Agama
+OBS repository because the tags are used to get the version number. If tags are
+missing the version will be set to the commit Unix time stamp followed by a
+short commit hash.
+
+If you want to have similar versions as the original packages then create a full
+fork including all branches and tags (unselect the "Copy the master branch only"
+option).
+
+### Configuring the GitHub Actions
+
+The GitHub Actions needs some configuration to allow the automatic submission.
+
+1. Go to the Settings -> Secrets and variables -> Actions -> New Repository
+   Secret option in your Agama GitHub fork. Create two secrets with names
+   `OBS_USER` and `OBS_PASSWORD` and set them to your OBS credentials.
+
+   Tip: If you do not want to put your credentials for your main OBS account
+   to GitHub then you might create a new separate testing OBS account.
+
+2. Switch to "Variables" tabs and click "New Repository Variable".
+   Create `OBS_PROJECT` variable with name of your OBS branch project
+   ("home:$OBS_USER:branches:systemsmanagement:Agama:Staging"). If the variable
+   is not created or is empty the autosubmission is disabled.
+
+3. Enable the GitHub Actions in the "Actions" tab.
+
+### Triggering the Rebuild
+
+*The autosubmission only works in the `master` branch in your fork, not in any
+other branch!*
+
+To trigger an update and rebuild of your package with the new sources just push
+a commit to the `master` branch.
+
+Alternatively you can trigger the package submission manually. Go to the
+"Action" tab in GitHub, select the respective "Submit" action in the left side
+bar and in the main area click the "Run workflow" selector. Then in the popup
+keep the default `master` branch and click the "Run workflow" button.
+
+## Package Versioning
 
 ### Staging