# 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`, vóór `self_update`, met `allow_failure: true` en `needs: [build]`. De archive-route staat live, dus de tarball van `CI_COMMIT_SHA` is te downloaden met de binary die al draait. Een AUR-storing maakt de pipeline niet rood en houdt `self_update` niet tegen. Een merge-request-pipeline slaat hem over. Een release die de archive-route zelf wijzigt, kan `publish_aur` één keer laten falen. Die job draait nog tegen de oude binary. `self_update` installeert daarna de nieuwe route. Een retry van alleen `publish_aur` publiceert dan alsnog. `self_update` is de laatste job in dezelfde stage en wacht op `publish_aur`. Omdat die job `allow_failure: true` heeft, start de deploy ook als de AUR-publicatie mislukt. `scripts/self-update.sh` stuurt de sha naar `POST /api/v1/admin/self-update` en stopt meteen, groen. Er is geen poll. De POST antwoordt 202 zodra de unit start. Steve draait in `bluegit.service`, en `post_upgrade` herstart die service. Een job die op dat moment nog `running` is, sterft mee en blijft anders voor altijd op `running` staan. `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 `publish_aur` wacht op `build` en publiceert de tarball van deze sha. Die URL werkt op de binary die al draait. `self_update` wacht op die job (`needs: [publish_aur]`), doet alleen de POST en eindigt groen. `publish_aur` heeft `allow_failure: true`, dus een AUR-fout blokkeert de deploy niet. Een release die de archive-route zelf wijzigt kan `publish_aur` één keer laten falen, omdat die job de oude binary gebruikt. De self-update daarna installeert de nieuwe route. Een retry van `publish_aur` publiceert dan alsnog. `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 wacht daarna niet. Een poll in de job zou de herstart niet overleven, en de updater zou op die lopende job blijven wachten. Bij `bluegit serve` zet BlueGit elke job die nog `running` is op `failed`. In het nieuwe proces heeft geen van die jobs nog een container. Het log zegt dat BlueGit herstartte terwijl de job liep. Daarna pakt retry met mode `failed` die job op, plus een vervolg dat daardoor was overgeslagen. Elke job met status `running` telt mee. `publish_aur` is dan al klaar en `self_update` eindigt bij de POST, vóór de bouw en `pacman -U`. 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`. Elke job met status `running` zit 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.