BlueGit

timfa posprint

Files

posprint / docs / AUR.md

AUR.md

AUR.md 5.5 KiB Download Raw

AUR publishing

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

Chosen approach

This repository keeps two Arch package definitions:

  • packaging/arch/PKGBUILD: local builds and GitLab artifact builds (.pkg.tar.zst)
  • packaging/aur/PKGBUILD: AUR source package, built by the AUR user from the GitLab tag tarball

The AUR package is not -bin. It downloads:

https://gitlab.com/Timfa/posprint/-/archive/<version>/posprint-<version>.tar.gz

That keeps the AUR package simple, reproducible, and aligned with upstream tags.

Files in this repo

PathPurpose
packaging/aur/PKGBUILDAUR package template
packaging/aur/.SRCINFOInitial generated metadata
scripts/publish-aur.shClone AUR repo, update PKGBUILD/.SRCINFO, commit, push
scripts/aur-ssh-setup.shInstall SSH key from GitLab File or base64 variable
scripts/bootstrap-aur-repo.shOne-time initial push to create the AUR repo
.gitlab-ci.ymlRuns AUR publish on tags

Release flow

When a Git tag is pushed:

1. GitLab builds the normal release artifacts. 2. GitLab creates the upstream release. 3. GitLab runs scripts/publish-aur.sh "$CI_COMMIT_TAG". 4. The script:

  • downloads the tagged source tarball
  • computes its SHA-256
  • clones the AUR repo
  • 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 the GitLab source archive URL
  • commits and pushes to 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
AUR_PKGBASEVariable (optional)Defaults to posprint

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

How to create the AUR repository

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

This copies packaging/aur/PKGBUILD and .SRCINFO, commits, and pushes to ssh://aur@aur.archlinux.org/posprint.git.

Manual equivalent:

mkdir ~/posprint-aur && cd ~/posprint-aur
git init
git remote add origin ssh://aur@aur.archlinux.org/posprint.git
git checkout -b master
cp /path/to/posprint/packaging/aur/PKGBUILD .
cp /path/to/posprint/packaging/aur/.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:

cd /path/to/posprint
./scripts/publish-aur.sh 0.4.0

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