Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
User Guide / Usage / Staging Workflow

9 Staging Workflow

9.1 Working with Staging Projects

This API provides an easy way to get information about a single or all staging projects like state, requests and checks. Note: To use this API, you first need to setup a staging workflow for a project.

9.1.1 Overview of All Staging Projects

This endpoint provides an overview of all staging projects for a certain project.

geeko > osc api '/staging/openSUSE:Factory/staging_projects/'

Which will return a simple list of staging projects:

<staging_projects>
  <staging_project name="openSUSE:Factory:Staging:A"/>
  <staging_project name="openSUSE:Factory:Staging:B"/>
</staging_projects>

The returned XML can include more information by adding any combination of this three parameters: requests, status and history. This example combines requests and status:

geeko > osc api '/staging/openSUSE:Factory/staging_projects/?requests=1&status=1'
<staging_projects>
  <staging_project name="openSUSE:Factory:Staging:A" state="unacceptable">
    <staged_requests count="6">
      <request id="368" type="submit" creator="scp" state="review" package="amet" superseded_by="" updated="2020-04-29T17:39:36Z"/>
      <request id="369" type="submit" creator="scp" state="declined" package="aut_0" superseded_by="" updated="2020-04-29T17:41:45Z"/>
      <request id="371" type="submit" creator="scp" state="review" package="dolor" superseded_by="" updated="2020-04-29T18:07:51Z"/>
    </staged_requests>
    <untracked_requests count="0"/>
    <obsolete_requests count="2">
      <request id="369" type="submit" creator="scp" state="declined" package="aut_0" superseded_by="" updated="2020-04-29T17:41:45Z"/>
    </obsolete_requests>
    <missing_reviews count="4">
      <review request="369" state="new" package="aut_0" creator="" by_user="Requestor"/>
    </missing_reviews>
    <building_repositories count="0"/>
    <broken_packages count="0"/>
    <checks count="0"/>
    <missing_checks count="0"/>
  </staging_project>
  <staging_project name="openSUSE:Factory:Staging:B" state="empty">
    <staged_requests count="0"/>
    <untracked_requests count="0"/>
    <obsolete_requests count="0"/>
    <missing_reviews count="0"/>
    <building_repositories count="0"/>
    <broken_packages count="0"/>
    <checks count="0"/>
    <missing_checks count="0"/>
  </staging_project>
</staging_projects>

9.1.2 Overview of a Single Staging Project

This endpoint provides an overview of a single staging project.

geeko > osc api '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A'

Which will return the following XML:

<staging_project name="openSUSE:Factory:Staging:A"/>

The returned XML can include more information by adding any combination of this three parameters: requests, status and history. This example combines status and history:

geeko > osc api '/staging/openSUSE:Factory/staging_projects//openSUSE:Factory:Staging:A?status=1&history=1'
<staging_project name="openSUSE:Factory:Staging:A" state="unacceptable">
  <building_repositories count="0"/>
  <broken_packages count="0"/>
  <checks count="0"/>
  <missing_checks count="0"/>
  <history count="8">
    <entry event_type="Staged request" request="368" package="amet" author="Admin"/>
    <entry event_type="Staged request" request="369" package="aut_0" author="Admin"/>
    <entry event_type="Staged request" request="371" package="dolor" author="Admin"/>
    <entry event_type="Staged request" request="374" package="harum" author="Admin"/>
    <entry event_type="Unstaged request" request="374" package="harum" author="Admin"/>
  </history>
</staging_project>

9.1.3 Copy a Staging Project

This endpoint creates a copy of a staging project. It will queue a job which is going to copy the project configuration, repositories, groups and users.

geeko > osc api -X POST '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A/copy/openSUSE:Factory:Staging:A-copy'

9.2 Working with Requests

One of the main features of the staging workflow is assigning incoming requests to different staging projects.

9.2.1 Assign Requests into a Staging Project

Our main project openSUSE:Factory received requests with id 1 and 2. We would like to group these two requests together and move them into the staging project openSUSE:Factory:Staging:A. This can be done with the following command which will create a link to the package in openSUSE:Factory:Staging:A.

geeko > osc api -X POST '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A/staged_requests' -d '<requests><request id="1"/><request id="2"/></requests>'

9.2.2 Remove Requests from a Staging Project

When we are done with testing the staging project openSUSE:Factory:Staging:A, we need to remove the requests 1 and 2 again. The following command will remove the package links from openSUSE:Factory:Staging:A.

geeko > osc api -X DELETE '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A/staged_requests' -d '<requests><request id="1"/><request id="2"/></requests>'

9.2.3 List Requests of a Staging Project

Listing all requests which are currently assigned to openSUSE:Factory:Staging:A can be done with the following command.

geeko > osc api '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A/staged_requests'

Which will return the following XML:

<staged_requests>
  <request id="368" type="submit" creator="scp" state="review" package="amet" superseded_by="" updated="2020-04-29T17:39:36Z"/>
  <request id="369" type="submit" creator="scp" state="declined" package="aut_0" superseded_by="" updated="2020-04-29T17:41:45Z"/>
  <request id="371" type="submit" creator="scp" state="review" package="dolor" superseded_by="" updated="2020-04-29T18:07:51Z"/>
</staged_requests>

9.2.4 Exclude Requests for a Staging Workflow

Our main project openSUSE:Factory received requests with id 3 and 4. We would like to exclude these two requests for the staging workflow project openSUSE:Factory.

geeko > osc api -X POST '/staging/openSUSE:Factory/excluded_requests' -d '<excluded_requests><request id="3" description="Reason description for request id 3."></request><request id="4" description="Reason description for request id 4."></request></excluded_requests>'

9.2.5 Bring Back Excluded Requests from a Staging Workflow

The following command will stop excluding requests with id 3 and 4 for the staging workflow project openSUSE:Factory.

geeko > osc api -X DELETE '/staging/openSUSE:Factory/excluded_requests' -d '<excluded_requests><request id ="3"/><request id="4"/></excluded_requests>'

9.2.6 Accept Staging Project

Once all the requests are ready and the staging project has an acceptable state, the requests can be merged. In other words, the staging project can be accepted.

geeko > osc api -X POST '/staging/openSUSE:Factory/staging_projects/openSUSE:Factory:Staging:A/accept'