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

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

| Path | Purpose |
|------|---------|
| `packaging/aur/PKGBUILD` | AUR package template |
| `packaging/aur/.SRCINFO` | Initial generated metadata |
| `scripts/publish-aur.sh` | Clone AUR repo, update `PKGBUILD`/`.SRCINFO`, commit, push |
| `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 the AUR repo |
| `.gitlab-ci.yml` | Runs 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 a non-root user when CI runs as root)
   - 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):

```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 |
| `AUR_PKGBASE` | Variable (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](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**

## 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](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
```

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

Manual equivalent:

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

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