# 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:

```text
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):

```text
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`, 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:

```bash
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):

```powershell
$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](https://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](https://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:

```bash
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`:

```bash
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):

```bash
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).
