Packit Onboarding Guide #
Let’s take a look on how to start using Packit and how to get the most out of it.
This guide is focused on the service use-case, but Packit is also available as a CLI tool,
so you can always try things locally on your own.
Note that running tests in Testing farm infrastructure is not currently supported with the CLI tool.
Unlike the service, CLI uses your own identities when connecting to other service like Copr
or Fedora dist-git.
Packit CLI is NOT a client of the Packit GitHub app,
packit command directly interacts with the services.
To start using Packit, you need to do three things:
- set up integration (so Packit is notified about your activities and can provide feedback)
- be approved (self-done mapping of your forge identity to FAS identity, so we know who you are)
- configure the wanted features
1. Set up Packit integration #
The integration is dependent on the service the upstream project is hosted on. In case you want to use Packit on your downstream repository for downstream jobs (Koji build and Bodhi update), you don’t need to enable anything. Just place your config file into the dist-git repository.
Here are the supported git-forges:
The majority of Packit users host their projects on GitHub, therefore we focus mainly on supporting the GitHub App. All of our workflows are supported and tested on GitHub. We utilize the majority of new GitHub features that can be used in GitHub Apps.
How to set up Packit on GitHub #
- Navigate to the “Packit-as-a-Service” GitHub application.
- Under “Pricing and setup”, click “Install it for free”.
- Click “Complete order and begin installation”.
- Install the “Packit-as-a-Service” to repositories of your choice.
Once installed, you will see the “Packit-as-a-Service” GitHub application in your project settings. In the left sidebar, click “Integration & services” and you will see the application displayed there.
Staging instance #
Packit-as-a-Service-stg GitHub App runs the latest code. It can be used to verify the latest changes until they get (every Tuesday) into the production instance. If you want to enjoy the freshest features and help us with the development, see more details here.
GitLab support is mainly experimental and is influenced by the presence of CentOS Stream source-git workflow. We do not verify the functionality of the GitLab support on a day-to-day basis as we do with the GitHub App. Most of the code is forge-independent so you can use the very same functionality both on GitHub and GitLab. The only difference is the setup and small UI differences because of the limits of the specific forge. You can use Packit on any GitLab instance, if:
- The GitLab instance is publically available.
- Packit has an identity for that instance.
gitlab.gnome.org, but let us know if you need any other instance to be supported.)
How to set up Packit on GitLab #
GitLab doesn’t have an app functionality, and we don’t use the Integrations as it doesn’t solve authentication. To enable Packit, you need to manually configure a webhook.
- Go to
Settings → Webhooksand add https://prod.packit.dev/api/webhooks/gitlab or https://stg.packit.dev/api/webhooks/gitlab as the
Merge request eventsand
Release eventsas the
Triggers. Do not provide
Secret tokenyet and click
Add webhook. You should see the created hook at the bottom of the page now.
Testand for example
Push event. At the top of the page appears a red
Hook executed successfully but returned HTTP 401 "X-Gitlab-Token not in request.headers".
- Wait a bit and check
Issuesof the project and after a while there should be a new confidential
Packit-Service Authenticationissue with the instructions how to finish the setup. (You need to give Packit user
maintainerpermissions to the project and attach a provided token to the webhooks.)
GitLab Pipelines #
With some limitations (but tweakability) you can also use Packit as a GitLab pipeline
using the Packit’s CLI from the regularly built
As you can see in the following example, it’s really straightforward and explicit:
image: quay.io/packit/packit srpm_build: stage: build script: - packit srpm artifacts: paths: - "*.src.rpm" expire_in: 1 week
We have rudimentary support for the Pagure instances since they are used in the downstream workflow. Packit cannot be set up as a CI (in the same sense as on GitHub or GitLab) on Pagure instances, since the demand for this feature is not significant. The differences between GitHub/GitLab and Pagure APIs would result in many workarounds having to be implemented, if it would be possible at all. You can track the progress in the related issue on GitHub.
2. Approval #
As a next step, you need to have a valid Fedora Account System
account to be able to start using Packit Service in an upstream project.
For GitHub, we have an automated way of self-approval,
for other instances, contact us, and we will approve you manually.
We require our new users to have
GitHub Username field set in the FAS account so that we can automatically
check for the match between the
GitHub Username field in the FAS account and the GitHub account that triggers the verification.
(If you don’t know, where to set this value,
the URL looks like this:
During the installation, we try to check the FAS account with the same username as the GitHub account that triggers the installation and if the check fails, we create a new issue in our allowlist tracker. (You will be tagged in that issue and should get a GitHub notification about that.)
You can provide the FAS account in a comment
/packit verify-fas <my-fas-username> in the issue we create
for your installation. This will trigger the automatic check.
Until that, you will get a neutral status with
Namespace is not allowed!
message on your commits.
- If you want to configure builds via Packit, your software needs to comply with Copr guidelines since we use Fedora Copr for the builds. Therefore, please, make sure you read them before configuring the Packit build job.
- If you are interested in using internal instance of the Testing Farm to run your tests in, please, reach out to us, since for this job, an additional approval on our side is needed.
- For retrying the build and test jobs via
/packit testpull request comments, you need to have write access to the repository or be the author of the pull request.
- Similarly, for retrying the propose downstream job via
/packit propose-downstreamissue comment, you need to have write access to the repository.
3. Configuration #
Packit uses a configuration file to let Packit know what to do, when to do it and how. As a format, it uses YAML and here are all the valid names:
And where do you need to place this config file? Whenever you need to use Packit – the concept is easy: Packit loads the config file from the repository and commit related to the event it reacts to. E.g. if Packit reacts to a pull request, it takes config from the HEAD commit of the pull request, if Packit works with releases, the release commit is used and if Packit works with downstream Koji build, the respective dist-git commit is used.
You know how to call this file, where to put it, but what should you fill inside?
In the following parts, we will cover some basic concepts used in the Packit config file. More details can be found on a dedicated configuration page.
Basic configuration #
You need to provide some basic information to let Packit understand your project and package.
You can use
packit init command (when running Packit locally) to get a basic structure.
It will look like this (name of the package is guessed from the directory name):
# See the documentation for more information: # https://packit.dev/docs/configuration/ specfile_path: package.spec # add or remove files that should be synced files_to_sync: - package.spec - .packit.yaml # name in upstream package repository/registry (e.g. in PyPI) upstream_package_name: package # downstream (Fedora) RPM package name downstream_package_name: package
We know that every project is a bit different and Packit can’t guess everything so you can (re)define various other options. The full list can be found here.
Version handling #
There are a few version-related config options you might need to set:
upstream_tag_template: Specifies a format of upstream tags if it doesn’t contain just a version.
get-current-versionaction: Command to get a project version in the current state of the project.
release_suffix: Used to influence release field of artifacts provided by Packit.
Packit’s feature set is really wide and does not need to be used as a whole pipeline.
To let user decide what and when should run, Packit uses concept of so-called
Each job represents a feature of Packit. All the jobs are defined under the
For each job you need to specify the following information:
job: the type of the job, the feature you want Packit to do.
trigger: when the job is run (
- additional information needed for the job (like what targets to build, for what branch to run the job,…)
(Note that for each job, not all the triggers are supported.)
As an example you can take a look at the following config snippet
(these are also the default jobs used if you don’t set the
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
Most of the attributes can be defined both on global level (outside the
or for a single job only (like e.g.
targets in the snippet above).
More about this overriding mechanism can be found here.
Another useful feature are aliases used to avoid
hardcoded values that changes when there is a new distribution release.
Available jobs #
copr_build: An RPM build triggered for pull-requests, new branch commits or releases. (Can be used to verify that package is buildable, to easily install package including the proposed change or to provide long-term Copr repositories.)
tests: Test suit using TMT/FMF definition run in the Testing Farm (Can be used as a next step to Copr build or without build at all.)
upstream_koji_build: A scratch Koji build triggered for the upstream state of project.
propose_downstream: For upstream release, Packit prepares a Fedora release. (Source is saved to the Lookaside Cache and a dist-git pull-request is created for each configured branch.)
koji_build: A downstream Koji build triggered when there is a new dist-git commit in a given branch.
bodhi_update: A Bodhi update created for a successfully finished Koji build.
More about the jobs and how to tweak them can be found on a configuration page.
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.
How to try that for real #
In order to start using Packit, we suggest you install the tooling locally. All
the logic is baked inside the
packit command - so once
packit srpm (the command
to create a source RPM locally from the current snapshot of the project) starts
passing for you, it should work inside packit service as well.
RPM builds pass on your laptop #
Packit needs an RPM spec file to build your package. The spec file does not need to be included in the upstream repo and can be generated on the fly or downloaded (e.g. from Fedora dist-git). Please check out our FAQ to read about some other common questions.
You can also read more about the SRPM process
in the document dedicated to the
Running from the dist-git repository #
When you are not allowed or do not want to run packit command from the upstream
git repository, you can run commands from the cloned dist-git repository in the
same way as you do from upstream. Make sure, that you specify the
upstream_project_url in your configuration.
packit srpm finally passing? If not, feel free to reach out to us.
If yes, let’s proceed to the next level.
The project has successful builds inside the service #
If a SRPM can be created locally, all should be good in the service as well.
That’s the theory. In practice, your laptop and packit service
environment are vastly different. For installations made before September 6, 2022,
Packit’s own sandboxing system is used – there, your commands are run as unprivileged user
and you can’t install anything or perform any privileged operation.
If you want to tweak the environment,
you can do the SRPM builds in Copr environment instead.
There, you can specify the requirements yourself.
This is the default for installations made since September 6, 2022,
but the change can also be done by specifying
(We are planning to move there all the builds in the future.)
In any case, feel free to reach out to us if you are having troubles,
and we’d be glad to help.
As described above, Packit supports various functions in form of jobs you can configure.
Let’s try the most favourite one: Copr build.
In order to get RPM builds for every change in your project, you need to add a
jobs inside your .packit.yaml and set up a
copr_build job to do RPM builds for
every change in a PR:
jobs: - job: copr_build trigger: pull_request targets: - fedora-all
fedora-all stands for all currently available Fedora releases.
Jobs are nicely described over here.
If you are looking for an inspiration for your .packit.yaml, check packit’s config file since we try to use all the latest features.
Check that Packit works #
With the configuration above, Packit will build your changes and provide them as RPMs. Once you create a pull request, Packit will:
- Check out the PR.
- Merge it to the target branch (this can be configured by the
- Submit a build using the code that results from the merge in the Copr build system in Packit’s namespace.
- Report results about the Copr build status to the pull request.
An example of Packit’s checks in a pull request:
How to re-trigger Packit actions in your pull request? #
In general, you can put a
/packit <job-you-want-to-trigger> comment
to trigger the Packit job manually.
So for Copr builds, Packit is able to trigger new builds based on a pull request comment:
or the shorter version
So whenever you run into a flake or feel like you want to retrigger, just type that comment into the PR and enjoy some fine, fresh builds.
propose_downstream, you need to place that comment to any issue.
The requirements stated above apply, so if you see this message
Only users with write or admin permissions to the repository can trigger Packit-as-a-Service
it means the author of the pull request does not have write access to the
repository so the build cannot be scheduled. This is a perfect case for
maintainers of the repository to post
/packit build in the PR to get a build.
In GitHub Checks interface, it is also possible to re-trigger a specific task just by clicking on
for the particular check:
Or it is possible to re-trigger every failed task using a pull request comment
which builds only failed builds and similar for testing farm
to re-trigger every failed test.
Packit handles Fedora updates for you. #
So you already have a
jobs section in your config. Let’s extend it with another
jobs that will handle the Fedora updates:
These are explained in detail in our release guide.
And that’s about it. Now you should be able to use the core features of the Packit. If you have any questions, feel free to reach out to us.
We welcome all kinds of suggestions to this guide, feel free to open a new issue here.