# 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 |
| `.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`
   - commits and pushes to AUR `master`

## GitLab CI secrets

Create these **CI/CD variables** in GitLab:

| Variable | Required | Notes |
|----------|----------|-------|
| `AUR_SSH_PRIVATE_KEY` | yes | Private SSH key for your AUR account; use **masked** + **protected** |
| `AUR_GIT_AUTHOR_NAME` | recommended | Example: `Tim Falken` or `posprint release bot` |
| `AUR_GIT_AUTHOR_EMAIL` | recommended | Example: `you@example.com` |
| `AUR_PKGBASE` | optional | Defaults to `posprint`; only needed if the AUR repo name differs |

Recommended GitLab settings:

- mark the variables as **Protected**
- mark `AUR_SSH_PRIVATE_KEY` as **Masked**
- only allow the release/tag pipeline on protected tags

## How to create the AUR repository

If you have an AUR account but no package yet:

1. Make sure your **SSH public key** is added to your AUR account profile.
2. On an Arch machine (or any machine with `git` + `makepkg`), create a working directory:

```bash
mkdir ~/posprint-aur
cd ~/posprint-aur
git init
git remote add origin ssh://aur@aur.archlinux.org/posprint.git
```

3. Copy in the initial metadata from this repo:

```bash
cp /path/to/posprint/packaging/aur/PKGBUILD .
cp /path/to/posprint/packaging/aur/.SRCINFO .
```

4. Commit and push:

```bash
git checkout -b master
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.
