BlueGit

timfa posprint

Files

posprint / docs / AUR.md

AUR.md

AUR.md 8.9 KiB Download Raw

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 tarball
  • packaging/aur-bin/PKGBUILD: AUR binary package (posprint-bin), installs a prebuilt usr/ 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

PathPurpose
packaging/aur/PKGBUILDAUR source package template
packaging/aur/.SRCINFOInitial generated metadata (source)
packaging/aur-bin/PKGBUILDAUR binary package template
packaging/aur-bin/.SRCINFOInitial generated metadata (binary)
scripts/make-linux-bin-tarball.shPack usr/ from the non-debug .pkg.tar.zst for posprint-bin
scripts/publish-gitlab-release.shUpload dist/ files to the Generic Package Registry and attach them to the GitLab Release
scripts/publish-aur.shUpdate both AUR repos (posprint and posprint-bin)
scripts/aur-ssh-setup.shInstall SSH key from GitLab File or base64 variable
scripts/bootstrap-aur-repo.shOne-time initial push to create an AUR repo
.gitlab-ci.ymlBuilds 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, and sha256sums
  • 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)
  • strips a leading v from 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)
VariableTypeValue
AUR_SSH_PRIVATE_KEY_B64Variable (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

VariableTypeValue
AUR_SSH_PRIVATE_KEYFileFull private key text, including -----BEGIN OPENSSH PRIVATE KEY----- / END lines
AUR_GIT_AUTHOR_NAMEVariableYour name
AUR_GIT_AUTHOR_EMAILVariableYour 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:

  • git
  • curl
  • sha256sum
  • makepkg
  • SSH access to aur@aur.archlinux.org

Notes

  • pkgrel resets to 1 for every new upstream release.
  • If you need an AUR-only packaging fix without a new upstream release, bump pkgrel in the AUR repo manually.
  • .SRCINFO must always be committed together with PKGBUILD.
  • The AUR only accepts pushes to the master branch.
  • Install with yay -S posprint (compile) or yay -S posprint-bin (prebuilt).
Source
1# AUR publishing
2
3How `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
9This 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
15The source package downloads:
16
17```text
18https://gitlab.com/Timfa/posprint/-/archive/<version>/posprint-<version>.tar.gz
19```
20
21The binary package downloads the **Generic Package Registry** tarball (durable; does not depend on job-artifact permalinks):
22
23```text
24https://gitlab.com/api/v4/projects/Timfa%2Fposprint/packages/generic/posprint/<version>/posprint-<version>-x86_64.tar.gz
25```
26
27Do **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
29That 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
48When a Git tag is pushed:
49
501. GitLab builds the normal release artifacts, including `posprint-<version>-x86_64.tar.gz` from the **non-debug** Arch package.
512. `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).
523. GitLab runs `scripts/publish-aur.sh "$CI_COMMIT_TAG"` with `needs:` artifacts from `build:linux-arch` (the tarball is already in `dist/`).
534. 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
66CI YAML is read from the **tagged commit**. Retrying jobs on an old 0.5.7 pipeline will not pick up these fixes.
67
68After this change is on `master`:
69
701. Delete the GitLab Release for `0.5.7` if it still exists (Deploy → Releases), or let the new pipeline update it.
712. Delete and recreate the tag on the merge commit:
72
73```bash
74git checkout master
75git pull origin master
76git tag -d 0.5.7
77git push origin :refs/tags/0.5.7
78git tag 0.5.7
79git push origin 0.5.7
80```
81
823. 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
84Do **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
86Alternative if you do not want to move the tag: bump to **0.5.8** and tag that instead.
87
88## GitLab CI secrets
89
90GitLab **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
92Use **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
96GitLab **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
98Generate **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"
103if (-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
114Also set `AUR_GIT_AUTHOR_NAME` and `AUR_GIT_AUTHOR_EMAIL`.
115Remove `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
130What you add on [aur.archlinux.org](https://aur.archlinux.org) under **SSH keys** is the **public** key (one line starting with `ssh-ed25519 AAAA...`).
131Never paste the **private** key (`-----BEGIN OPENSSH PRIVATE KEY-----`) in chat, GitLab logs, or the repo.
132
133Recommended:
134
135- mark release variables as **Protected**
136- run tag pipelines only on **protected tags**
137
138The same SSH key publishes **both** `posprint` and `posprint-bin`.
139
140## How to create the AUR repositories
141
142If you have an AUR account but no package yet:
143
1441. 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`.
1462. On a machine where `ssh -T aur@aur.archlinux.org` works, from this repo:
147
148```bash
149chmod +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
154This copies the matching `PKGBUILD` and `.SRCINFO`, commits, and pushes to `ssh://aur@aur.archlinux.org/<pkgbase>.git`.
155
156Tag 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
158Manual equivalent for `posprint-bin`:
159
160```bash
161mkdir ~/posprint-bin-aur && cd ~/posprint-bin-aur
162git init
163git remote add origin ssh://aur@aur.archlinux.org/posprint-bin.git
164git checkout -b master
165cp /path/to/posprint/packaging/aur-bin/PKGBUILD .
166cp /path/to/posprint/packaging/aur-bin/.SRCINFO .
167git add PKGBUILD .SRCINFO
168git commit -m "initial import"
169git push origin master
170```
171
172After the first push, the AUR package page exists and later tag pipelines can update it.
173
174## Bootstrapping manually
175
176Before enabling CI automation, test one update locally (needs a binary tarball in `dist/` or a completed tag pipeline):
177
178```bash
179cd /path/to/posprint
180./scripts/publish-aur.sh 0.5.7
181```
182
183Requirements 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).