Open a browser and navigate to https://build.opensuse.org

Figure 12.1: Start page #

To proceed, you'll need to log in and authenticate with your username and your password. Click on Login and enter the data in the upper right corner.

Figure 12.2: Login #

After successful authentication, you'll end up on the start page again - with new options visible. We'll go through most of them in detail, but first lets create your home: in the next step.

Figure 12.3: Logged in #

Every user has a home project (home:[userid]) where they have write access by default. This is a personal workspace where you can experiment and play. Click on the link "Home Project" at the upper right to get to your home project.

12.2.1 The Project Page #

Your home project will be empty for now, but you can add packages containing sources/build recipes and projects which are containers for the build targets. As you can see, you're the default maintainer which grants you full write access to this project. You're also the bug owner of your project.

Figure 12.4: Project Page #

12.2.2 Changing a project's title and description #

On every project page you will find a "Edit description" link. This link will lead you to a place were you can review and change your project's title and description. Click on the "Update project" button to save.

Figure 12.5: Updating project description #

12.2.3 Creating Subprojects to a Project #

Subprojects are projects that are part of another projects namespace. Subprojects are an easy way to organize multiple projects. On the "Subprojects" tab you can find a list subprojects that belong to a project. To create a new subproject click on the "New subproject" link, fill in the form and press the "Create project" button.

Note

Maintainers of upper projects can always modify the subprojects. Apart from that all projects are separated and have no influence on each other.

Figure 12.6: Creating Subprojects #

For now, let's leave your home for a bit and explore the build service. Click on "My Projects" on the left at the bottom. This opens a page listing your watched projects and your involvements in projects or packages.

Figure 12.7: My Projects #

Now, let's visit the main monitor page by clicking on "Status Monitor". You see here the status of the services, some graphs and graphics are showing the currently running and completed jobs and the overall load.

Figure 12.8: Status Monitor #

We'll show you how you can log in and use the web interface hosted at build.opensuse.org. This includes login, adding a link to a package in your personal workspace (home:) and how to build that package by adding a repository. First, let's enter "My Projects" by clicking on the link at the bottom left.

Figure 12.9: My Projects #

Now let's create a link to a package and add a repository to build against. A link is basically a pointer to sources of an already existing package. By "repository" we mean container of built binary packages like Debian_8 or openSUSE_13.2. Let's follow these steps:

12.4.1 Add Link to Existing Package #

Right below packages, there's "Branch Package from other Project" .

Figure 12.10: Branch Package #

Open that page and enter for

Name of original project:
Apache

and for

Name of package in original project:
flood

- we'll leave "Name of linked package in target project" empty. This is shown on the next picture:

Figure 12.11: Apache Flood Branch #

Proceed with "Create Branch" and you'll be redirected to your home again. You'll see a new package "flood" and a notice about the branch being added.

Figure 12.12: Branched Package #

Wonderful, we've added a pointer to the sources! Now we need to add a repository, so the builder knows the target-distribution to build packages for. How to add a repository to a project is documented at Section 12.6.1, “Adding a repository”.

12.4.2 Package Page, Build Log and Project Monitor Page #

Next, it is time to explore the Monitor page, the package detail page and the build log. Just click on the links and explore the web interface. I recommend starting with your home project's top level 'overview' page - click on the Overview tab and you may see something like this:

Figure 12.13: flood_succeeded_finished #

If you wait a bit, you would see the below building success screen

Figure 12.14: flood_build_success #

Click the “succeeded” message, then you will see the build log as below.

Figure 12.15: flood_build_log #

To find the RPMs you built, go to your home project page and click Repositories. From there click on the blue repository name. For example, openSUSE_Factory:

Figure 12.16: My_Repository #

Note

Published repositories are marked with the OBS truck

Now click Go to download repository. Note that publishing the repository might take a while. Before the binary repository is published, you will receive a 404 error. When the binaries are available, you will see something like this:

Figure 12.17: Repository Structure #

Your RPMs can be found in the subdirectories, and the .repo file is suitable for use with zypper, yum or other repository-friendly package management tools.

This section will show how you can manage your project's repositories.

12.6.1 Adding a repository #

To add a repository to your project, click on "Add Repositories" on the project's repository tab. This will direct you to a list of possible distributions you can build packages for, see Figure 12.18, “Adding a Repository to a Project”.

Figure 12.18: Adding a Repository to a Project #

Note

If you could not find a repository that fits your needs, you might want to switch to the expert mode. Click on the "Expert mode" link right to the button. This page allows you to search and select a repository of any project available in OBS and add it to your projects repository list.

This will take you back to your home: project. The build repository might be disabled: if so, click on the cogwheel to enable it. Congratulations, it is configured. On a heavily loaded server, it can sometimes take a few minutes for your changes to become effective, but your linked package will automatically begin building.

12.6.2 Add Download on Demand repositories to a project #

When you have administrator rights you will be able to add Download on Demand repositories to your project. To do so, click on the "Add DoD repository" link and enter your DoD repository data into the form.

Figure 12.19: Adding a Download on Demand Repository #

The minimal set of fields you have to enter are architecture, repository type and the URL that provides the binary packages. Detailed information about the data you can enter here you can find at the DoD concept section. Press "Save" to create the repository.

Figure 12.20: Download on Demand Repository Form #

When the repository got added you are able to edit, delete or add additional DoD repository sources.

12.6.3 Adding DoD Repository Sources to a Repository #

Figure 12.21: Adding Download on Demand repository sources #

Open the DoD repository sources form by clicking the "Add" link. Here you can enter your additional DoD repository source. Click the "Add Download on Demand" button.

Figure 12.22: Form for Adding DoD Repository Sources #

12.6.4 Editing DoD Repository Sources #

To edit DoD repository sources after they got added click on the "Edit" link that you find right to each DoD repository source.

Figure 12.23: Form for editing DoD repository sources #

Image templates are pre-configured image configurations. The image templates page provides a list of these templates. Users can clone these templates and further configure them as they like.

How you can create your own image templates will be shown here.

Figure 12.24: OBS Templates Page #

12.7.1 Creating Own Image Templates #

Create a subproject of your home project.

Figure 12.25: Form for creating image template subproject #

Note

Published image templates are fetched via a project's attribute. Any package container living in a published project will be visible on the image templates page.

Within that project create a new package. That will be your actual image template.

Figure 12.26: New Image Template #

Add the 'KIWI image build' repository to your project. This repository is needed to build KIWI images in your project. Go to the 'Repositories' tab, click on 'Add repositories' and click on the 'KIWI image build' check box.

Figure 12.27: Enabling the KIWI Image Build Repository #

Add sources for your image configuration.

Figure 12.28: Overview of Sources of a Custom Image Template #

KIWI configurations usually consists of an xml configuration root tarball.

In addition, you can define an icon for your image templates by adding graphical image (for example, PNG, JPG) to your template sources and name it _icon. If that file exists, it will be used as icon for your image on the image templates page.

For a full list of image descriptions and general information about building images with KIWI, see the KIWI project page and the KIWI cookbook.

You can edit the KIWI file associated to your project. It is only possible, at the moment, to edit the repository list and packages with type image. If you are running your own instance of OBS be sure you have the kiwi_image_editor feature enabled in your config/feature.yml file.

12.8.1 Accessing the KIWI Editor #

Go to your package, and upload a file with the .kiwi extension (for example, test.kiwi), with valid KIWI content.

Figure 12.29: Example of a Package with a KIWI XML File #

Note

You should see now a "Edit KIWI" link (next to "Delete package" link).

Click on the "Edit KIWI" link and you will be redirected to the Editor.

Figure 12.30: KIWI Editor. Show screen #

• Repositories: Displays the repositories set in the Kiwi file.

• Packages: Displays the packages of the package group with type image.

12.8.2 Adding Repositories in the KIWI Editor #

To add a new repository click Add repository link and fill in the dialog. There are two ways to create it:

• Basic Mode: Adding the name of a project will provide a list with the repositories from that project.

Figure 12.31: KIWI Adding a new repository - Basic Mode #

• Expert Mode: This mode provides you with a set of customizable parameters for creating a repository.

  • Type: Valid options are rpm-md and apt-deb.

  • Priority: Repository priority for the given repository.

  • Alias: Alternative name for the configured repository.

  • Source Path: Define the repository path.

  • User: Specifies a user name for the given repository.

  • Password: Specifies a password for the given repository.

  • Prefer License: The repository providing this attribute will be used primarily to install the license tarball if found on that repository.

  • Image Include: Specifies whether the given repository should be configured as a repository in the image.

  • Replaceable: Defines a repository name which may be replaced by the repositories specified in the image description. This attribute should only be applied in the context of a boot image description.

Figure 12.32: KIWI Adding a new repository - Expert Mode #

To use the configuration of the current project check the Use project repositories checkbox.

Figure 12.33: KIWI Use project configuration #

Note

This option will remove the other repositories from your kiwi file.

12.8.3 Adding Packages in the KIWI Editor #

Adding a package is practically the same as adding a repository. We offer an autocomplete for the package name that will show you the package available in the repositories added previously.

Figure 12.34: KIWI Adding a new package #

Note

The package groups shown in the editor are only those with type image and the packages will be added in this kind of package group. If it did exist previously the KIWI Editor creates a package group with type image for you.

Only administrators and users with Maintainer rights can manage groups. They can add and remove other users from the group, as well as give them Maintainer rights.

On the Group Members tab, there is a link to Add Member, then enter the name of an existing user. You can click on the Maintainer checkbox to give Maintainer rights to a user.

Figure 12.35: Manage a Group #

The Build Service is well known for providing an easy way to build and distribute binary packages from source code. The packages, grouped together in what we call a project, are built every time they are updated. The maintainers of the package can choose among a wide range of operating systems and hardware architectures to build the packages on. Those continuous building processes ensure that the packages are always working for the different setups.

The maintenance of those packages can be made on a collaborative way via Build Service. As shown in the following diagram, the maintainers can create a package and then they or any other developer can branch it (make a copy of it), can do some changes on its code and can request those changes to be applied on the original package. After that, the maintainers usually review the request, chat with the developer in case it needs some fixes and end up accepting the request. Doing so, the new changes to the code become part of the package's source code.

Figure 12.36: Staging Workflow Basic Schema #

However, the workflow is not always that easy. Apart from managing individual packages, Build Service provides many other functionalities and it even allows us to release entire distributions. In a very simplistic way, we can say a distribution is just a Build Service project with thousands of packages inside. Packages that have been selected to be installed together as part of the distribution.

When dealing with such a big project, many people request changes in many different packages all the time. They have to be reviewed, adjusted and tested (built) before being accepted. As you can imagine, it becomes nonviable to review the packages one by one. Even if the maintainers check that a package is not broken and merge it, it can break everything else for conflicts with other packages. To deal with these situations, Build Service provides what we call Staging Workflow.

The idea behind the Staging Workflow is testing the requests incrementally by batches. First, a copy of the original project is created, it is called Staging Project and is going to act as a playground. The Staging Managers select some of the requests they consider to be belonging together and assign the corresponding packages to the Staging Project. This way, the groups of packages are going to be tested (built) in one go. Once the Staging Project gets built, the changes can be merged to the original project.

The Staging Managers can create as many Staging Projects as they require and can assign different selections of requests to each of them. It is still tedious solving the conflicts that appear between them, but being able to test a lot of packages in parallel is much more efficient than doing the same package by package.

Let's make it clearer with a real example. Imagine we are working on the project openSUSE Factory and we start working on its Staging Workflow.

Many contributors and maintainers really want some improvements to be applied on their packages, so the openSUSE:Factory project receives new requests all the time. Among all of them, there are a few that are related to Gnome packages, so the Staging Managers decide to stage them together in openSUSE:Factory:Staging:A. The Staging Project is an exact copy of the main project openSUSE:Factory.

The building process begins and, if something gets broken, the Staging Managers ask the requester to fix it. This can add even more requests to the scene but the goal is always getting a working version of openSUSE:Factory:Staging:A by fixing or even discarding some of the requests. When the building process finishes successfully, the requested changes are merged in the source code of openSUSE:Factory and some other batches of requests are staged again and again until we come up with an stable version of openSUSE:Factory ready to be released.

Figure 12.37: Staging Workflow Schema #

12.10.1 Creating a Staging Workflow #

At the moment, it is possible to create a Staging Workflow for any kind of project unless the project is already one of the Staging Projects.

All the Staging Workflow starts in the tab 'Staging' which can be found on the project's page. It will take you to the first step to create a new Staging Workflow or to the dashboard if the Staging Workflow already exists.

The creation of a Staging Workflow will automatically create two Staging Projects as a subproject of the main project. Before creating, we need to select a group of managers, they will be in charge of assigning requests to the Staging Projects and also excluding requests from the Staging Workflow.

Figure 12.38: Creating a Staging Workflow for openSUSE:Factory #

Note

An Admin should previously create the manager groups.

12.10.2 Start Using Staging Workflow #

In this view, we can find all the Staging Projects with an associated request and their current state.

Figure 12.39: Staging Workflow Show Screen #

• Table content:

  • Staging Project: Shows the Staging Project name, its overall state (see legend), and the overall build progress of the packages within the project.

  • Requests: Show the associated requests and their current state.

  • Problems: Shows build problems of packages within the project and status problems reported to the Build Service's Status API by external services like openQA.

• Info section:

  • Managers: Shows the Staging Managers group.

  • Empty projects: Staging projects without assigned requests.

  • Backlog: List of requests that can be assigned to a Staging Project.

  • Ready: List of requests that were in the backlog and have an accepted review.

  • Excluded: List of requests excluded from this Staging Workflow.

12.10.3 Delete a Staging Workflow #

Next to the title, there is a icon that allows us to delete the Staging Workflow.

Figure 12.40: Staging Workflow Delete Icon #

By clicking on the delete icon on the Staging Workflow index page, we are able to delete a Staging Workflow.

By selecting the associated Staging Projects in the appearing modal window, we are able to delete them as well. If not selected, they will remain as regular subprojects.

Figure 12.41: Delete a Staging Workflow #

12.10.4 Configure a Staging Workflow #

Next to the title, there is a link to the Staging Workflow configuration's page.

Figure 12.42: Staging Workflow Configure Icon #

From the configuration page it is possible to delete a Staging Project, create one from scratch or create a copy of an existent one. But also to change the Managers Group of the Staging Workflow.

Figure 12.43: Configuring a Staging Workflow #

Note

Changing the Managers Group of a Staging Workflow will automatically unassign the old group and assign the new group to the related Staging Projects.

12.10.4.1 Create Staging Project from Scratch #

Right after the creation of a Staging Workflow, two new Staging Projects are automatically created and assigned to it: Staging:A and Staging:B. However, it is also possible to create a new Staging Project from scratch.

On the Staging Workflow dashboard, click on configure icon next to the title and then on Create Staging Project to add a name for the new Staging Project.

Figure 12.44: Create a New Staging Project #

12.10.4.2 Create Staging Project from a Template #

It is possible to create a Staging Project from a template. Inside Staging Workflow's configuration page, simply choose the Staging Project you want to copy from (the template), click on its Copy icon and add a new name. The Staging Project copy is processed in the background, so there might be a delay before it shows up.

Figure 12.45: Copy Staging Project from Template #

12.10.5 Staging Project #

A Staging Project contains requests assigned by a Staging Manager. There is an overview page for a Staging Project, where you can find more detailed information about the requests, reviews and checks.

Figure 12.46: Looking into a Staging Project #

• Obsolete Requests: Requests that were declined, revoked or superseded.

• Missing Reviews: Requests with pending reviews.

• Building Repositories: List of packages that are still building.

• Broken Packages: List of packages with failing builds.

• Checks: List of checks of the Staging Project.

All the actions performed on requests that are assigned to the Staging Project are tracked. They are listed in the 'History' section.

Figure 12.47: History #

12.10.6 Working with Requests in Staging Workflow #

12.10.6.1 Exclude Requests #

Sometimes it can be useful to exclude a request and don't let it be available in the Backlog. This can prevent the staging project from being assigned with requests we are sure are causing conflicts, have some missing dependencies or have to wait for other request to be accepted.

By clicking on the 'Excluded' link on the 'Infos' section, it is possible to exclude requests or bring back already excluded ones.

Figure 12.48: Exclude Requests #