From 88b334bd977bca4a474ec5a03223c967ad9826be Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:29 +0000 Subject: [PATCH 1/11] Add documentation on best practices to use the centos namespace on gitlab Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md new file mode 100644 index 0000000..adf72ff --- /dev/null +++ b/docs/gitlab.md @@ -0,0 +1,81 @@ +# Best practices for the usage of the CentOS namespace on gitlab + +This document highlights the best practices SIGs interested in using the CentOS namespace on gitlab.com +should follow. + +## Login in + +To login via ACO on gitlab.com, you must use the following link: + +## Content + +Any and all content hosted on gitlab.com should follow the Requirements the CentOS project has specified +for SIGs: [https://wiki.centos.org/SpecialInterestGroup#Requirements](https://wiki.centos.org/SpecialInterestGroup#Requirements) + +## Access + +It is expected that access levels are managed via groups on accounts.centos.org (ACO). There are different +ways this can be achieved. + +### Simple case + +For SIGs who are fine with everyone getting the same level of access, a single group can be created on +https://accounts.centos.org where all the SIG members will be added. This group can then be mapped to that +SIG’s namespace under gitlab.com/centos and be given `owner` access level. + +This means, everyone added to this group on accounts.centos.org will be granted `owner` access to each and +every project placed under that SIG’s namespace. This also means, that anyone **not** in this group will have +no access at all. + +### More complex case + +For SIGs who want or need a more fine tuned model, it is recommended that they create a `groups` namespace under +the SIG’s namespace. In the group namespace will be placed all the groups needed by the SIG and each of this +group will be mapped to a corresponding group on ACO. There should be no project under the `groups` namespace. +The groups can then be given access to any project and the access level of the group can be picked on a +per-project basis. + +Here is an example of the structure recommended for the complex case: + +``` +SIG's namespace +│ +├── groups +│ ├── group1-developers [grp1] +│ ├── group2-maintainers [grp2] +│ └── sig [sg] +│ +├── rpms +│ └── pkg [grp1+grp2] +│ +├── src +│ └──source_tree [grp1] +│ +└── sig [sg] +``` + +## Group membership refresh + +To login via ACO on gitlab.com, you must use the following link: + +Group memberships are refreshed upon login into gitlab.com. So if someone is added to a group in ACO, they +will need to visit that link again: XXX to have their membership refreshed. + +## Group names + +It is expected that groups on ACO that are created to manage access on gitlab.com should follow the +corresponding pattern: `-gitlab-` + +Some examples: + +- hyperscale-gitlab-maintainers +- automotive-gitlab-kernel-maintainer +- automotive-gitlab-sig-owner +- docs-gitlab-members +- … + +## Requesting a namespace or a group + +To request a namespace under gitlab.com/centos or the creation of a group on ACO, simply open a ticket at: +[https://pagure.io/centos-infra/](https://pagure.io/centos-infra/) + diff --git a/docs/index.md b/docs/index.md index 8c8ddb8..e147ba0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,3 +13,4 @@ You'll find on this (always involving) website best practices for each step in t * How to [push to mirror](delivery.md) network * How to create a CentOS [spin](spin.md) * Rules for [dns entries](dns.md) under sig.centos.org + * Using the [CentOS namespace on gitlab.com](gitlab.md) diff --git a/mkdocs.yml b/mkdocs.yml index 135e4a8..665c6ee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ nav: - delivery.md - dns.md - SIG's spin: spin.md + - Using GitLab: gitlab.md theme: name: material From d7f0c2d01b9962bafaffb8c9c0b7879be4621d78 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 2/11] Add the URL to login on gitlab via ACO Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index adf72ff..6ba1214 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -5,7 +5,7 @@ should follow. ## Login in -To login via ACO on gitlab.com, you must use the following link: +To login via ACO on gitlab.com, you must use the following link: [https://id.centos.org/gitlab](https://id.centos.org/gitlab) ## Content @@ -57,6 +57,7 @@ SIG's namespace ## Group membership refresh To login via ACO on gitlab.com, you must use the following link: +[https://id.centos.org/gitlab](https://id.centos.org/gitlab) Group memberships are refreshed upon login into gitlab.com. So if someone is added to a group in ACO, they will need to visit that link again: XXX to have their membership refreshed. From 0c5da930c48002fe207b98390de89e27f23d48bc Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 3/11] Adjust the template to follow for group names Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index 6ba1214..9d6822e 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -65,14 +65,14 @@ will need to visit that link again: XXX to have their membership refreshed. ## Group names It is expected that groups on ACO that are created to manage access on gitlab.com should follow the -corresponding pattern: `-gitlab-` +corresponding pattern: `gitlab--(-)` Some examples: -- hyperscale-gitlab-maintainers -- automotive-gitlab-kernel-maintainer -- automotive-gitlab-sig-owner -- docs-gitlab-members +- gitlab-centos-hypsercale-maintainers +- gitlab-centos-automotive-kernel-maintainer +- gitlab-centos-automotive-sig-owner +- gitlab-centos-docs-members - … ## Requesting a namespace or a group From 5d7bff2e90dffcfcd022bec9b56893f608e56c8c Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 4/11] Explain that the pattern for group names applies to the more complex SIGs Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index 9d6822e..f3741ec 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -64,8 +64,9 @@ will need to visit that link again: XXX to have their membership refreshed. ## Group names -It is expected that groups on ACO that are created to manage access on gitlab.com should follow the -corresponding pattern: `gitlab--(-)` +For SIGs using the more complex case where multiple groups are required or desired, it is expected that the +extra groups created on ACO to manage access on gitlab.com should follow the corresponding pattern: +`gitlab--(-)` Some examples: From 43667fe6ee1d585d8dee985d89ae2a60fa3f2be2 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 5/11] Invite people to create a gitlab account before associated it to ACO Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index f3741ec..f3677ad 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -5,7 +5,17 @@ should follow. ## Login in -To login via ACO on gitlab.com, you must use the following link: [https://id.centos.org/gitlab](https://id.centos.org/gitlab) +The first thing to understand is that gitlab will "link" an existing account +with third party authentication system. In other words, you need to have a +gitlab account and be logged in onto gitlab.com before you can associate your +account with the CentOS Account System (ACO). + +So if you do not have a gitlab account, create one. Then visit the following +link [https://id.centos.org/gitlab](https://id.centos.org/gitlab) to associate +your account with CentOS' Account System. + +From there on, everytime you visit this link, your group membership defined in +ACO, will be refreshed on gitlab. ## Content From 11046d2f3f4be0746df826c370267638ca6bc9a6 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 6/11] Tweak some more the pattern to use for group names Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index f3677ad..455546e 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -76,14 +76,14 @@ will need to visit that link again: XXX to have their membership refreshed. For SIGs using the more complex case where multiple groups are required or desired, it is expected that the extra groups created on ACO to manage access on gitlab.com should follow the corresponding pattern: -`gitlab--(-)` +`gitlab--sig-(-)` Some examples: -- gitlab-centos-hypsercale-maintainers -- gitlab-centos-automotive-kernel-maintainer -- gitlab-centos-automotive-sig-owner -- gitlab-centos-docs-members +- gitlab-centos-sig-hypsercale-maintainers +- gitlab-centos-sig-automotive-kernel-maintainer +- gitlab-centos-sig-automotive-sig-owner +- gitlab-centos-sig-docs-members - … ## Requesting a namespace or a group From 03562e5dfeb7e5258ae142c8e4d65c9333a38446 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 7/11] Move the section about linking ACO to gitlab to the Auth page Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/auth.md b/docs/auth.md index 8d4602f..f253ff1 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -83,4 +83,17 @@ If you've signed up with the account name `tuser`, you can generate your new cer Important note WRT OTP: If you have enabled Two Factor auth, you absolutely need to get a valid kerberos ticket through other step *before* using centos-cert. See details on the [Fedora Accounts Documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/user/#twofactor) for this - +## Linking your CentOS account to gitlab + +The first thing to understand is that gitlab will "link" an existing account +with third party authentication system. In other words, you need to have a +gitlab account and be logged in onto gitlab.com before you can associate your +account with the CentOS Account System (ACO). + +So if you do not have a gitlab account, create one and log with it into [ +https://gitlab.com](https://gitlab.com). Then visit the following link [ +https://id.centos.org/gitlab](https://id.centos.org/gitlab) to associate your +account with CentOS' Account System. + +From there on, everytime you visit this link, your group membership defined in +ACO, will be refreshed on gitlab. diff --git a/docs/gitlab.md b/docs/gitlab.md index 455546e..70e53d8 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -5,17 +5,8 @@ should follow. ## Login in -The first thing to understand is that gitlab will "link" an existing account -with third party authentication system. In other words, you need to have a -gitlab account and be logged in onto gitlab.com before you can associate your -account with the CentOS Account System (ACO). - -So if you do not have a gitlab account, create one. Then visit the following -link [https://id.centos.org/gitlab](https://id.centos.org/gitlab) to associate -your account with CentOS' Account System. - -From there on, everytime you visit this link, your group membership defined in -ACO, will be refreshed on gitlab. +Instructions on how to link your CentOS account with a gitlab account can be +found in our [Authentication page](auth.md#linking-your-centos-account-to-gitlab). ## Content From 02c4171a05a77753df93ed6b77818b3ab691176e Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 8/11] Fix placeholder link Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/gitlab.md b/docs/gitlab.md index 70e53d8..61b5b39 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -61,7 +61,8 @@ To login via ACO on gitlab.com, you must use the following link: [https://id.centos.org/gitlab](https://id.centos.org/gitlab) Group memberships are refreshed upon login into gitlab.com. So if someone is added to a group in ACO, they -will need to visit that link again: XXX to have their membership refreshed. +will need to visit that link again: [https://id.centos.org/gitlab](https://id.centos.org/gitlab) +to have their membership refreshed. ## Group names From f8825f81f838fb9ef71586f4b0ef403dd94a83dd Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 9/11] Drop trailing spaces Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/auth.md b/docs/auth.md index f253ff1..0a2af93 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -1,10 +1,10 @@ -# Authentication +# Authentication ## Creating your account You can create your account on our community portal running on [https://accounts.centos.org](https://accounts.centos.org). -To register/create an account, just click on "Register" on the portal and follow the process. +To register/create an account, just click on "Register" on the portal and follow the process. More information and user documentation is available on consolidated [online documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/) for the portal ## Modifying your account @@ -20,7 +20,7 @@ Some settings you can modify directly: * other personal details * your password * adding/removing OTP tokens (see below for 2FA) - * ssh and gpg public keys + * ssh and gpg public keys ### Enabling 2FA on your account (optional) It's adviced (but not mandatory) to implement 2 Factor Authentication on your account (for some critical accounts, that's though required). @@ -30,7 +30,7 @@ You can add one (or more, adviced) OTP tokens on your profile. Known to work sol * Yubikey (4 and above, that supports OTP) : through rpm pkg yubioath-desktop * FreeOTP (available on Google Play Store) * OTPClient (available as rpm pkg and flatpak/flathub) - * others (list is non exhaustive) + * others (list is non exhaustive) More informations about 2FA is available on specific [portal documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/user/#twofactor) @@ -60,7 +60,7 @@ Your user certificate bundle comes in the form of 1 file: To generate your certificate you can use the 'centos-cert' tool included in the centos-packager package: ``` - centos-cert + centos-cert You need to call the script like this : /usr/bin/centos-cert -arguments -u : username ([REQUIRED] : your existing ACO/FAS username) @@ -73,10 +73,10 @@ You need to call the script like this : /usr/bin/centos-cert -arguments If you've signed up with the account name `tuser`, you can generate your new certificate like this: ``` - [tuser@myworkstation]$ centos-cert -u tuser + [tuser@myworkstation]$ centos-cert -u tuser ``` -!!! note +!!! note Attention that centos-cert -u tuser will request a new certificate, so that will automatically revoke any other certificate you had in the past. If you need to use cbs/koji on multiple machines, just copy the files mentioned above on the other machine. !!! warning From 12da4d933dd6e509aebd81a74c8bb832a61b1540 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:15:31 +0000 Subject: [PATCH 10/11] Improve the navigation menu to link to the git and cbs docs Signed-off-by: Pierre-Yves Chibon --- diff --git a/mkdocs.yml b/mkdocs.yml index 665c6ee..05c181a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,9 +7,8 @@ repo_name: centos/sig-guide nav: - index.md - Authentication: auth.md - - Building: - - git.md - - cbs.md + - Lookaside/Git: git.md + - Building in CBS: cbs.md - ci.md - delivery.md - dns.md From fea7395741a814a6870d4540ac39cb9dc3bff59b Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 21 2022 10:52:58 +0000 Subject: [PATCH 11/11] Start documenting the changes made to the build infrastructure This includes the changes made to the lookaside cache, the changes made to use the flat dist-git layout in the git repositories as well as the changes that using gitlab.com to host the git repositories bring Signed-off-by: Pierre-Yves Chibon --- diff --git a/docs/git.md b/docs/git.md index d43d6b9..a9f8cf0 100644 --- a/docs/git.md +++ b/docs/git.md @@ -1,19 +1,29 @@ -# Git/lookaside +# Lookaside/git -Package sources checked into git.centos.org are in exploded SRPM format. This means that the package working directory should have at least a SPECS/ subdirectory. +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. -## New Package (from source) +It should be noted that two model exists, the "traditional" model and the one +based on CentOS Stream and Fedora. While both model can be intertwined in some +places, it is recommended that SIGs pick a model and follow it. This documentation +will not cover which aspect of which model is compatible with the other one. -If the package you'd like to build isn't yet on https://git.centos.org, create first a ticket on https://pagure.io/centos-infra/issues to request the git repo for /rpms/ to be created +## New Package (from source) -Once it will be created, it will be possible for you to push to *specific* branches, based on the following rules: c{7,8}-* +If you SIG uses [https://git.centos.org](https://git.centos.org) and the package +you want to build is not there yet, you will have to create a ticket first at: +[https://pagure.io/centos-infra/issues](https://pagure.io/centos-infra/issues) +to request that the git repo for `/rpms/` be created. -So that means that if I'm member of the sig-core group (in ACO), I'll be able to commit/push to c8-sig-core or c8-sig-core-whatever-I-want branches +If your SIG uses [https://gitlab.com/CentOS](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. -Let's use the following example : I need to create a branch for pkg centpkg-minimal, and I'm member of the sig-core SIG group. We have to push two things to git.centos.org : +In the rest of the document we will use the following example : Build the package `centpkg-minimal`, +as a member of the `sig-core` SIG group. We have to push two things: - * .spec files to build a src.rpm - * eventually blob (.tar.gz archive) that will need to be pushed to lookaside cache + * the .spec file to build the rpm, to the git repository + * eventually an archive (.tar.gz, .tar, .xz...) of the sources, to lookaside cache !!! warning To push to lookaside cache you need to have already a local check out from [https://git.centos.org/centos-git-common](https://git.centos.org/centos-git-common) @@ -23,29 +33,51 @@ Let's use the following example : I need to create a branch for pkg centpkg-mini Let's assume that my pkg centpkg-minimal that I want to build has an archive called centpkg.minimal.tar.gz. To be able to push to lookaside cache, we need the following : * a valid TLS cert (also needed to build on cbs.centos.org) obtained through [centos-cert](../auth/) util - * lookaside_upload script in your $PATH (coming from centos-git-common git repo, see above) + * either script `lookaside_upload` or `lookaside_upload_sig` in your $PATH (coming from centos-git-common git repo, see above) + +There are two path available for the lookaside cache, each is available using a different script: + +- `lookaside_upload` allows uploading to the traditional CentOS Linux structure: `baseurl/pkgname/branch/hash` ([example]( +https://git.centos.org/sources/kernel/c8s/0c4e10577cfd4b4f8e3d83c0406da8ab05eb775f)) +- `lookaside_upload_sig` allows uploading to the same lookaside structure as the one used by CentOS Stream and Fedora: `baseurl/pkgname/tarball/hashtype/hash/tarball` ([example]( +https://sources.stream.centos.org/sources/rpms/kernel/linux-5.14.0-62.el9.tar.xz/sha512/f7aeac0fe5bf594933cd35b7ecc94ea8ddcbfedc04fa769c4da298e7bf105df116375d44711d944c748c85f61f96f6149be34c76eb37f28aa1f16359a9122abf/linux-5.14.0-62.el9.tar.xz)) + +Both scripts need some paramters, simply use `-h` to see them. -This simple script would need some paramters: +Back to our example. + +### Pushing to the "traditional" lookaside structure + +The pkg name is centpkg-minimal, file is centpkg-minimal.tar.gz and I'm member of the sig-core group, and want to build it for c7, so we'll call it like this : ``` -lookaside_upload +lookaside_upload -f centpkg-minimal.tar.gz -n centpkg-minimal -b c7-sig-core +[+] CentOS Lookaside upload tool -> Checking if file already uploaded +[+] CentOS Lookaside upload tool -> Initialing new upload to lookaside +[+] CentOS Lookaside upload tool -> URL : https://git.centos.org +[+] CentOS Lookaside upload tool -> Source to upload : centpkg-minimal.tar.gz +[+] CentOS Lookaside upload tool -> Package name: centpkg-minimal +[+] CentOS Lookaside upload tool -> sha1sum: d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 +[+] CentOS Lookaside upload tool -> Remote branch: c7-sig-core +[+] CentOS Lookaside upload tool -> ====== Trying to upload ======= -You need to call the script like this : ~/bin/lookaside_upload -arguments +################################################################################################################ 100.0% +File centpkg-minimal.tar.gz size 15178 CHECKSUM d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 stored OK +[+] CentOS Lookaside upload tool -> Validating that source was correctly uploaded .... +[+] CentOS Lookaside upload tool -> [SUCCESS] Source should be available at https://git.centos.org/sources/centpkg-minimal/c7-sig-core/d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 - -f : filename/source to upload (required, default:none) - -n : package name for that source (requred, default:none, example "httpd") - -b : "branch" where to upload to (required, default:none, example "c7-sig-core") - -h : display this help ``` -So back to our example, the pkg name is centpkg-minimal, file is centpkg-minimal.tar.gz and I'm member of the sig-core group, and want to build it for c7, so we'll call it like this : +### Pushing to the CentOS Stream/Fedora lookaside structure + +The pkg name is centpkg-minimal, file is centpkg-minimal.tar.gz, so we'll call it like this : ``` -lookaside_upload -f centpkg-minimal.tar.gz -n centpkg-minimal -b c7-sig-core +lookaside_upload_sig -f centpkg-minimal.tar.gz -n centpkg-minimal [+] CentOS Lookaside upload tool -> Checking if file already uploaded [+] CentOS Lookaside upload tool -> Initialing new upload to lookaside [+] CentOS Lookaside upload tool -> URL : https://git.centos.org -[+] CentOS Lookaside upload tool -> Source to upload : centpkg-minimal.tar.gz +[+] CentOS Lookaside upload tool -> Source to upload : centpkg-minimal.tar.gz [+] CentOS Lookaside upload tool -> Package name: centpkg-minimal [+] CentOS Lookaside upload tool -> sha1sum: d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 [+] CentOS Lookaside upload tool -> Remote branch: c7-sig-core @@ -58,14 +90,27 @@ File centpkg-minimal.tar.gz size 15178 CHECKSUM d6616b89617914a0dd0fd5cfa06b0afc ``` -Now that we have uploaded to lookaside cache, we can reference it in our /rpms/centpkg-minimal git repository on git.centos.org, see below +Now that we have uploaded to lookaside cache, we can reference it in our /rpms/centpkg-minimal git repository on git.centos.org, see below + + +## Pushing to git + +SIGs have two options when it comes to the git repositories which can be used as part of dist-git: +- [git.centos.org](https://git.centos.org) +- [gitlab.com/CentOS](https://gitlab.com/CentOS) -## Pushing to git.centos.org +If your SIG wants to use gitlab, they will have to follow the [instructions](gitlab.md) to request one. +Here we'll cover both workflow, assuming the git repository exists on either platform. -We should already have a local checkout of the git repository for the pkg we'd like to work on. In our case, the git repo url is https://git.centos.org/rpms/centpkg-minimal +### Git clone -So the way to git clone/pull over ssh is so ssh://git@git.centos.org/rpms/centpkg-minimal.git : +The first thing you'll need is a local checkout of the git repository for the pkg we'd like to work on. +In our case, the git repo url is `https://git.centos.org/rpms/centpkg-minimal` or +`https://gitlab.com/CentOS//rpms/.git` + +So the way to git clone/pull over ssh is either `ssh://git@git.centos.org/rpms/centpkg-minimal.git` or +`git@gitlab.com:CentOS//rpms/.git`: ``` git clone ssh://git@git.centos.org/rpms/centpkg-minimal.git @@ -78,26 +123,119 @@ Resolving deltas: 100% (2/2), done. ``` !!! important - You can clone over https, but then it wouldn't let you push back to it, as it needs ssh with key verification and based on group membership for acls + On git.centos.org you can clone over https, but then it wouldn't let you push back to it, as it needs ssh with key verification and based on group membership for acls + +### Git branches + +Repositories git.centos.org are used by both Red Hat and CentOS SIG, the structure of the git +repository is used to control the access. SIG members are therefore only allowed to push to branches +following the pattern: `c-sig-*` -Let's create a new c7-sig-core branch (still based on the assumption that I want to build for c7) : +That means that if I'm member of the sig-core group (in ACO), I'll be able to +commit/push to `c7-sig-core`, `c8-sig-core` or `c9s-sig-core-whatever-I-want` branches + +For our example, on git.centos.org we'll have to create a new c7-sig-core branch +(with on the assumption that we want to build for c7) : ``` git checkout -b c7-sig-core ``` -You can now create your SPECS/.spec and add also other text patches under SOURCES/ We still need also to point to /sources/ for the lookaside cache, so we'll use the value of the hash returned when we successfully uploaded to lookaside cache and we'll write a .``.metadata file in the root dir that will look like this in our example: +Since SIGs have full control over their namespace on gitlab.com, that branching structure +is not mandatory. It will, however, be necessary if you plan on using the "traditional" lookaside +structure describe above as this relies on branch names. + +### Git repository layout + +There are two possible structure possible for the repository layout: + +- The exploded SRPM layout +- The flat dist-git layout + +#### The exploded SRPM layout + +This is the "traditional" layout used in CentOS Linux, it is articulated around two folders: ``` -d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 SOURCES/centpkg-minimal.tar.gz +├── SOURCES +└── SPECS ``` -Now that we have pointer to lookaside cache, and also .spec, we can push back to git and we should be able to proceed with the "build-from-git" on cbs.centos.org. Let's commit first : +The `SPECS` folder is meant to receive your spec file and all other text files and +patches would go under `SOURCES`: + +``` +├── SOURCES +│ ├── +│ └── +└── SPECS + └── .spec +``` + +Once done, we still need to link these files with the sources uploaded earlier in the +lookaside cache. See the next section. + +#### 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: + +``` +├── +├── +└── .spec +``` + +### Linking to sources in the lookaside cache + +Here as well, there are two ways you can link a dist-git repository to sources +uploaded to the lookaside cache: + +- the "traditional" way using a `..metadata` file +- the CentOS Stream/Fedora way using a `sources` file !!! important - Even if your package doesn't contain any source pushed to lookaside cache (like for a package just having some small files in SOURCES/ dir, you *need* to have the `..metadata` package present and pushed in git repository + Even if your package doesn't contain any source pushed to lookaside cache + (like for a package just having some small files in SOURCES/ dir, you *need* to + have either a `..metadata` or `sources` file present and pushed in + git repository -Here is what the git repository for a pkg should look like : +#### Using a `..metadata` file + +To use this method, simply create a `..metadata` file with the following +content: +``` + SOURCES/ +``` + +For example: +``` +d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 SOURCES/centpkg-minimal.tar.gz +``` + +#### Using a `sources` file + +To use this method, simply create a `sources` file. The easiest way to achieve +this is: +``` +sha512sum --tag > sources +``` + +Example output: +``` +SHA512 (centpkg-minimal-1.1.0.tar.gz) = f7cfbc956199b1a0342f321a0e4cb055d6ac2c784a8faace43cf80772f0de34b58ede1a02a558cd03e25c14938ac6e17b3746b1919c0bbc1f5b2955472577e4f +``` + +Now that we have pointer to lookaside cache, and also .spec, we can push back to git and +we should be able to proceed with the "build-from-git" on cbs.centos.org. Let's commit first. + +### Git push + +Depending on if you picked the "traditional" structure or the CentOS Stream/Fedora +one, this is how your repository should look like: + +* Traditional layout ``` . @@ -107,21 +245,28 @@ Here is what the git repository for a pkg should look like : │ └── └── SPECS └── .spec +``` +* CentOS Stream/Fedora layout ``` +. +├── sources +├── +├── +└── .spec +``` -You can now push to to git, as usual: +We can now push to to git, as usual: ``` # git add # if needed -git commit -a -git push origin c7-sig-core # to create the c7-sig-core branch on git.centos.org if not existing yet - +git commit -a +git push origin # to create the remote branch if not existing yet ``` -Now that we have our sources pushed to both git.centos.org and lookaside cache, we can now proceed with a build in cbs/koji +Where `` would be `c7-sig-core` for our example using `git.centos.org`. -!!! note - It's worth knowing that the documented process and structure is the default one, aka `rpmbuild style` layout for how your files/sources should be declared in your git repository/branch. But since 2022-02-21, the `flat layout` (as used also on [Fedora](https://src.fedoraproject.org) dist-git server) can also be used on git.centos.org. You still need to push tarballs to lookaside but you can use the flat layout when importing from Fedora/Epel, and it's purely an opt-in choice, and so not the default one that SIGs are using for years now +Now that we have our sources pushed to both git.centos.org and lookaside cache, +we can now proceed with a [build in cbs/koji](cbs.md).