Skip to main content

Open Build Service (OBS) Integration

The Agama installer packages are built in the openSUSE Open Build Service.

Development project​

The systemsmanagement:Agama:Devel contains the latest packages built from the master Git branch. This project contains unstable development version of Agama. It is intended for development and testing.

The packages are automatically updated whenever the master branch is changed or when a new version is released. See more details below.

Releasing a new version​

For releasing a new version just create a new version tag. The process is then fully automated. See more details in the Packaging documentation section.

OBS synchronization​

The automatic OBS synchronization is implemented using the GitHub Actions. The actions are defined in the obs-staging-*.yml files in the .github/workflows directory.

Because the process of updating a package is the same for several packages the definition is shared in the obs-staging-shared.yml file.

The packages in the devel project 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 the 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 sources from GitHub and dependencies from other repositories (Rust or NPM packages).

The process of updating a package is basically:

  • osc co systemsmanagement:Agama:Devel <package> - checkout the package from OBS
  • osc service manualrun - update the sources and dependencies by running the OBS services locally
  • osc commit - upload the changes to the OBS server, it will rebuild the updated package automatically

To run the services locally you need to install the OSC tool and several packages with the used OBS services:

zypper install osc obs-service-cargo_audit obs-service-cargo_vendor \
  obs-service-download_files obs-service-format_spec_file obs-service-obs_scm \
  obs-service-node_modules

The rubygem-agama package uses a different approach because the Ruby packages use *.gem files which are not supported by OBS services. It uses the osc:commit Rake task, same as the YaST packages.

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:Devel repository. This will inherit the repository setup for building the packages, images and containers.

osc branch systemsmanagement:Agama:Devel agama-web-ui

This will create home:$OBS_USER:branches:systemsmanagement:Agama:Devel 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:

osc meta prj home:$OBS_USER:branches:systemsmanagement:Agama:Devel | \
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:Devel

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:

osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Devel 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-installer package:

osc branch systemsmanagement:Agama:Devel agama-installer
osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Devel agama-installer

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 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.

  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:Devel"). If the variable is not created or is empty the autosubmission is disabled.

  3. Enable the GitHub Actions in the "Actions" tab.

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.

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.

Devel package versioning​

The packages in the Devel project use a version built from the last released version with a number of commits in the master branch since that release.

The version is automatically constructed by the OBS service, for the rubygem-agama package the version is built using the git describe --tags command.

Release project​

For releasing a public version of Agama we use the systemsmanagement:Agama:Release project and respective release branch in Git. The reason for a separate project is that we might need to release a hot fix but the master branch might already contain a new feature for the next version.

The integration works the same way as for the Devel project above, the only difference is that it uses the OBS_PROJECT_RELEASE GitHub Action variable to define the target OBS project to allow submitting to a different project.

Release package versioning​

The packages in the Release project use a version based on the version tag matching v[0-9]+. Use rake tag command for creating a tag. See more details in the packaging documentation.