# AUR Elke push naar `master` werkt `packaging/aur/PKGBUILD` bij en pusht die naar `ssh://aur@aur.archlinux.org/bluegit.git` (branch `master`; AUR accepteert niets anders). De aanpak en de geheimnamen zijn dezelfde als in Posprint. Posprint publiceert bij een tag; BlueGit doet het bij elke commit op `master`, omdat er geen vaste versietag is. ## Package Er is één source-package, `bluegit`. Geen `-bin`. De PKGBUILD haalt het archief van BlueGit op, op de commit-sha: ```text https://git.timfalken.com/timfa/bluegit/-/archive//bluegit-.tar.gz ``` Die map heet `bluegit-`. `pkgver` is `YYYYMMDDHHMMSS`, de UTC-committertijd van de commit. De CI-job neemt `CI_COMMIT_TIMESTAMP` (ISO 8601). Ontbreekt die, dan neemt `publish-aur.sh` `git show -s --format=%cI` en rekent die om naar UTC. Het lokale script en de self-updater gebruiken dezelfde committer-tijd, zodat dezelfde sha dezelfde `pkgver` houdt. `pkgrel` gaat terug naar 1. `_commit` is de volledige sha. Het CI-script vult `sha256sums` met de hash van dat archief. Het lokale script doet hetzelfde met `updpkgsums`. Beide maken `.SRCINFO` opnieuw met `makepkg --printsrcinfo`. Draait de CI-job als root, dan doet gebruiker `aurbuild` dat (`AUR_MAKEPKG_USER` overschrijft de naam). De gedeelde functies staan in `scripts/aur-common.sh`. De lokale `packaging/arch/PKGBUILD` blijft voor een build uit de werkboom. Die gaat niet naar de AUR. ## Unit en install-hook De unit is de bestaande system-unit: `User=bluegit`, `ExecStart` met `/etc/bluegit/config.yml`, `StateDirectory=bluegit` voor `/var/lib/bluegit`. Geen `systemd --user`-unit. `packaging/aur/bluegit.install` maakt bij installatie en upgrade de systeemgebruiker en de state-map aan. `post_install` doet `systemctl daemon-reload` en daarna `systemctl enable --now bluegit.service`, maar alleen als `/etc/bluegit/config.yml` er al is én het clientgeheim in `/etc/bluegit/client_secret` of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env` staat. Een lege `client_secret: ""` telt niet. Ontbreekt een van beide, dan print de hook de vervolgstappen en start hij niets. `post_upgrade` herlaadt systemd en doet `systemctl try-restart bluegit.service`. `pre_remove` doet `systemctl disable --now bluegit.service`. Draait systemd niet (chroot of container), dan slaat de hook die stappen over zonder fout. `backup=('etc/bluegit/config.yml')` laat een aangepaste config staan. De huidige user-unit (`/home/timfa/bluegit/config.yml`, `/home/timfa/bluegit/state`, datadisk `/home/timfa/temp-bluegit`) gaat over naar deze system-service volgens [MIGRATIE.md](MIGRATIE.md). De datadisk verhuist naar `/srv/bluegit`; een pad onder `/home` blijft met `ProtectHome=true` onbereikbaar. De schijf, het clientgeheim en de ingress van deze installatie staan in [BEHEER.md](BEHEER.md). ## Geheimen De namen zijn 1-op-1 dezelfde als in Posprint. De publieke sleutel hoort op aur.archlinux.org, nooit de private sleutel in de repository. ### GitLab (overgang) `.gitlab-ci.yml` blijft de pipeline op gitlab.com. Zet daar deze CI/CD-variabelen: | Naam | Soort | Inhoud | | --- | --- | --- | | `AUR_SSH_PRIVATE_KEY` | File, mask uit, protected mag | ruwe OpenSSH-sleutel (`BEGIN … PRIVATE KEY`). Een File met base64 wordt ook herkend. | | `AUR_SSH_PRIVATE_KEY_B64` | Variable, één regel, Masked+Protected | base64 van die sleutel. GitLab maskeert geen meerregelige waarde, daarom base64 of een File. | | `AUR_GIT_AUTHOR_NAME` | Variable | naam in de AUR-commit | | `AUR_GIT_AUTHOR_EMAIL` | Variable | e-mail in de AUR-commit | Eén van de twee sleutelvariabelen is genoeg. `scripts/aur-ssh-setup.sh` haalt CRLF weg en controleert de sleutel met `ssh-keygen -y` zonder hem te printen. De job heet `publish:aur`. Hij draait alleen als `CI_COMMIT_BRANCH` `master` is, met `allow_failure: true`. ### BlueGit Steve leest `blue-ci-cd.yml` op de mirror `https://git.timfalken.com/timfa/bluegit`. Zet dezelfde namen als geheimen op die repository, of op de groep als de repository van een groep is. Eerst de groep, daarna de repository; dezelfde naam laat de repository winnen. BlueGit heeft geen File-type: de waarde van het geheim is de tekst zelf. Een ruwe sleutel in `AUR_SSH_PRIVATE_KEY` herkent het script aan `BEGIN … PRIVATE KEY`. Een base64-waarde mag in `AUR_SSH_PRIVATE_KEY` of in `AUR_SSH_PRIVATE_KEY_B64`. Markeer de geheimen als beschermd en bescherm de branch `master`. Een beschermd geheim komt alleen mee als de branch of tag op een beschermd patroon past. | Naam | Waarde | | --- | --- | | `AUR_SSH_PRIVATE_KEY` | ruwe OpenSSH-sleutel, of base64 daarvan. Eén sleutelgeheim is genoeg. | | `AUR_SSH_PRIVATE_KEY_B64` | dezelfde sleutel als één regel base64. | | `AUR_GIT_AUTHOR_NAME` | naam in de AUR-commit | | `AUR_GIT_AUTHOR_EMAIL` | e-mail in de AUR-commit | | `BLUEGIT_UPDATE_TOKEN` | dezelfde waarde als `BLUEGIT_UPDATE_TOKEN` in `/etc/bluegit/env` op de mini-PC | `publish_aur` draait op `master` en `main`, met `allow_failure: true` en `needs: [self_update]`, zodat hij pas start als de self-update-job klaar is. Een AUR-storing maakt de pipeline niet rood. Een merge-request-pipeline slaat hem over. `self_update` draait in dezelfde stage, wacht op `build`, en roept daarna `scripts/self-update.sh` aan. Dat script stuurt de sha naar `POST /api/v1/admin/self-update` en polt `GET /api/v1/admin/self-update` tot `status` `ok` is voor diezelfde sha. De timeout is 300 seconden. Een andere sha, ook met `ok`, telt niet. `failed` voor de eigen sha faalt meteen. Een time-out faalt de job, en daardoor start `publish_aur` niet. `CI_API_URL` eindigt op `/api/v1`. De body mag `ref` zijn; de job stuurt de sha van de pipeline. Zonder `BLUEGIT_UPDATE_TOKEN` op de server antwoordt het endpoint met 404 en faalt de job. Een merge-request-pipeline draait deze job niet: alleen `vet`, `test`, `frontend_checks` en `build`. ## Lokaal publiceren Zolang de CI-runner er niet is, publiceert `scripts/aur-publish-local.sh` met de hand vanuit een lokale checkout. Het gebruikt de AUR-sleutel in `~/.ssh` of ssh-agent, en geen CI-variabelen. De checkout moet op `master` staan, schoon zijn en gelijk aan `origin/master`. Het script publiceert de sha van `origin/master`. Staat die sha al als `_commit` in de AUR-PKGBUILD, dan stopt het zonder iets te wijzigen. Het clonet of werkt `ssh://aur@aur.archlinux.org/bluegit.git` bij in `~/.cache/bluegit-aur` (`BLUEGIT_AUR_CACHE` wijzigt die map), kopieert `packaging/aur/*`, zet `_commit` en `pkgver`, en draait `updpkgsums` en `makepkg --printsrcinfo`. Daarna commit het `upstream ` en pusht het naar `master`. `updpkgsums` komt uit `pacman-contrib`. ## Self-update `self_update` wacht op `build`. Het script polt tot de update `ok` is voor de sha van de pipeline, ongeveer 5 minuten. `publish_aur` wacht op die job (`needs: [self_update]`, `allow_failure: true`) en publiceert daarna. `BLUEGIT_UPDATE_TOKEN` is een gemaskeerde, beschermde CI-variabele. Dezelfde waarde staat op de mini-PC in `/etc/bluegit/env` (EnvironmentFile, optioneel). Zonder die variabele antwoordt `POST /api/v1/admin/self-update` met 404. De vergelijking is constant-time, en een burst krijgt 429. De body mag leeg zijn of `ref` / `sha` bevatten. Het endpoint schrijft die ref naar `/var/lib/bluegit/update-request` en start alleen `bluegit-update.service` (`systemctl start --no-block`). De CI-job blijft daarna pollen. `self_update` van `timfa/bluegit` telt niet mee in `running`, anders wacht de updater op de job die op hem wacht. Een job met die naam in een andere repository telt wel. Die telling zit in de binary en geldt pas nadat deze versie geïnstalleerd is. De poll leest `status` en `sha` met `jq`, omdat `log` vooraan in de JSON staat en die tekst dezelfde woorden bevat. De polkit-regel `packaging/bluegit-update.rules` laat gebruiker `bluegit` uitsluitend `start` van die ene unit toe. Geen stop, geen restart, geen andere unit. De unit is een oneshot als root. `/usr/lib/bluegit/update` (uit `packaging/bluegit-update.sh`) wacht tot `GET /api/v1/admin/self-update` `"running":0` meldt, ook na de bouw en vóór `pacman -U`. Hij cloont niet van GitLab: `BLUEGIT_UPDATE_REPO` in `/etc/bluegit/env` wijst naar de lokale bare repo, bijvoorbeeld `/srv/bluegit/tim/bluegit.git`. `pkgver` is de UTC-committertijd van die commit (`YYYYMMDDHHMMSS`), dezelfde regel als het lokale AUR-script, zodat `yay` later geen downgrade of upgrade verzint voor dezelfde sha. `makepkg` draait als `bluegit-build`. Die gebruiker maakt de install-hook aan via `systemd-sysusers` (`packaging/sysusers.conf`). `pacman -U --noconfirm` installeert het pakket. `post_upgrade` in `bluegit.install` doet `systemctl try-restart bluegit.service`. Mislukt de bouw of de installatie, dan blijft de oude versie staan. De uitvoer staat in het journal van `bluegit-update.service` en, vanaf deze versie, in `/var/lib/bluegit/update.log`. Elke run maakt dat bestand leeg en schrijft het opnieuw (mode 644). `GET /api/v1/admin/self-update` met dezelfde Bearer als de POST geeft `running`, `status`, `sha`, `started_at`, `result`, `error` en `log` (de laatste 200 regels). Het object `update` blijft. Het veld `running` blijft, want de updater wacht tot dat 0 is. Zonder sleutel is het antwoord 404, met een foute sleutel 401. Een POST die 202 teruggeeft is nog geen installatie. De unit wacht tot `BLUEGIT_UPDATE_TIMEOUT` (standaard 1800 seconden) tot `running` 0 is, ook vóór `pacman -U`. De job `self_update` van `timfa/bluegit` zit niet in die telling. `openapi.json` blijft 404 zolang de oude binary draait. `packaging/aur/PKGBUILD` heeft geen `check()`. `makepkg` draait de testsuite niet en komt `unshare` dus niet tegen. De bouw is `go build`. `pkgver` komt uit `git show` op `BLUEGIT_UPDATE_REPO`. Die aanroep zet `safe.directory`: Git weigert ook als root een repo van een andere uid. Mislukt git, dan stopt het script en wordt de status `failed`. Het script dat nu geïnstalleerd is, is dat van het vorige pakket. Deze log en `safe.directory` gelden pas nadat een update deze versie echt geïnstalleerd heeft. Het script schrijft `/var/lib/bluegit/update-status.json` met tijd, sha en resultaat (`running`, `ok`, `failed`). Een installatiebeheerder ziet dat op de Info-pagina en op de setup-pagina. De mini-PC heeft `base-devel`, `go` en `pacman-contrib` niet als package-dependency. Die moeten geïnstalleerd zijn, anders stopt het script vóór `pacman -U`. ## Archief Het archief van een commit is anoniem te downloaden zolang de repository publiek is. Een token is niet nodig. `tar.gz` en `zip` bestaan allebei. De map in het archief heet `bluegit-`, met de volledige sha. ```text https://git.timfalken.com/timfa/bluegit/-/archive//bluegit-.tar.gz https://git.timfalken.com/timfa/bluegit/-/archive//bluegit-.zip ``` Twee downloads van dezelfde sha geven dezelfde bytes. `git archive` zet de gzip-mtime op 0, dus de klok zit niet in de checksum. `sha256sums` in de PKGBUILD hoort bij die url. Een andere git-versie op de server kan het archiefformaat wijzigen; dan klopt een al gepubliceerde checksum niet meer. Een branch- of tagarchief (`/-/branches/archive`, `/-/tags/archive`) volgt de punt van die ref. Die url hoort niet in de PKGBUILD: de bytes veranderen zodra de ref opschuift, en dan breekt `sha256sums`. De publish-job haalt de tarball zonder token op en zet de sha256 in de PKGBUILD. `makepkg` gebruikt dezelfde URL.