Dist-git repository onboarding
Table of contents
Setup
To start using Packit in dist-git, you only need:
- a configuration file
- enable the monitoring for your package
1. Configuration file
To start using Packit for automating your Fedora releases with setup only in dist-git,
the main thing you need is to create a configuration file and place it
in the default (rawhide
) branch of your dist-git repository.
As a format, it uses YAML and here are all the valid names:
.packit.yaml
.packit.yml
packit.yaml
packit.yml
In your configuration file, you can define these jobs:
You can use our downstream configuration template for creating your Packit configuration in dist-git repository.
You can also use packit dist-git init CLI command to create your Packit dist-git configuration.
For validation of the configuration, you can utilise
Packit CLI command validate-config
or our
pre-commit hooks.
Jobs
Pull from upstream job
When a new upstream release happens and release-monitoring.org detects it, you'll get dist-git pull requests with it automatically.
Bodhi updates created by the bodhi_update
job as well as automatic Bodhi updates will close the Bugzilla opened by
the Upstream Release Monitoring automatically when they reach stable.
Packit adds the Bugzilla numbers to the commit message and the changelog in this form - Resolves rhbz#xz
.
There is also an env variable with the list of bugs to be closed
PACKIT_RESOLVED_BUGS
that you can use in the case you want to customize the changelog creation through an action
as shown below.
If you want to restrict what releases with corresponding tags Packit should react on,
you can utilise the configuration options upstream_tag_include
and
upstream_tag_exclude
. However, these are currently taken into consideration only when the
upstream_project_url
is configured. In case of omitting it in configuration, you can adjust the releases filtering
using the release-monitoring.org
project settings.
Upstream tarball URL is taken from the spec file or from sources
(see below)
and not from upstream_project_url
.
You can check the other customization options here.
Current default behaviour of the release syncing results in having divergent dist-git branches. If you want to avoid this, please see the details here.
Koji build job
You can configure Packit to react to the new commits in your dist-git repository and create
Koji builds by including a koji_build
job in the configuration.
Then, if Packit is informed (via fedora-messaging bus) about a new commit in the configured dist-git branch, it submits a new build in Koji
like maintainers usually do. (The commits without any spec file change are skipped.)
By default, only merged pull requests created by Packit are being acted upon, but
you can override this behaviour by specifying
allowed_pr_authors
and/or allowed_committers
in the job configuration.
The koji_build job can be configured like this:
jobs:
- job: koji_build
trigger: commit
dist_git_branches:
- fedora-all
Bodhi update job
You can configure Packit to react to successful Koji builds and create
Bodhi updates by including a bodhi_update
job in the configuration.
Once Packit is informed (via fedora-messaging bus) about the successful Koji build for the configured branch,
it creates a new update for that branch in Bodhi for you.
By default, only successful Koji builds created by Packit are being acted upon, but
you can override this behaviour by specifying
allowed_builders
in the job configuration.
The bodhi_update job can be configured like this:
jobs:
- job: bodhi_update
trigger: commit
dist_git_branches:
- fedora-branched # rawhide updates are created automatically
Actions - use your own commands/scripts
Actions are a way how to redefine or tweak the Packit's workflows. These are user-defined commands that can replace a part of Packit's job (e.g. to get version, or to create a tarball) or are run in a particular step as a hook (with no action run by default).
Take a look at the tables here to know what actions are available for each job. You can also see some examples here
2. Monitoring of the package
Besides the configuration file, if you use the pull_from_upstream
job, you also need
to have your package monitored by Upstream Release Monitoring:
- make sure there is Fedora mapping for the upstream project in https://release-monitoring.org/projects/
- make sure
Monitoring status
on the left side at https://src.fedoraproject.org/rpms/your-package is set toMonitoring
You can check an example of a configuration file in the section below.
How to try that for real
Release syncing
If you are interested in the functionality of syncing the release (pull_from_upstream
job)
and want to try it out, we recommend triggering the job
first time from a dist-git pull request to make sure Packit is correctly configured (see the following sections).
If there is a pending release
If there is a new release pending for your package (bugzilla has been opened by release-monitoring.org but no rebase done in dist-git yet), do the following:
- create a
rawhide
-based pull request with Packit configuration defining thepull_from_upstream
job- we recommend firstly setting the
dist_git_branches
for the job to one branch only (e.g.fedora-rawhide
)
- we recommend firstly setting the
- comment
/packit pull-from-upstream --with-pr-config
on the pull request - check the dashboard
- if everything went well, review the pull request(s) in your dist-git repository created by Packit
- if you are happy with the results
- you can update the
dist_git_branches
to include the list of desired branches and trigger the syncing for all branches (using the same comment/packit pull-from-upstream --with-pr-config
) - merge the pull request
- you can update the
If there is no pending release
If there is no pending release and your package has been rebased at least once in the past, you can still try the job using a new testing branch:
- create a branch pointing to a commit before the last rebase, name it e.g.
packit-test
and push it (directly to dist-git, not to your fork) - create a
rawhide
-based pull request with Packit configuration defining thepull_from_upstream
job - in the configuration, set the
dist_git_branches
option of thepull_from_upstream
job to the name of the testing branch - comment
/packit pull-from-upstream --with-pr-config
on the pull request - check the dashboard
- if everything went well, review the pull request in your dist-git repository created by Packit
- if you are happy with the results, you can change the
dist_git_branches
option to whatever you want, merge your pull request and wait for the next upstream release
Normally, the version is taken from Upstream Release Monitoring as Packit is triggered by that. When triggering via comment, the version is retrieved from the latest upstream project release tag.
To reproduce the Packit Service behaviour with your credentials from CLI,
you can use a packit pull-from-upstream
command.
It creates dist-git pull requests with the content of the release and the Packit config taken from a local clone.
Koji builds and Bodhi updates
The Koji builds are triggered for dist-git pushes to configured branches that contain specfile change and meet other requirements (see the schema). The Bodhi updates are then created when Packit successfuly builds in Koji. You can trigger both of them manually as well, see Retriggering section.
To reproduce the Packit Service behaviour with your credentials from CLI,
you can use again Packit commands packit build in-koji
and
packit create-update
.
UI
You can check all the job runs with details and logs in Packit dashboard, specifically:
You can utilise Fedora Notifications as well.
Notifications about errors
Since it is not possible to create issues in dist-git repositories, you can configure a repository where we should
open issues in case of errors during the downstream jobs via issue_repository
configuration key. See the details in the link.
Retriggering
pull_from_upstream
Packagers can retrigger the job via a comment in any dist-git pull request:
/packit pull-from-upstream
This will take the Packit configuration file from the default branch of the dist-git
repository (rawhide
), same as if the job was triggered by a new release. To use the configuration file from the dist-git pull request you are commenting on, you can add an argument:
/packit pull-from-upstream --with-pr-config
koji_build
Packagers can retrigger a build by a comment in a dist-git pull request:
/packit koji-build
The build will be triggered for the target branch of the pull request using the most recent commit on the target branch (NOT the HEAD commit of the pull request).
If Packit created an issue in the configured issue_repository
, you can place the same comment in that
issue to retrigger the builds (see issue_repository
for details).
bodhi_update
Packagers with write access to the dist-git repository can retrigger an update by a comment in a dist-git pull request:
/packit create-update
The update will be triggered for the target branch of the pull request.
If Packit created an issue in the configured issue_repository
, you can place the same comment in that
issue to retrigger the updates (see issue_repository
for details).
Full example of a dist-git only configuration
Let's take a look how the configuration file can look like when you define all three steps. It's quite simple, isn't it?
jobs:
- job: pull_from_upstream
trigger: release
dist_git_branches:
- fedora-rawhide
- job: koji_build
trigger: commit
dist_git_branches:
- fedora-rawhide
- job: bodhi_update
trigger: commit
dist_git_branches:
- fedora-branched # rawhide updates are created automatically