BlueGit

timfa posprint

Files

posprint / docs / AUR.md

AUR.md

chore: bump version to 0.5.7 for Bluetooth SPP test release
timfa project_84475926_bot_3b4fb417c41b9b24a7422b6452f025d2 · pushed by timfa · 2 months ago
ef0ca9ca History
AUR.md 6.7 KiB Download Raw

AUR publishing

How posprint is published to the Arch User Repository (AUR) from GitLab tags.

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:

https://gitlab.com/Timfa/posprint/-/jobs/artifacts/<version>/raw/dist/posprint-<version>-x86_64.tar.gz?job=build:linux-arch

That tarball is packed from the 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 .pkg.tar.zst for posprint-bin
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. 2. GitLab creates the upstream release (with a link to that tarball). 3. GitLab runs scripts/publish-aur.sh "$CI_COMMIT_TAG". 4. The script:

  • downloads the tagged source tarball and hashes it
  • uses the CI binary tarball from dist/ (or downloads the job artifact) 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

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) from GitLab tags.
4
5## Chosen approach
6
7This repository keeps **three** Arch package definitions:
8
9- `packaging/arch/PKGBUILD`: local builds and GitLab artifact builds (`.pkg.tar.zst`)
10- `packaging/aur/PKGBUILD`: AUR **source** package (`posprint`), built by the AUR user from the GitLab tag tarball
11- `packaging/aur-bin/PKGBUILD`: AUR **binary** package (`posprint-bin`), installs a prebuilt `usr/` tree from GitLab CI
12
13The source package downloads:
14
15```text
16https://gitlab.com/Timfa/posprint/-/archive/<version>/posprint-<version>.tar.gz
17```
18
19The binary package downloads:
20
21```text
22https://gitlab.com/Timfa/posprint/-/jobs/artifacts/<version>/raw/dist/posprint-<version>-x86_64.tar.gz?job=build:linux-arch
23```
24
25That tarball is packed from the Arch CI package (`usr/` only). `posprint` and `posprint-bin` **conflict**; `posprint-bin` **provides** `posprint`.
26
27## Files in this repo
28
29| Path | Purpose |
30|------|---------|
31| `packaging/aur/PKGBUILD` | AUR source package template |
32| `packaging/aur/.SRCINFO` | Initial generated metadata (source) |
33| `packaging/aur-bin/PKGBUILD` | AUR binary package template |
34| `packaging/aur-bin/.SRCINFO` | Initial generated metadata (binary) |
35| `scripts/make-linux-bin-tarball.sh` | Pack `usr/` from `.pkg.tar.zst` for `posprint-bin` |
36| `scripts/publish-aur.sh` | Update both AUR repos (`posprint` and `posprint-bin`) |
37| `scripts/aur-ssh-setup.sh` | Install SSH key from GitLab File or base64 variable |
38| `scripts/bootstrap-aur-repo.sh` | One-time initial push to create an AUR repo |
39| `.gitlab-ci.yml` | Builds the binary tarball and runs AUR publish on tags |
40
41## Release flow
42
43When a Git tag is pushed:
44
451. GitLab builds the normal release artifacts, including `posprint-<version>-x86_64.tar.gz`.
462. GitLab creates the upstream release (with a link to that tarball).
473. GitLab runs `scripts/publish-aur.sh "$CI_COMMIT_TAG"`.
484. The script:
49 - downloads the tagged **source** tarball and hashes it
50 - uses the CI **binary** tarball from `dist/` (or downloads the job artifact) and hashes it
51 - clones each AUR repo (`posprint`, `posprint-bin`), or creates it on first push
52 - updates `pkgver`, `pkgrel`, and `sha256sums`
53 - 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)
54 - strips a leading `v` from the tag when resolving GitLab URLs
55 - commits and pushes to each AUR `master`
56
57## GitLab CI secrets
58
59GitLab **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**.
60
61Use **exactly one** of these setups (do not mix File + base64 unless using the auto-detect path below):
62
63### Option B — Variable + base64 (maskable; recommended from Windows)
64
65GitLab **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`.
66
67Generate **LF-normalized** base64 of the **entire** key file (including BEGIN/END):
68
69```powershell
70$path = "$env:USERPROFILE\.ssh\id_ed25519_aur_ci"
71$text = [IO.File]::ReadAllText($path) -replace "`r`n", "`n" -replace "`r", "`n"
72if (-not $text.EndsWith("`n")) { $text += "`n" }
73$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text))
74$b64
75# Verify (must print BEGIN line):
76[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64)).Substring(0, 35)
77```
78
79| Variable | Type | Value |
80|----------|------|--------|
81| `AUR_SSH_PRIVATE_KEY_B64` | **Variable** (not File) | The single-line `$b64` string; **Masked** + **Protected** |
82
83Also set `AUR_GIT_AUTHOR_NAME` and `AUR_GIT_AUTHOR_EMAIL`.
84Remove `AUR_SSH_PRIVATE_KEY` if it is also set (B64 is preferred by the setup script).
85
86### Option A — File + raw key
87
88| Variable | Type | Value |
89|----------|------|--------|
90| `AUR_SSH_PRIVATE_KEY` | **File** | Full private key text, including `-----BEGIN OPENSSH PRIVATE KEY-----` / `END` lines |
91| `AUR_GIT_AUTHOR_NAME` | Variable | Your name |
92| `AUR_GIT_AUTHOR_EMAIL` | Variable | Your email |
93
94**Mask must be off** for File + raw key (newlines). Protected may stay on.
95`scripts/aur-ssh-setup.sh` strips CR so Windows CRLF pastes still work (from 0.5.1+).
96
97### Public vs private key
98
99What you add on [aur.archlinux.org](https://aur.archlinux.org) under **SSH keys** is the **public** key (one line starting with `ssh-ed25519 AAAA...`).
100Never paste the **private** key (`-----BEGIN OPENSSH PRIVATE KEY-----`) in chat, GitLab logs, or the repo.
101
102Recommended:
103
104- mark release variables as **Protected**
105- run tag pipelines only on **protected tags**
106
107The same SSH key publishes **both** `posprint` and `posprint-bin`.
108
109## How to create the AUR repositories
110
111If you have an AUR account but no package yet:
112
1131. Add your **SSH public key** (one line, `ssh-ed25519 AAAA...`) on [aur.archlinux.org](https://aur.archlinux.org) → Account → SSH keys.
114 That is **not** the private key file from `~/.ssh/id_ed25519`.
1152. On a machine where `ssh -T aur@aur.archlinux.org` works, from this repo:
116
117```bash
118chmod +x scripts/bootstrap-aur-repo.sh scripts/aur-ssh-setup.sh
119./scripts/bootstrap-aur-repo.sh
120./scripts/bootstrap-aur-repo.sh posprint-bin packaging/aur-bin
121```
122
123This copies the matching `PKGBUILD` and `.SRCINFO`, commits, and pushes to `ssh://aur@aur.archlinux.org/<pkgbase>.git`.
124
125Tag 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.
126
127Manual equivalent for `posprint-bin`:
128
129```bash
130mkdir ~/posprint-bin-aur && cd ~/posprint-bin-aur
131git init
132git remote add origin ssh://aur@aur.archlinux.org/posprint-bin.git
133git checkout -b master
134cp /path/to/posprint/packaging/aur-bin/PKGBUILD .
135cp /path/to/posprint/packaging/aur-bin/.SRCINFO .
136git add PKGBUILD .SRCINFO
137git commit -m "initial import"
138git push origin master
139```
140
141After the first push, the AUR package page exists and later tag pipelines can update it.
142
143## Bootstrapping manually
144
145Before enabling CI automation, test one update locally (needs a binary tarball in `dist/` or a completed tag pipeline):
146
147```bash
148cd /path/to/posprint
149./scripts/publish-aur.sh 0.5.7
150```
151
152Requirements on that machine:
153
154- `git`
155- `curl`
156- `sha256sum`
157- `makepkg`
158- SSH access to `aur@aur.archlinux.org`
159
160## Notes
161
162- `pkgrel` resets to `1` for every new upstream release.
163- If you need an AUR-only packaging fix without a new upstream release, bump `pkgrel` in the AUR repo manually.
164- `.SRCINFO` must always be committed together with `PKGBUILD`.
165- The AUR only accepts pushes to the `master` branch.
166- Install with `yay -S posprint` (compile) or `yay -S posprint-bin` (prebuilt).