Skip to content

Lookaside/Git

Lookaside/git

This page documents how SIGs can upload the sources of their RPM into the lookaside cache and how they should set-up their corresponding git repository.

It should be noted that a few different repository layouts exist, the "traditional" one and others based on CentOS Stream and Fedora (see Git repository layout below). While these can be intertwined in some places, it is recommended that SIGs pick a layout and follow it. This documentation will not cover which aspect of which layout is compatible with the other ones.

New Package (from source)

If your SIG uses https://gitlab.com/CentOS, you, your SIG chair or people that have been granted access by the SIG chair, will be able to create the project for your package directly.

In the rest of the document we will use the following example : Build the package centpkg-minimal, as a member of the cloud SIG. We have to push two things:

  • the .spec file to build the rpm, to the git repository
  • eventually an archive (.tar.gz, .tar, .xz...) of the sources, to lookaside cache

Important

The recommended way to do both of these is the centpkg-sig command, which wraps git, the lookaside cache upload/download, and CBS build submission into a single tool. Install it with:

dnf install centpkg-sig

(available on Fedora and CentOS Stream through EPEL). You will also still need a valid TLS cert, obtained through the centos-cert util, to upload sources or submit builds.

Cloning your package

Use centpkg-sig clone with --sig/-s to specify your SIG's subgroup on gitlab.com/CentOS:

centpkg-sig clone -s cloud centpkg-minimal
cd centpkg-minimal

This is equivalent to a plain git clone of git@gitlab.com:CentOS/cloud/rpms/centpkg-minimal.git, but it also lets you pass a --branch/-b to check out a specific branch, and knows how to find the repo without having to spell out the full namespaced path. If you'd rather give the full path yourself, that works too:

centpkg-sig clone -b c9s-sig-cloud-okd-4.18 cloud/rpms/centpkg-minimal
Pushing sources to the lookaside cache

Let's assume that my pkg centpkg-minimal that I want to build has an archive called centpkg-minimal.tar.gz. From inside the git checkout, uploading it to the lookaside cache is a single command:

centpkg-sig new-sources centpkg-minimal.tar.gz

This uploads the file to the lookaside cache, updates (or creates) the sources file in your checkout with its checksum, and adds the tarball to .gitignore so it isn't committed to git by mistake. It works no matter which of the repository layouts below your package uses. To download sources that are already referenced by an existing checkout, use:

centpkg-sig sources

Note

Uploads land at baseurl/pkgname/tarball/hashtype/hash/tarball, the same lookaside structure used by CentOS Stream and Fedora (example). Note that only the git hosting for SIG packages moved to gitlab.com — the lookaside cache itself is served from src.sigs.centos.org.

Now that we have uploaded to lookaside cache and have a sources file pointing at it, we can commit and push to git, see below.

Pushing to git

Git hosting for SIG packages lives under gitlab.com/CentOS. If your SIG doesn't have a subgroup there yet, follow the instructions to request one.

Git branches

Since SIGs have full control over their namespace on gitlab.com, no particular branching structure is mandatory, but centpkg-sig understands the conventional c<version>[s]-sig-<signame>[-<project>[-<release>]] pattern (e.g. c9s-sig-cloud-okd-4.18) as well as target-style names such as cloud9s-okd-5.0-el9s, and uses them to work out the CBS build target automatically when you run centpkg-sig build (see Building in CBS).

Git repository layout

centpkg-sig supports any of these layouts for a package's repository, and new-sources/sources will do the right thing for whichever one you use:

  • The exploded SRPM layout
  • The flat dist-git layout
  • The SIG hybrid layout
The exploded SRPM layout

This is the "traditional" layout used in CentOS Linux, it is articulated around two folders:

├── SOURCES
└── SPECS

The SPECS folder is meant to receive your spec file and all other text files and patches would go under SOURCES, linked to lookaside cache via a .<pkg_name>.metadata file at the top level:

├── .<pkg_name>.metadata
├── SOURCES
│   ├── <optional_file>
│   └── <optional_patch>
└── SPECS
    └── <pkg_name>.spec
The flat dist-git layout

This is the layout used in the dist-git repositories in CentOS Stream and Fedora. All files (spec files, text files, patches...) are stored at the top level of the repository, alongside a sources file:

├── sources
├── <optional_file>
├── <optional_patch>
└── <pkg_name>.spec
The SIG hybrid layout

This layout keeps the spec file under SPECS/, like the exploded SRPM layout, but links to lookaside cache with a top-level sources file instead of a .metadata file:

├── sources
└── SPECS
    └── <pkg_name>.spec

Important

Even if your package doesn't contain any source pushed to lookaside cache (like for a package just having some small files alongside the spec), you need to have either a .<pkg_name>.metadata or sources file present and pushed in the git repository. centpkg-sig new-sources creates and maintains this file for you, so you shouldn't need to edit it by hand.

Git push

We can now push to git, as usual:

git add <files>   # spec file, sources/.metadata file, patches, etc.
git commit
git push origin <branch>   # to create the remote branch if not existing yet

Now that we have our sources pushed to both gitlab.com and the lookaside cache, we can proceed with a build in cbs/koji, using centpkg-sig build.