BlueGit

timfa posprint

Files

posprint / docs / AUR.md

AUR.md

AUR.md 5.2 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
  • 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`
44 - commits and pushes to AUR `master`
45
46## GitLab CI secrets
47
48GitLab **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**.
49
50Use **exactly one** of these setups (do not mix File + base64 unless using the auto-detect path below):
51
52### Option B — Variable + base64 (maskable; recommended from Windows)
53
54GitLab **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`.
55
56Generate **LF-normalized** base64 of the **entire** key file (including BEGIN/END):
57
58```powershell
59$path = "$env:USERPROFILE\.ssh\id_ed25519_aur_ci"
60$text = [IO.File]::ReadAllText($path) -replace "`r`n", "`n" -replace "`r", "`n"
61if (-not $text.EndsWith("`n")) { $text += "`n" }
62$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text))
63$b64
64# Verify (must print BEGIN line):
65[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64)).Substring(0, 35)
66```
67
68| Variable | Type | Value |
69|----------|------|--------|
70| `AUR_SSH_PRIVATE_KEY_B64` | **Variable** (not File) | The single-line `$b64` string; **Masked** + **Protected** |
71
72Also set `AUR_GIT_AUTHOR_NAME` and `AUR_GIT_AUTHOR_EMAIL`.
73Remove `AUR_SSH_PRIVATE_KEY` if it is also set (B64 is preferred by the setup script).
74
75### Option A — File + raw key
76
77| Variable | Type | Value |
78|----------|------|--------|
79| `AUR_SSH_PRIVATE_KEY` | **File** | Full private key text, including `-----BEGIN OPENSSH PRIVATE KEY-----` / `END` lines |
80| `AUR_GIT_AUTHOR_NAME` | Variable | Your name |
81| `AUR_GIT_AUTHOR_EMAIL` | Variable | Your email |
82| `AUR_PKGBASE` | Variable (optional) | Defaults to `posprint` |
83
84**Mask must be off** for File + raw key (newlines). Protected may stay on.
85`scripts/aur-ssh-setup.sh` strips CR so Windows CRLF pastes still work (from 0.5.1+).
86
87### Public vs private key
88
89What you add on [aur.archlinux.org](https://aur.archlinux.org) under **SSH keys** is the **public** key (one line starting with `ssh-ed25519 AAAA...`).
90Never paste the **private** key (`-----BEGIN OPENSSH PRIVATE KEY-----`) in chat, GitLab logs, or the repo.
91
92Recommended:
93
94- mark release variables as **Protected**
95- run tag pipelines only on **protected tags**
96
97## How to create the AUR repository
98
99If you have an AUR account but no package yet:
100
1011. Add your **SSH public key** (one line, `ssh-ed25519 AAAA...`) on [aur.archlinux.org](https://aur.archlinux.org) → Account → SSH keys.
102 That is **not** the private key file from `~/.ssh/id_ed25519`.
1032. On a machine where `ssh -T aur@aur.archlinux.org` works, from this repo:
104
105```bash
106chmod +x scripts/bootstrap-aur-repo.sh scripts/aur-ssh-setup.sh
107./scripts/bootstrap-aur-repo.sh
108```
109
110This copies `packaging/aur/PKGBUILD` and `.SRCINFO`, commits, and pushes to `ssh://aur@aur.archlinux.org/posprint.git`.
111
112Manual equivalent:
113
114```bash
115mkdir ~/posprint-aur && cd ~/posprint-aur
116git init
117git remote add origin ssh://aur@aur.archlinux.org/posprint.git
118git checkout -b master
119cp /path/to/posprint/packaging/aur/PKGBUILD .
120cp /path/to/posprint/packaging/aur/.SRCINFO .
121git add PKGBUILD .SRCINFO
122git commit -m "initial import"
123git push origin master
124```
125
126After the first push, the AUR package page exists and later tag pipelines can update it.
127
128## Bootstrapping manually
129
130Before enabling CI automation, test one update locally:
131
132```bash
133cd /path/to/posprint
134./scripts/publish-aur.sh 0.4.0
135```
136
137Requirements on that machine:
138
139- `git`
140- `curl`
141- `sha256sum`
142- `makepkg`
143- SSH access to `aur@aur.archlinux.org`
144
145## Notes
146
147- `pkgrel` resets to `1` for every new upstream release.
148- If you need an AUR-only packaging fix without a new upstream release, bump `pkgrel` in the AUR repo manually.
149- `.SRCINFO` must always be committed together with `PKGBUILD`.
150- The AUR only accepts pushes to the `master` branch.