AUR publishing
How posprint is published to the Arch User Repository (AUR).
> Since the move to BlueGit, the release and publish:aur jobs in blue-ci-cd.yml do this (source: BlueGit tag archive, binary: BlueGit release asset). The GitLab-specific notes below are kept for history; secrets are BlueGit repository secrets with the same names.
Chosen approach
This repository keeps three Arch package definitions:
packaging/arch/PKGBUILD: local builds and GitLab artifact builds (.pkg.tar.zst)packaging/aur/PKGBUILD: AUR source package (posprint), built by the AUR user from the GitLab tag tarballpackaging/aur-bin/PKGBUILD: AUR binary package (posprint-bin), installs a prebuiltusr/tree from GitLab CI
The source package downloads:
https://gitlab.com/Timfa/posprint/-/archive/<version>/posprint-<version>.tar.gz
The binary package downloads the Generic Package Registry tarball (durable; does not depend on job-artifact permalinks):
https://gitlab.com/api/v4/projects/Timfa%2Fposprint/packages/generic/posprint/<version>/posprint-<version>-x86_64.tar.gz
Do not use /-/jobs/artifacts/<tag>/raw/...?job=build:linux-arch. That permalink only serves the latest successful pipeline for the tag, so it 404s while the tag pipeline is still running and after a later job (for example AUR publish) fails.
That tarball is packed from the non-debug Arch CI package (usr/ only). posprint and posprint-bin conflict; posprint-bin provides posprint.
Files in this repo
| Path | Purpose |
|---|---|
packaging/aur/PKGBUILD | AUR source package template |
packaging/aur/.SRCINFO | Initial generated metadata (source) |
packaging/aur-bin/PKGBUILD | AUR binary package template |
packaging/aur-bin/.SRCINFO | Initial generated metadata (binary) |
scripts/make-linux-bin-tarball.sh | Pack usr/ from the non-debug .pkg.tar.zst for posprint-bin |
scripts/publish-gitlab-release.sh | Upload dist/ files to the Generic Package Registry and attach them to the GitLab Release |
scripts/publish-aur.sh | Update both AUR repos (posprint and posprint-bin) |
scripts/aur-ssh-setup.sh | Install SSH key from GitLab File or base64 variable |
scripts/bootstrap-aur-repo.sh | One-time initial push to create an AUR repo |
.gitlab-ci.yml | Builds the binary tarball and runs AUR publish on tags |
Release flow
When a Git tag is pushed:
1. GitLab builds the normal release artifacts, including posprint-<version>-x86_64.tar.gz from the non-debug Arch package. 2. release:gitlab uploads those files to the Generic Package Registry and creates/updates the GitLab Release (download URLs stay valid even if a later job fails). 3. GitLab runs scripts/publish-aur.sh "$CI_COMMIT_TAG" with needs: artifacts from build:linux-arch (the tarball is already in dist/). 4. The script:
- downloads the tagged source tarball and hashes it
- uses the CI binary tarball from
dist/(or, if missing, the Generic Package Registry) and hashes it - clones each AUR repo (
posprint,posprint-bin), or creates it on first push - updates
pkgver,pkgrel, andsha256sums - regenerates
.SRCINFOviamakepkg --printsrcinfo(as non-rootaurbuildwhen CI runs as root; parent tempdir is made traversable andBUILDDIRis forced under that user) - strips a leading
vfrom the tag when resolving GitLab URLs - commits and pushes to each AUR
master
publish:aur has allow_failure: true so an AUR outage cannot mark the whole tag pipeline failed (that used to 404 every jobs/artifacts/<tag> download). Prefer the job succeeding.
Refreshing tag 0.5.7 (or any already-pushed tag)
CI YAML is read from the tagged commit. Retrying jobs on an old 0.5.7 pipeline will not pick up these fixes.
After this change is on master:
1. Delete the GitLab Release for 0.5.7 if it still exists (Deploy → Releases), or let the new pipeline update it. 2. Delete and recreate the tag on the merge commit:
git checkout master
git pull origin master
git tag -d 0.5.7
git push origin :refs/tags/0.5.7
git tag 0.5.7
git push origin 0.5.7
3. Wait for the new tag pipeline. Source AUR posprint is already 0.5.7; a retag changes the GitLab archive hash, so publish will push an updated sha256sums (same pkgver, not a second version bump). posprint-bin was never published for 0.5.7 and will be created on the first successful run.
Do not only retry publish:aur on the failed 0.5.7 pipeline — that job still has no dist/*.tar.gz and still curls a 404 permalink.
Alternative if you do not want to move the tag: bump to 0.5.8 and tag that instead.
GitLab CI secrets
GitLab masked variables cannot contain spaces or newlines. An OpenSSH private key is multiline, so do not paste the raw private key into a masked Variable.
Use exactly one of these setups (do not mix File + base64 unless using the auto-detect path below):
Option B — Variable + base64 (maskable; recommended from Windows)
GitLab Masked variables cannot contain newlines. From Windows, pasting a raw key into a File variable often introduces CRLF, which makes Linux OpenSSH report Load key: invalid format.
Generate LF-normalized base64 of the entire key file (including BEGIN/END):
$path = "$env:USERPROFILE\.ssh\id_ed25519_aur_ci"
$text = [IO.File]::ReadAllText($path) -replace "`r`n", "`n" -replace "`r", "`n"
if (-not $text.EndsWith("`n")) { $text += "`n" }
$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text))
$b64
# Verify (must print BEGIN line):
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64)).Substring(0, 35)
| Variable | Type | Value |
|---|---|---|
AUR_SSH_PRIVATE_KEY_B64 | Variable (not File) | The single-line $b64 string; Masked + Protected |
Also set AUR_GIT_AUTHOR_NAME and AUR_GIT_AUTHOR_EMAIL. Remove AUR_SSH_PRIVATE_KEY if it is also set (B64 is preferred by the setup script).
Option A — File + raw key
| Variable | Type | Value |
|---|---|---|
AUR_SSH_PRIVATE_KEY | File | Full private key text, including -----BEGIN OPENSSH PRIVATE KEY----- / END lines |
AUR_GIT_AUTHOR_NAME | Variable | Your name |
AUR_GIT_AUTHOR_EMAIL | Variable | Your email |
Mask must be off for File + raw key (newlines). Protected may stay on. scripts/aur-ssh-setup.sh strips CR so Windows CRLF pastes still work (from 0.5.1+).
Public vs private key
What you add on aur.archlinux.org under SSH keys is the public key (one line starting with ssh-ed25519 AAAA...). Never paste the private key (-----BEGIN OPENSSH PRIVATE KEY-----) in chat, GitLab logs, or the repo.
Recommended:
- mark release variables as Protected
- run tag pipelines only on protected tags
The same SSH key publishes both posprint and posprint-bin.
How to create the AUR repositories
If you have an AUR account but no package yet:
1. Add your SSH public key (one line, ssh-ed25519 AAAA...) on aur.archlinux.org → Account → SSH keys. That is not the private key file from ~/.ssh/id_ed25519. 2. On a machine where ssh -T aur@aur.archlinux.org works, from this repo:
chmod +x scripts/bootstrap-aur-repo.sh scripts/aur-ssh-setup.sh
./scripts/bootstrap-aur-repo.sh
./scripts/bootstrap-aur-repo.sh posprint-bin packaging/aur-bin
This copies the matching PKGBUILD and .SRCINFO, commits, and pushes to ssh://aur@aur.archlinux.org/<pkgbase>.git.
Tag pipelines can also create a missing AUR repo on first publish (clone fails → git init + push). Bootstrapping still lets you create the pages before the next tag.
Manual equivalent for posprint-bin:
mkdir ~/posprint-bin-aur && cd ~/posprint-bin-aur
git init
git remote add origin ssh://aur@aur.archlinux.org/posprint-bin.git
git checkout -b master
cp /path/to/posprint/packaging/aur-bin/PKGBUILD .
cp /path/to/posprint/packaging/aur-bin/.SRCINFO .
git add PKGBUILD .SRCINFO
git commit -m "initial import"
git push origin master
After the first push, the AUR package page exists and later tag pipelines can update it.
Bootstrapping manually
Before enabling CI automation, test one update locally (needs a binary tarball in dist/ or a completed tag pipeline):
cd /path/to/posprint
./scripts/publish-aur.sh 0.5.7
Requirements on that machine:
gitcurlsha256summakepkg- SSH access to
aur@aur.archlinux.org
Notes
pkgrelresets to1for every new upstream release.- If you need an AUR-only packaging fix without a new upstream release, bump
pkgrelin the AUR repo manually. .SRCINFOmust always be committed together withPKGBUILD.- The AUR only accepts pushes to the
masterbranch. - Install with
yay -S posprint(compile) oryay -S posprint-bin(prebuilt).
Source
| 1 | # AUR publishing |
| 2 | |
| 3 | How `posprint` is published to the Arch User Repository (AUR). |
| 4 | |
| 5 | > Since the move to BlueGit, the `release` and `publish:aur` jobs in `blue-ci-cd.yml` do this (source: BlueGit tag archive, binary: BlueGit release asset). The GitLab-specific notes below are kept for history; secrets are BlueGit repository secrets with the same names. |
| 6 | |
| 7 | ## Chosen approach |
| 8 | |
| 9 | This repository keeps **three** Arch package definitions: |
| 10 | |
| 11 | - `packaging/arch/PKGBUILD`: local builds and GitLab artifact builds (`.pkg.tar.zst`) |
| 12 | - `packaging/aur/PKGBUILD`: AUR **source** package (`posprint`), built by the AUR user from the GitLab tag tarball |
| 13 | - `packaging/aur-bin/PKGBUILD`: AUR **binary** package (`posprint-bin`), installs a prebuilt `usr/` tree from GitLab CI |
| 14 | |
| 15 | The source package downloads: |
| 16 | |
| 17 | ```text |
| 18 | https://gitlab.com/Timfa/posprint/-/archive/<version>/posprint-<version>.tar.gz |
| 19 | ``` |
| 20 | |
| 21 | The binary package downloads the **Generic Package Registry** tarball (durable; does not depend on job-artifact permalinks): |
| 22 | |
| 23 | ```text |
| 24 | https://gitlab.com/api/v4/projects/Timfa%2Fposprint/packages/generic/posprint/<version>/posprint-<version>-x86_64.tar.gz |
| 25 | ``` |
| 26 | |
| 27 | Do **not** use `/-/jobs/artifacts/<tag>/raw/...?job=build:linux-arch`. That permalink only serves the latest *successful* pipeline for the tag, so it 404s while the tag pipeline is still running and after a later job (for example AUR publish) fails. |
| 28 | |
| 29 | That tarball is packed from the **non-debug** Arch CI package (`usr/` only). `posprint` and `posprint-bin` **conflict**; `posprint-bin` **provides** `posprint`. |
| 30 | |
| 31 | ## Files in this repo |
| 32 | |
| 33 | | Path | Purpose | |
| 34 | |------|---------| |
| 35 | | `packaging/aur/PKGBUILD` | AUR source package template | |
| 36 | | `packaging/aur/.SRCINFO` | Initial generated metadata (source) | |
| 37 | | `packaging/aur-bin/PKGBUILD` | AUR binary package template | |
| 38 | | `packaging/aur-bin/.SRCINFO` | Initial generated metadata (binary) | |
| 39 | | `scripts/make-linux-bin-tarball.sh` | Pack `usr/` from the non-debug `.pkg.tar.zst` for `posprint-bin` | |
| 40 | | `scripts/publish-gitlab-release.sh` | Upload `dist/` files to the Generic Package Registry and attach them to the GitLab Release | |
| 41 | | `scripts/publish-aur.sh` | Update both AUR repos (`posprint` and `posprint-bin`) | |
| 42 | | `scripts/aur-ssh-setup.sh` | Install SSH key from GitLab File or base64 variable | |
| 43 | | `scripts/bootstrap-aur-repo.sh` | One-time initial push to create an AUR repo | |
| 44 | | `.gitlab-ci.yml` | Builds the binary tarball and runs AUR publish on tags | |
| 45 | |
| 46 | ## Release flow |
| 47 | |
| 48 | When a Git tag is pushed: |
| 49 | |
| 50 | 1. GitLab builds the normal release artifacts, including `posprint-<version>-x86_64.tar.gz` from the **non-debug** Arch package. |
| 51 | 2. `release:gitlab` uploads those files to the Generic Package Registry and creates/updates the GitLab Release (download URLs stay valid even if a later job fails). |
| 52 | 3. GitLab runs `scripts/publish-aur.sh "$CI_COMMIT_TAG"` with `needs:` artifacts from `build:linux-arch` (the tarball is already in `dist/`). |
| 53 | 4. The script: |
| 54 | - downloads the tagged **source** tarball and hashes it |
| 55 | - uses the CI **binary** tarball from `dist/` (or, if missing, the Generic Package Registry) and hashes it |
| 56 | - clones each AUR repo (`posprint`, `posprint-bin`), or creates it on first push |
| 57 | - updates `pkgver`, `pkgrel`, and `sha256sums` |
| 58 | - regenerates `.SRCINFO` via `makepkg --printsrcinfo` (as non-root `aurbuild` when CI runs as root; parent tempdir is made traversable and `BUILDDIR` is forced under that user) |
| 59 | - strips a leading `v` from the tag when resolving GitLab URLs |
| 60 | - commits and pushes to each AUR `master` |
| 61 | |
| 62 | `publish:aur` has `allow_failure: true` so an AUR outage cannot mark the whole tag pipeline failed (that used to 404 every `jobs/artifacts/<tag>` download). Prefer the job succeeding. |
| 63 | |
| 64 | ### Refreshing tag 0.5.7 (or any already-pushed tag) |
| 65 | |
| 66 | CI YAML is read from the **tagged commit**. Retrying jobs on an old 0.5.7 pipeline will not pick up these fixes. |
| 67 | |
| 68 | After this change is on `master`: |
| 69 | |
| 70 | 1. Delete the GitLab Release for `0.5.7` if it still exists (Deploy → Releases), or let the new pipeline update it. |
| 71 | 2. Delete and recreate the tag on the merge commit: |
| 72 | |
| 73 | ```bash |
| 74 | git checkout master |
| 75 | git pull origin master |
| 76 | git tag -d 0.5.7 |
| 77 | git push origin :refs/tags/0.5.7 |
| 78 | git tag 0.5.7 |
| 79 | git push origin 0.5.7 |
| 80 | ``` |
| 81 | |
| 82 | 3. Wait for the new tag pipeline. Source AUR `posprint` is already 0.5.7; a retag changes the GitLab archive hash, so publish will push an updated `sha256sums` (same `pkgver`, not a second version bump). `posprint-bin` was never published for 0.5.7 and will be created on the first successful run. |
| 83 | |
| 84 | Do **not** only retry `publish:aur` on the failed 0.5.7 pipeline — that job still has no `dist/*.tar.gz` and still curls a 404 permalink. |
| 85 | |
| 86 | Alternative if you do not want to move the tag: bump to **0.5.8** and tag that instead. |
| 87 | |
| 88 | ## GitLab CI secrets |
| 89 | |
| 90 | GitLab **masked** variables cannot contain spaces or newlines. An OpenSSH private key is multiline, so do **not** paste the raw private key into a masked **Variable**. |
| 91 | |
| 92 | Use **exactly one** of these setups (do not mix File + base64 unless using the auto-detect path below): |
| 93 | |
| 94 | ### Option B — Variable + base64 (maskable; recommended from Windows) |
| 95 | |
| 96 | GitLab **Masked** variables cannot contain newlines. From Windows, pasting a raw key into a File variable often introduces **CRLF**, which makes Linux OpenSSH report `Load key: invalid format`. |
| 97 | |
| 98 | Generate **LF-normalized** base64 of the **entire** key file (including BEGIN/END): |
| 99 | |
| 100 | ```powershell |
| 101 | $path = "$env:USERPROFILE\.ssh\id_ed25519_aur_ci" |
| 102 | $text = [IO.File]::ReadAllText($path) -replace "`r`n", "`n" -replace "`r", "`n" |
| 103 | if (-not $text.EndsWith("`n")) { $text += "`n" } |
| 104 | $b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text)) |
| 105 | $b64 |
| 106 | # Verify (must print BEGIN line): |
| 107 | [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64)).Substring(0, 35) |
| 108 | ``` |
| 109 | |
| 110 | | Variable | Type | Value | |
| 111 | |----------|------|--------| |
| 112 | | `AUR_SSH_PRIVATE_KEY_B64` | **Variable** (not File) | The single-line `$b64` string; **Masked** + **Protected** | |
| 113 | |
| 114 | Also set `AUR_GIT_AUTHOR_NAME` and `AUR_GIT_AUTHOR_EMAIL`. |
| 115 | Remove `AUR_SSH_PRIVATE_KEY` if it is also set (B64 is preferred by the setup script). |
| 116 | |
| 117 | ### Option A — File + raw key |
| 118 | |
| 119 | | Variable | Type | Value | |
| 120 | |----------|------|--------| |
| 121 | | `AUR_SSH_PRIVATE_KEY` | **File** | Full private key text, including `-----BEGIN OPENSSH PRIVATE KEY-----` / `END` lines | |
| 122 | | `AUR_GIT_AUTHOR_NAME` | Variable | Your name | |
| 123 | | `AUR_GIT_AUTHOR_EMAIL` | Variable | Your email | |
| 124 | |
| 125 | **Mask must be off** for File + raw key (newlines). Protected may stay on. |
| 126 | `scripts/aur-ssh-setup.sh` strips CR so Windows CRLF pastes still work (from 0.5.1+). |
| 127 | |
| 128 | ### Public vs private key |
| 129 | |
| 130 | What you add on [aur.archlinux.org](https://aur.archlinux.org) under **SSH keys** is the **public** key (one line starting with `ssh-ed25519 AAAA...`). |
| 131 | Never paste the **private** key (`-----BEGIN OPENSSH PRIVATE KEY-----`) in chat, GitLab logs, or the repo. |
| 132 | |
| 133 | Recommended: |
| 134 | |
| 135 | - mark release variables as **Protected** |
| 136 | - run tag pipelines only on **protected tags** |
| 137 | |
| 138 | The same SSH key publishes **both** `posprint` and `posprint-bin`. |
| 139 | |
| 140 | ## How to create the AUR repositories |
| 141 | |
| 142 | If you have an AUR account but no package yet: |
| 143 | |
| 144 | 1. Add your **SSH public key** (one line, `ssh-ed25519 AAAA...`) on [aur.archlinux.org](https://aur.archlinux.org) → Account → SSH keys. |
| 145 | That is **not** the private key file from `~/.ssh/id_ed25519`. |
| 146 | 2. On a machine where `ssh -T aur@aur.archlinux.org` works, from this repo: |
| 147 | |
| 148 | ```bash |
| 149 | chmod +x scripts/bootstrap-aur-repo.sh scripts/aur-ssh-setup.sh |
| 150 | ./scripts/bootstrap-aur-repo.sh |
| 151 | ./scripts/bootstrap-aur-repo.sh posprint-bin packaging/aur-bin |
| 152 | ``` |
| 153 | |
| 154 | This copies the matching `PKGBUILD` and `.SRCINFO`, commits, and pushes to `ssh://aur@aur.archlinux.org/<pkgbase>.git`. |
| 155 | |
| 156 | Tag pipelines can also create a missing AUR repo on first publish (clone fails → `git init` + push). Bootstrapping still lets you create the pages before the next tag. |
| 157 | |
| 158 | Manual equivalent for `posprint-bin`: |
| 159 | |
| 160 | ```bash |
| 161 | mkdir ~/posprint-bin-aur && cd ~/posprint-bin-aur |
| 162 | git init |
| 163 | git remote add origin ssh://aur@aur.archlinux.org/posprint-bin.git |
| 164 | git checkout -b master |
| 165 | cp /path/to/posprint/packaging/aur-bin/PKGBUILD . |
| 166 | cp /path/to/posprint/packaging/aur-bin/.SRCINFO . |
| 167 | git add PKGBUILD .SRCINFO |
| 168 | git commit -m "initial import" |
| 169 | git push origin master |
| 170 | ``` |
| 171 | |
| 172 | After the first push, the AUR package page exists and later tag pipelines can update it. |
| 173 | |
| 174 | ## Bootstrapping manually |
| 175 | |
| 176 | Before enabling CI automation, test one update locally (needs a binary tarball in `dist/` or a completed tag pipeline): |
| 177 | |
| 178 | ```bash |
| 179 | cd /path/to/posprint |
| 180 | ./scripts/publish-aur.sh 0.5.7 |
| 181 | ``` |
| 182 | |
| 183 | Requirements on that machine: |
| 184 | |
| 185 | - `git` |
| 186 | - `curl` |
| 187 | - `sha256sum` |
| 188 | - `makepkg` |
| 189 | - SSH access to `aur@aur.archlinux.org` |
| 190 | |
| 191 | ## Notes |
| 192 | |
| 193 | - `pkgrel` resets to `1` for every new upstream release. |
| 194 | - If you need an AUR-only packaging fix without a new upstream release, bump `pkgrel` in the AUR repo manually. |
| 195 | - `.SRCINFO` must always be committed together with `PKGBUILD`. |
| 196 | - The AUR only accepts pushes to the `master` branch. |
| 197 | - Install with `yay -S posprint` (compile) or `yay -S posprint-bin` (prebuilt). |