How to do Fedora releases with Packit

Let's split the release process into single steps:

1. New upstream release
2. Upload archive to lookaside cache
3. Update dist-git content
4. Koji builds
5. Bodhi updates

Doing Fedora releases with Packit means utilising these jobs:

1. propose_downstream or pull_from_upstream
2. koji_build
3. bodhi_update

Every job takes care of a different part of the release process.

tip

In this page, you can find all the details of the release process automation covered by Packit.

If you are a downstream package maintainer and would like to see the information on how to onboard to using Packit in dist-git, see dist-git onboarding guide directly.

Propose downstream or pull from upstream

There are two jobs that can help you to get your new release to Fedora. They differ in the way they are triggered and configured but share the implementation.

1. propose_downstream - push workflow is configured and started in the upstream repository,
2. pull_from_upstream - pull workflow that is configured in dist-git.

Here are the key differences between the two:

	propose-downstream	pull-from-upstream
Packit Service	Have a .packit.yaml in upstream repo: jobs: - job: propose-downstream: ... Triggered by a new release in upstream project. It creates dist-git pull requests with the content of the release.	Have a .packit.yaml in dist-git repo (main or rawhide branch): jobs: - job: pull-from-upstream: ... Triggered by a new release in upstream project. It creates dist-git pull requests with the content of the release and the packit config taken from dist-git main/rawhide branch.
Packit CLI	Have a .packit.yaml in upstream repo, clone repo and run: packit propose-downstream It creates dist-git pull requests with the content of the release and the packit config taken from local clone.	Have a .packit.yaml in dist-git repo, clone repo and run: packit pull-from-upstream It creates dist-git pull requests with the content of the release and the packit config taken from local clone.

Resolving specfile and version

	propose-downstream	pull-from-upstream
Packit Service	Version is retrieved from upstream project release event. Specfile is retrieved from upstream repo.	Version is retrieved from https://release-monitoring.org event. Specfile is retrieved from dist-git repo.
Packit CLI	Version is retrieved from the latest upstream project release tag if not specified. Specfile is retrieved from the upstream repo unless the --local-project option is used.	Version is retrieved from the latest upstream project release tag if not specified. Specfile is retrieved from the local dist-git repo clone.

New upstream release

The process of releasing a new version starts in the upstream repository by creating a new upstream release. 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.

Upload archive to lookaside cache

The upstream archive needs to be downloaded by Packit first and then uploaded to the lookaside cache. By default, Packit downloads sources defined in the specfile that contain URLs. You can override these URLs via sources configuration key.

For Python packages, you can use a GitHub action (example setup of Packit itself) that automatically builds and uploads the archive to PyPI on each new release. Then during propose downstream, Packit tries to download the archive from the provided URL. If the download fails because the upstream archive is not available at the time of running the job, the job is scheduled to be retried later.

If you don't want Packit to upload sources to lookaside cache before the pull request is opened, set upload_sources to false. By disabling the upload, you need to take care of this yourself and the builds triggered by dist-git CI will fail because of the missing archive in the lookaside cache.

Update dist-git content

After saving the archive in the lookaside cache, Packit updates the dist-git content (mainly sources file and spec file) via pull requests for the specified branches. You can configure which files in the upstream repo should be copied to dist-git during an update via files_to_sync configuration key.

The version in the spec file is set to the version that Packit gets from the upstream tag corresponding to the release that triggered the job. If the version and tag differ, you can specify the upstream_tag_template configuration option so that Packit can extract the correct version.

The changelog entry generated by default is - Update to version <version> followed by a reference to the bugzilla about new release (if there is one). If you use copy_upstream_release_description: true, the changelog entry will use the GitHub/GitLab release description field. (Just make sure the formatting is compatible with spec file. E.g. use - instead of * for lists to not create multiple changelog entries.) There is also sync_changelog configuration option to enable syncing the whole changelog. You can also utilize a custom changelog-entry action if you would like to override the default behaviour.

    actions:
      changelog-entry:
        - bash -c 'echo "- New release ${PACKIT_PROJECT_VERSION}"'

Besides the configuration of changelog via Packit, you can also use %autochangelog macro to generate the changelog entries automatically, see details. In that case, Packit will not touch the changelog at all.

Be aware that Packit does not sign-off its commits so it can't open pull requests if the Enforce signed-off commits in pull-request option is set in the dist-git project settings.

After Packit successfully creates the dist-git pull requests, it's on downstream CI systems and maintainer(s) to check the changes and merge the pull requests.

Customization

For customization of the propose_downstream/pull_from_upstream, you may need to define additional configuration options, most commonly:

• If the version from release monitoring and Git tag differ, you should specify the upstream_tag_template.

• You can configure which files (if any) in the upstream repo should be copied to dist-git during an update via files_to_sync configuration key.

• By default, Packit downloads sources defined in the spec file that contain URLs. You can override these URLs via sources configuration key.

• You may utilise some of the actions for overriding the Packit default behaviour, for example:

  • for the changelog entry generation, if you do not want the default Update to version <version>, you can use your own command(s) (here, the first one gets the git log between the corresponding tag and the tag before that one and the second command links the bugzilla(s)):

    changelog-entry:
      - bash -c 'git log --no-merges --pretty="format:- %s (%an)" $(git describe --tags --abbrev=0 ${PACKIT_PROJECT_UPSTREAM_TAG}^)..${PACKIT_PROJECT_UPSTREAM_TAG} --'
      - bash -c '[ -z "$PACKIT_RESOLVED_BUGS" ] || echo ${PACKIT_RESOLVED_BUGS} | tr " " "\n" | sed "s/^/- Resolves /"'

  • for a custom commit message for commit created by Packit:

    commit-message:
      - bash -c 'echo -e "Rebase to new upstream release ${PACKIT_PROJECT_VERSION}\n"'
      - bash -c '[ -z "$PACKIT_RESOLVED_BUGS" ] || echo ${PACKIT_RESOLVED_BUGS} | tr " " "\n" | sed "s/^/- Resolves /"'

Keeping dist-git branches non-divergent

Packit currently syncs the release in a way that the branches become divergent (you can follow the request to change this behaviour here).

However, if you wish to keep your dist-git branches in sync, you can configure Packit to propose updates exclusively to rawhide (by specifying dist_git_branches: fedora-rawhide) and you can locally merge it with the stable release branches. The following example demonstrates how to achieve this for a single branch (f39 in this case):

# Clone the dist-git repository if you haven't done so already
fedpkg clone $PACKAGE
# or
git clone ssh://$YOUR_USER@pkgs.fedoraproject.org/rpms/$PACKAGE.git

# Alternatively, pull the rawhide changes only
git pull origin rawhide

# Switch to the desired branch and merge it with the updated rawhide branch
git checkout f39
git merge rawhide
git push origin f39

Koji build job

After having the dist-git content updated, you can easily automate also building in Koji. You can simply configure Packit to react to the new commits in your dist-git repository and create Koji builds by having a Packit configuration (when using propose_downstream job, you can configure Packit to sync the file) in your default branch (usually rawhide) of the dist-git repository that includes a koji_build job. 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.

For a configuration example and retriggering, see dist-git onboarding.

Bodhi update job

Lastly, you can again similarly to Koji builds, configure Packit to react to successful Koji builds and create Bodhi updates by having a Packit configuration in your default branch (usually rawhide) of the dist-git repository that includes a bodhi_update job. 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.

For a configuration example and retriggering, see dist-git onboarding.

Permission overview

The downstream automation is a pipeline of jobs: propose_downstream/pull_from_upstream -> Packit PR merge -> koji_build -> bodhi_update or: dist-git push/non-Packit PR merge -> koji_build -> bodhi_update

This chain can break (resulting in no followup job) if the permissions are not configured correctly in the Packit configuration.

packit PR merge/dist-git push -> Koji build

A Koji build can be triggered by a merged pull request, a direct push or a PR comment.

• If you only merge Packit created pull requests, you don't need to specify other settings.
• If you open your own pull request and you want Packit to automatically trigger a Koji build when you merge it you need to be in the allowed_pr_authors list, even in case the PR contains commits created by Packit. On the other hand, if you want to break the chain because, for example, you want to build the package by yourself in a side-tag then you can create a new pull request containing Packit commits and you have to make sure you are not in the allowed_pr_authors list.
• If you push Packit commits directly to dist-git (not merging Packit pull request) but you still want Packit to react and trigger a Koji build then you need to add yourself to the allowed_committers list; Packit is commit author but you are the committer.
• If you want to trigger a Koji build by a PR comment you need be in the packager dist-git group.

caution

We are solving a bug https://github.com/packit/packit-service/issues/2359 This bug can cause an inconsistent behaviour (you may end up with triggered or not triggered Koji builds, even if your configuration is ok) when you try to reuse Packit commits in new pull requests or direct pushes.

Koji build -> Bodhi update

A Bodhi update is triggered by a finished Koji build or a PR comment.

• If the Koji builds are always submitted by Packit you don't need to specify other settings.
• If you submit the Koji builds on your own, Packit can still automatically create the Bodhi updates but you need to be specified in the allowed_builders list.
• If you want to trigger a Bodhi update by a PR comment you need to have write permissions on the project and be in the packager dist-git group.