BlueGit

timfa bluegit

Files

bluegit / docs / AUR.md

AUR.md

fix: accepteer een checkout van een andere uid en toon het update-log
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
71de6a16 History
AUR.md 10.1 KiB Download Raw

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 de GitLab-archieven op:

https://gitlab.com/Timfa/bluegit/-/archive/<commit>/bluegit-<commit>.tar.gz

Die map heet bluegit-<commit>. 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. De datadisk verhuist naar /srv/bluegit; een pad onder /home blijft met ProtectHome=true onbereikbaar.

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:

NaamSoortInhoud
AUR_SSH_PRIVATE_KEYFile, mask uit, protected magruwe OpenSSH-sleutel (BEGIN … PRIVATE KEY). Een File met base64 wordt ook herkend.
AUR_SSH_PRIVATE_KEY_B64Variable, één regel, Masked+Protectedbase64 van die sleutel. GitLab maskeert geen meerregelige waarde, daarom base64 of een File.
AUR_GIT_AUTHOR_NAMEVariablenaam in de AUR-commit
AUR_GIT_AUTHOR_EMAILVariablee-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.

NaamWaarde
AUR_SSH_PRIVATE_KEYruwe OpenSSH-sleutel, of base64 daarvan. Eén sleutelgeheim is genoeg.
AUR_SSH_PRIVATE_KEY_B64dezelfde sleutel als één regel base64.
AUR_GIT_AUTHOR_NAMEnaam in de AUR-commit
AUR_GIT_AUTHOR_EMAILe-mail in de AUR-commit
BLUEGIT_UPDATE_TOKENdezelfde 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: [], zodat hij meteen start en een AUR-storing de rest niet rood maakt. Een merge-request-pipeline slaat hem over.

self_update draait in dezelfde stage, wacht op build, en roept daarna de draaiende instantie aan:

curl -fsS -X POST "$CI_API_URL/admin/self-update" \
  -H "Authorization: Bearer $BLUEGIT_UPDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"ref\":\"${CI_COMMIT_SHA}\"}"

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 <pkgver> en pusht het naar master. updpkgsums komt uit pacman-contrib.

Self-update

Een push naar master hoeft niet op de AUR te wachten. publish_aur publiceert parallel (needs: [], allow_failure: true). self_update staat in dezelfde stage en wacht alleen op build, niet op de AUR-job, en doet dan:

curl -fsS -X POST "$CI_API_URL/admin/self-update" \
  -H "Authorization: Bearer $BLUEGIT_UPDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"ref\":\"${CI_COMMIT_SHA}\"}"

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). Het wacht de oneshot niet af: anders blijft de CI-job running en wacht de updater op de job die hem aanriep.

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 er geen job meer queued of running is, ook vóór pacman -U. 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 is anoniem te downloaden:

https://gitlab.com/Timfa/bluegit/-/archive/<commit>/bluegit-<commit>.tar.gz

De publish-job haalt die tarball zonder token op en zet de sha256 in de PKGBUILD. makepkg gebruikt dezelfde URL.

Source
1# AUR
2
3Elke 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.
4
5## Package
6
7Er is één source-package, `bluegit`. Geen `-bin`. De PKGBUILD haalt de GitLab-archieven op:
8
9```text
10https://gitlab.com/Timfa/bluegit/-/archive/<commit>/bluegit-<commit>.tar.gz
11```
12
13Die map heet `bluegit-<commit>`. `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`.
14
15De lokale `packaging/arch/PKGBUILD` blijft voor een build uit de werkboom. Die gaat niet naar de AUR.
16
17## Unit en install-hook
18
19De unit is de bestaande system-unit: `User=bluegit`, `ExecStart` met `/etc/bluegit/config.yml`, `StateDirectory=bluegit` voor `/var/lib/bluegit`. Geen `systemd --user`-unit.
20
21`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.
22
23De 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.
24
25## Geheimen
26
27De namen zijn 1-op-1 dezelfde als in Posprint. De publieke sleutel hoort op aur.archlinux.org, nooit de private sleutel in de repository.
28
29### GitLab (overgang)
30
31`.gitlab-ci.yml` blijft de pipeline op gitlab.com. Zet daar deze CI/CD-variabelen:
32
33| Naam | Soort | Inhoud |
34| --- | --- | --- |
35| `AUR_SSH_PRIVATE_KEY` | File, mask uit, protected mag | ruwe OpenSSH-sleutel (`BEGIN … PRIVATE KEY`). Een File met base64 wordt ook herkend. |
36| `AUR_SSH_PRIVATE_KEY_B64` | Variable, één regel, Masked+Protected | base64 van die sleutel. GitLab maskeert geen meerregelige waarde, daarom base64 of een File. |
37| `AUR_GIT_AUTHOR_NAME` | Variable | naam in de AUR-commit |
38| `AUR_GIT_AUTHOR_EMAIL` | Variable | e-mail in de AUR-commit |
39
40Eé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.
41
42De job heet `publish:aur`. Hij draait alleen als `CI_COMMIT_BRANCH` `master` is, met `allow_failure: true`.
43
44### BlueGit
45
46Steve 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`.
47
48Markeer 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.
49
50| Naam | Waarde |
51| --- | --- |
52| `AUR_SSH_PRIVATE_KEY` | ruwe OpenSSH-sleutel, of base64 daarvan. Eén sleutelgeheim is genoeg. |
53| `AUR_SSH_PRIVATE_KEY_B64` | dezelfde sleutel als één regel base64. |
54| `AUR_GIT_AUTHOR_NAME` | naam in de AUR-commit |
55| `AUR_GIT_AUTHOR_EMAIL` | e-mail in de AUR-commit |
56| `BLUEGIT_UPDATE_TOKEN` | dezelfde waarde als `BLUEGIT_UPDATE_TOKEN` in `/etc/bluegit/env` op de mini-PC |
57
58`publish_aur` draait op `master` en `main`, met `allow_failure: true` en `needs: []`, zodat hij meteen start en een AUR-storing de rest niet rood maakt. Een merge-request-pipeline slaat hem over.
59
60`self_update` draait in dezelfde stage, wacht op `build`, en roept daarna de draaiende instantie aan:
61
62```yaml
63curl -fsS -X POST "$CI_API_URL/admin/self-update" \
64 -H "Authorization: Bearer $BLUEGIT_UPDATE_TOKEN" \
65 -H "Content-Type: application/json" \
66 -d "{\"ref\":\"${CI_COMMIT_SHA}\"}"
67```
68
69`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`.
70
71## Lokaal publiceren
72
73Zolang 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.
74
75De 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.
76
77Het 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 <pkgver>` en pusht het naar `master`. `updpkgsums` komt uit `pacman-contrib`.
78
79## Self-update
80
81Een push naar `master` hoeft niet op de AUR te wachten. `publish_aur` publiceert parallel (`needs: []`, `allow_failure: true`). `self_update` staat in dezelfde stage en wacht alleen op `build`, niet op de AUR-job, en doet dan:
82
83```yaml
84curl -fsS -X POST "$CI_API_URL/admin/self-update" \
85 -H "Authorization: Bearer $BLUEGIT_UPDATE_TOKEN" \
86 -H "Content-Type: application/json" \
87 -d "{\"ref\":\"${CI_COMMIT_SHA}\"}"
88```
89
90`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`). Het wacht de oneshot niet af: anders blijft de CI-job `running` en wacht de updater op de job die hem aanriep.
91
92De 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.
93
94`/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`.
95
96Mislukt 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.
97
98Een POST die 202 teruggeeft is nog geen installatie. De unit wacht tot `BLUEGIT_UPDATE_TIMEOUT` (standaard 1800 seconden) tot er geen job meer `queued` of `running` is, ook vóór `pacman -U`. `openapi.json` blijft 404 zolang de oude binary draait.
99
100`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.
101
102De 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`.
103
104## Archief
105
106Het archief is anoniem te downloaden:
107
108```text
109https://gitlab.com/Timfa/bluegit/-/archive/<commit>/bluegit-<commit>.tar.gz
110```
111
112De publish-job haalt die tarball zonder token op en zet de sha256 in de PKGBUILD. `makepkg` gebruikt dezelfde URL.