From c1b68140cc8f8ca5d7841bab6b5c3379a52ece47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ladislav=20Slez=C3=A1k?= Date: Tue, 14 May 2024 17:14:34 +0200 Subject: [PATCH] Document automatic GitHub -> OBS synchronization for forks (#1206) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Describe how to setup automatic submission from GitHub forks to OBS branched packages. --------- Co-authored-by: Imobach González Sosa --- doc/obs_integration.md | 124 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 1 deletion(-) diff --git a/doc/obs_integration.md b/doc/obs_integration.md index baf03b0553..f22e472937 100644 --- a/doc/obs_integration.md +++ b/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 "/aarch64<\/arch>/d;/i586<\/arch>/d;/ppc64le<\/arch>/d;/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