Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
User Guide / Best Practices / Using the OBS Web UI

12 Using the OBS Web UI

This chapter explains and shows how you could use OBS Web UI. We will show and use OBS Web UI based on http://build.opensuse.org. You need to make an account first to follow this chapter contents.

12.1 Homepage and Login

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

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

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

Logged in
Figure 12.3: Logged in

12.2 Home Project

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.

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

Updating project description
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
Note

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

Creating Subprojects
Figure 12.6: Creating Subprojects

12.3 My Projects, Server Status

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.

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

Status Monitor
Figure 12.8: Status Monitor

12.4 Create a link to a package in your home

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.

My Projects
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:

  1. Add link to the existing package.

  2. Add repository.

  3. Observe the build on the monitor page.

  4. Look at package's page.

12.4.1 Add Link to Existing Package

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

Branch Package
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:

Apache Flood Branch
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.

Branched Package
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:

flood_succeeded_finished
Figure 12.13: flood_succeeded_finished

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

flood_build_success
Figure 12.14: flood_build_success

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

flood_build_log
Figure 12.15: flood_build_log

12.5 Repository Output: Built Packages

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:

My_Repository
Figure 12.16: My_Repository
Note
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:

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

12.6 Managing Repositories

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

Adding a Repository to a Project
Figure 12.18: Adding a Repository to a Project
Note
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.

Adding a Download on Demand Repository
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 can be found at Section 22.3, “Download on Demand Repositories (DoD)”. Press "Save" to create the repository.

Download on Demand Repository Form
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

Adding Download on Demand repository sources
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.

Form for Adding DoD Repository Sources
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.

Form for editing DoD repository sources
Figure 12.23: Form for editing DoD repository sources

12.6.5 Editing DoD Repository Sources

To delete a repository or repository source, click on the "Delete" link and accept the confirmation dialog.

12.7 Image Templates

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.

OBS Templates Page
Figure 12.24: OBS Templates Page

12.7.1 Creating Own Image Templates

Create a subproject of your home project.

Form for creating image template subproject
Figure 12.25: Form for creating image template subproject
Note
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.

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

Enabling the KIWI Image Build Repository
Figure 12.27: Enabling the KIWI Image Build Repository

Add sources for your image configuration.

Overview of Sources of a Custom Image Template
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.

12.7.2 Publishing Image Templates on the Official Image Templates Page

Once everything is set up and your templates are building, you might want to publish them. In that case contact the admin of the OBS instance you are using and ask them kindly to do so. If you happen to use the official OBS, that would be admin@opensuse.org.

12.8 KIWI Editor

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.

Example of a Package with a KIWI XML File
Figure 12.29: Example of a Package with a KIWI XML File
Note
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.

KIWI Editor. Show screen
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.

KIWI Adding a new repository - Basic Mode
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.

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

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

KIWI Use project configuration
Figure 12.33: KIWI Use project configuration
Note
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.

KIWI Adding a new package
Figure 12.34: KIWI Adding a new package
Note
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 didn't exist previously, the KIWI Editor creates a package group with type image for you.

12.9 Manage Group

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.

Manage a Group
Figure 12.35: Manage a Group

12.10 Staging Workflow

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.

Staging Workflow Basic Schema
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.

Staging Workflow Schema
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.

Creating a Staging Workflow for openSUSE:Factory
Figure 12.38: Creating a Staging Workflow for openSUSE:Factory
Note
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.

Staging Workflow Show Screen
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.

Staging Workflow Delete Icon
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.

Delete a Staging Workflow
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.

Staging Workflow Configure Icon
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.

Configuring a Staging Workflow
Figure 12.43: Configuring a Staging Workflow
Note
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.

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

Copy Staging Project from Template
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.

Looking into a Staging Project
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.

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

Exclude Requests
Figure 12.48: Exclude Requests