Skip to main content

Packit Service jobs configuration

Packit Service doesn't have any web interface, but its behaviour can be configured via the config file generally described here.

The tasks Packit Service should do should be defined in the jobs section. The section is a list of dictionaries:

jobs:
- {key: value}
- {}

When there is an action (pull request, commit, etc.) in the upstream repository, Packit Service takes the config file from the relevant git ref (release tag for release, PR head for pull requests, related dist-git commit for downstream jobs). Then, it tries to find a matching job in the jobs sections for the particular event (e.g. for pull request, jobs with pull_request trigger are matched).

If there is no jobs section in the configuration file, jobs default to:

jobs:
- job: copr_build
  trigger: pull_request
  targets: [fedora-stable]

- job: tests
  trigger: pull_request
  targets: [fedora-stable]

- job: propose_downstream
  trigger: release
  dist_git_branches:
    - fedora-all

If you do not want to use the jobs then the jobs section in the configuration file should be empty:

jobs: []

Packit configuration supports YAML Merge Key syntax, which can be used to reduce duplication of configuration. Please see the example:

# before
jobs:
- job: copr_build
  trigger: pull_request
  targets:
    - centos-stream-8-x86_64
    - centos-stream-9-x86_64
    - fedora-all

- job: copr_build
  trigger: commit
  branch: main
  targets:
    - centos-stream-8-x86_64
    - centos-stream-9-x86_64
    - fedora-all

# after
jobs:
- &copr
  job: copr_build
  trigger: pull_request
  targets:
    - centos-stream-8-x86_64
    - centos-stream-9-x86_64
    - fedora-all

- <<: *copr
  trigger: commit
  branch: main

Do not forget that you can also define common Packit config options at the top level (such as targets or actions) and only override them when needed in the jobs or packages section. Note that overriding replaces the whole value, not individual keys — for actions this means a job's actions mapping replaces the top-level one as a whole, rather than being merged per action.

For more complex structures it can be useful to have yaml-anchors that are ignored, in which case you can use the top-level _ key, for example:

_:
  basic-test: &template-basic-test
    job: tests
    trigger: pull_request
    targets:
      - centos-stream-8-x86_64
      - centos-stream-9-x86_64
      - fedora-all

jobs:

- <<: *template-basic-test
  identifier: kernel-rt-sanity
  labels:
    - kernel-rt
  env:
    RPM_NAME=kernel-rt

- <<: *template-basic-test
  identifier: kernel-sanity
  labels:
    - kernel
  env:
    RPM_NAME=kernel

This is typically useful when creating a number of tests which needs various parameters, but many parameters stay same. For compatibility reasons, you can also define a job that is not executed by setting trigger to ignore. The above example can be rewritten as:

jobs:
- &template-basic-test
  job: tests
  trigger: ignore
  targets:
    - centos-stream-8-x86_64
    - centos-stream-9-x86_64
    - fedora-all

- <<: *template-basic-test
  identifier: kernel-rt-sanity
  trigger: pull_request
  labels:
    - kernel-rt
  env:
    RPM_NAME=kernel-rt

- <<: *template-basic-test
  identifier: kernel-sanity
  trigger: pull_request
  labels:
    - kernel
  env:
    RPM_NAME=kernel

However, using the _ placeholder key is preferred as it provides more flexibility.

Configuration keys​

job​

(str) name of the job (you can imagine this as a CLI command).

trigger​

(str) what is the trigger for the job? Every job only supports a specific set of triggers. You can also use the special value ignore that indicates not to execute the job at all (used for templates or temporarily disabled jobs).

packages​

(list) Optional, list of package object names (when using monorepositories). If a job object has no such key, all packages of a monorepo should be handled. The package object names need to be defined in the packages dictionary.

Here is an example of the configuration of the job including the packages:

jobs:
  - job: copr_build
    trigger: pull_request
    targets:
      - fedora-all
      - epel-8
    packages:
      - copr-frontend
      - copr-backend

manual_trigger​

(bool) Option that enables triggering the job only manually (via pull-request/issue comment or rerunning GitHub check). Defaults to false.

Overriding global parameters in jobs​

You are able to override your global parameters (such as specfile_path, downstream_package_name, actions...) for every job. This is very useful when you want to set up a build or a test matrix using different parameters or configuration. It's also useful when your release workflow differs between Fedora and EPEL.

In order to do such a thing, just set a value you want to override in the respective job.

Example:

specfile_path: package.spec
jobs:
- job: some-job
  trigger: ran-out-of-beer
  targets: [fedora-stable]
  specfile_path: somewhere/else/package.spec

In this example, the job some-job would override specfile_path to somewhere/else/package.spec instead of using ./package.spec.

CLI configuration​

Job-level values of keys also available at the top level, such as actions, version_update_mask and notifications, are accepted and validated when the configuration is loaded. They become part of that job's effective configuration, following the override rules above. Packit Service selects the matching job and uses its effective configuration.

Ordinary Packit CLI commands use the package configuration instead: top-level values, or package-level values when using packages. For example, if you set different actions or version_update_mask values at the top level and in a job, the ordinary CLI workflow uses the top-level value. Valid job-level overrides do not change that workflow. Invalid job-level values can still make loading or validation fail, even when a valid value would not be used by the CLI.

The following CLI commands read job-level values:

  • packit prepare-sources --job-config-index N uses the effective configuration of the job at index N (0-based) instead of the package configuration, and executes its actions as needed. A job with multiple triggers counts once per trigger; with packages, only jobs associated with each package are counted. This is an internal option used by Packit Service.
  • The experimental packit build in-image-builder uses the first vm_image_build job by default, or the job at --job-config-index (counting all jobs for the package after expanding multiple triggers), which must be a vm_image_build job, and reads its image settings.
  • packit propose-downstream and packit pull-from-upstream read the matching job's dist_git_branches.
  • packit build in-copr reads the first qualifying Copr job's project when no --project option is given.
  • packit validate and packit config validate validate job-level values. Invalid values fail validation; valid values do not change the CLI workflow.

CLI options, such as --project and branch options, take precedence over both package-level and job-level configuration values.

Supported jobs​