6 Using Source Services

6.1 About Source Service

Source Services are tools to validate, generate or modify sources in a trustable way. They are designed as smallest possible tools and can be combined following the powerful idea of the classic UNIX design.

Source services allow:

  • Server side generated files are easy to identify and are not modifiable by the user. This way other user can trust them to be generated in the documented way without modifications.

  • Generated files never create merge conflicts.

  • Generated files are a separate commit to the user change.

  • Services are runnable at any time without user commit.

  • Services are runnable on server and client side in the same way.

  • Services are safe. A source checkout and service run never harms the system of a user.

  • Services avoid unnecessary commits. This means there are no time-dependent changes. In case the package already contains the same file, the newly generated file are dropped.

  • Services running local or inside the build environment can get created, added and used by everybody.

  • Services running in default or server side mode must be installed by the administrator of the OBS server.

  • The use of a service can be defined per package or project wide.

For using source services you need (refer to Example 6.1, “Structure of a _service File”):

  • An XML file named _service.

  • A root element services.

  • A service element which uses the specific service with optional parameters.

Example 6.1: Structure of a _service File
<services> 1
 <service name="MY_SCRIPT"2 mode="MODE"3>
  <param name="PARAMETER1">PARAMETER1_VALUE</param>4
 </service>
</services>

1

The root element of a _service file.

2

The service name. The service is a script that is stored in the /usr/lib/obs/service directory.

3

Mode of the service, see Section 6.2, “Modes of Services”.

4

One or more parameters which are passed to the script defined in 2.

The example above will execute the script:

/usr/lib/obs/service/MY_SCRIPT --PARAMETER1 PARAMETER1_VALUE --outdir DIR

6.2 Modes of Services

Each service can be used in a mode defining when it should run and how to use the result. This can be done per package or globally for an entire project.

Default Mode

The default mode of a service is to always run after each commit on the server side and locally before every local build.

trylocal Mode

This mode is running the service locally. The result is committed as standard files and not named with a _service: prefix. Additionally, the service runs on the server by default. Usually the service should detect that the result is the same and skip the generated files. In case they differ, they are generated and added on the server.

localonly Mode

This mode is running the service locally. The result gets committed as standard files and not named with _service: prefix. The service is never running on the server side. It is also not possible to trigger it manually.

serveronly Mode

The serveronly mode is running the service on the server only. This can be useful, when the service is not available or can not work on developer workstations.

buildtime Mode

The service is running inside of the build job, both for local and server side builds. A side effect is that the service package is becoming a build dependency and must be available. Every user can provide and use a service this way in their projects. The generated sources are not part of the source repository, but part of the generated source packages. Note that services requiring external network access are likely to fail in this mode, because such access is not available if the build workers are running in secure mode (as is always the case at https://build.opensuse.org).

disabled Mode

The disabled mode is neither running the service locally nor on the server side. It can be used to temporarily disable the service but keeping the definition as part of the service definition. Or it can be used to define the way how to generate the sources and doing so by manually calling osc service disabledrun The result will get committed as standard files again.

6.3 Defining Services for Validation

Source Services can be used to validate sources. This can be defined at different levels:

  • Per Package.  Useful when the packager wants to validate whether the downloaded sources are really from the original maintainer.

  • Per Project.  Useful for applying project-wide policies which cannot be skipped for any package.

You can validate sources using either of two methods:

  • By comparing checksums and metadata of the files in your repository with checksums and metadata as recorded by the maintainer.

  • Alternatively, you can download the sources from a trusted location again and verify that they did not change.

6.4 Creating Source Service Definitions

Source services are defined in the _service file and are either part of the package sources or used project-wide. Project-wide services are stored under the _project package in file _service. package

The _service file contains a list of services which get called in the listed order. Each service can define a list of parameters and a mode. The project wide services get called after the per package defined services.

The _service file is in XML format and looks like this:

<services>
  <service name="download_files" mode="trylocal" />
  <service name="verify_file">
    <param name="file">krabber-1.0.tar.gz</param>
    <param name="verifier">sha256</param>
    <param name="checksum">7f535a96a834b31ba2201a90c4d365990785dead92be02d4cf846713be938b78</param>
  </service>
  <service name="update_source" mode="disabled" />
</services>

With the example above, the services above are executed in the following order:

  1. Downloads the file via the download_files service using the URL from the Spec file. When using osc, the downloaded file gets committed as part of the commit.

  2. Compares the downloaded file (krabber-1.0.tar.gz) against the SHA256 checksum.

  3. When osc service disabledrun is run manually, update the source archive from an online source. In all other cases, ignore this part of the _service file.

6.5 Removing a Source Service

Sometimes it is useful to continue working on generated files manually. In this situation the _service file needs to be dropped, but all generated files need to be committed as standard files. The OBS provides the mergeservice command for this. It can also be used via osc by calling osc service merge.

Print this page