florian.wilde/nebula
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 20 Wiki Activity

Feat #10: Token-Rechte vollständig dokumentiert #11

Merged
florian.wilde merged 2 commits from feat/10-token-rechte into main 2026-08-18 11:51:07 +00:00
Conversation 0 Commits 2 Files Changed 5
+291 -11
florian.wilde commented 2026-08-18 10:11:17 +00:00
Owner
Copy Link
Copy Source

Die dokumentierten Rechte stammten aus der Zeit, als Nebula nur gelesen hat. Seit v1.7.0 legt es Issues an und schließt sie — wer sich an die README oder den Hinweis im Verbindungsdialog hielt, bekam dabei einen 403.

Erhoben, nicht geraten

Jeder ausgehende Aufruf aus lib/git/gitea.ts, github.ts und gitlab.ts wurde erhoben und auf das nötige Recht abgebildet — aus dem Code, nicht aus dem Gedächtnis.

Nach Funktion aufgeschlüsselt

Damit erkennbar ist, was sich weglassen lässt:

System Nur Abgleich Zusätzlich für die Issue-Anbindung
GitHub Metadata, Contents, Issues, Pull requests, Actions — je lesend Issues: Read and write
GitLab read_api api
Gitea / Forgejo read:repository, read:issue, read:user write:issue

GitLab ist der unangenehme Fall

GitLab kennt keinen schmalen Schreib-Scope für Issues. Wer die Issue-Anbindung dort nutzen will, braucht api — also alles, was das Konto darf, Code eingeschlossen.

Das steht jetzt ausdrücklich da, samt der Alternative: bei read_api bleiben und auf die Issue-Anbindung verzichten. Der Abgleich läuft dann vollständig, und geschlossene Issues werden weiterhin erkannt (seit v1.9.0 prüft der Abgleich das selbst) — nur zurückgeschrieben wird nichts.

Ich stelle das als Abwägung dar, nicht als Empfehlung, einfach api zu setzen.

Was Nebula nicht braucht

Ebenfalls festgehalten: keine Schreibrechte auf Code, keine Adminrechte, keine Rechte zum Anlegen von Webhooks. Letzteres ist genau der Grund, warum der Haken von Hand im Git-System eingetragen wird — so bleibt der Token davon frei.

Der Hinweis in der Anwendung

tokenHelp in lib/git/meta.ts steht direkt unter dem Token-Feld und ist die Stelle, die tatsächlich gelesen wird. Auch dort war es rein lesend formuliert — mitgezogen.

Dazu ein Wächter in meta.test.ts: jeder Provider muss in GitClient createIssue und setIssueState können, folglich muss auch jeder Hinweis sagen, was das an Rechten kostet. Genau diese Kopplung war hier gerissen.

Geprüft

  • 267 Unit-Tests (6 neue), 36 E2E-Tests
  • Hinweistext je System gegen die laufende Anwendung gelesen — alle drei erscheinen korrekt unter dem Eingabefeld
  • axe-core auf 375 px und 1280 px: 0 Verstöße, kein seitlicher Überlauf

Closes #10

Die dokumentierten Rechte stammten aus der Zeit, als Nebula nur **gelesen** hat. Seit v1.7.0 legt es Issues an und schließt sie — wer sich an die README oder den Hinweis im Verbindungsdialog hielt, bekam dabei einen `403`. ## Erhoben, nicht geraten Jeder ausgehende Aufruf aus `lib/git/gitea.ts`, `github.ts` und `gitlab.ts` wurde erhoben und auf das nötige Recht abgebildet — aus dem Code, nicht aus dem Gedächtnis. ## Nach Funktion aufgeschlüsselt Damit erkennbar ist, was sich weglassen lässt: | System | Nur Abgleich | Zusätzlich für die Issue-Anbindung | | --- | --- | --- | | **GitHub** | *Metadata*, *Contents*, *Issues*, *Pull requests*, *Actions* — je lesend | *Issues: Read and write* | | **GitLab** | `read_api` | `api` | | **Gitea / Forgejo** | `read:repository`, `read:issue`, `read:user` | `write:issue` | ## GitLab ist der unangenehme Fall GitLab kennt **keinen schmalen Schreib-Scope für Issues**. Wer die Issue-Anbindung dort nutzen will, braucht `api` — also alles, was das Konto darf, Code eingeschlossen. Das steht jetzt ausdrücklich da, samt der Alternative: bei `read_api` bleiben und auf die Issue-Anbindung verzichten. Der Abgleich läuft dann vollständig, und geschlossene Issues werden weiterhin erkannt (seit v1.9.0 prüft der Abgleich das selbst) — nur zurückgeschrieben wird nichts. Ich stelle das als Abwägung dar, nicht als Empfehlung, einfach `api` zu setzen. ## Was Nebula *nicht* braucht Ebenfalls festgehalten: keine Schreibrechte auf Code, keine Adminrechte, keine Rechte zum Anlegen von Webhooks. Letzteres ist genau der Grund, warum der Haken von Hand im Git-System eingetragen wird — so bleibt der Token davon frei. ## Der Hinweis in der Anwendung `tokenHelp` in `lib/git/meta.ts` steht direkt unter dem Token-Feld und ist die Stelle, die tatsächlich gelesen wird. Auch dort war es rein lesend formuliert — mitgezogen. Dazu ein **Wächter** in `meta.test.ts`: jeder Provider muss in `GitClient` `createIssue` und `setIssueState` können, folglich muss auch jeder Hinweis sagen, was das an Rechten kostet. Genau diese Kopplung war hier gerissen. ## Geprüft - 267 Unit-Tests (6 neue), 36 E2E-Tests - Hinweistext je System gegen die laufende Anwendung gelesen — alle drei erscheinen korrekt unter dem Eingabefeld - axe-core auf 375 px und 1280 px: 0 Verstöße, kein seitlicher Überlauf Closes #10
florian.wilde added 1 commit 2026-08-18 10:11:18 +00:00
Token-Rechte vollstaendig dokumentiert
CI / pruefen (pull_request) Canceled after 0s
Details
7920b6a20f 
Die Angaben stammten aus der Zeit, als Nebula nur gelesen hat. Seit v1.7.0
legt es Issues an und schliesst sie - wer sich an README oder den Hinweis im
Verbindungsdialog hielt, bekam dabei einen 403.

Erhoben wurde es nicht aus dem Gedaechtnis, sondern aus dem Code: jeder
ausgehende Aufruf in lib/git/gitea.ts, github.ts und gitlab.ts, abgebildet
auf das noetige Recht.

Aufgeschluesselt nach Funktion statt nach System, damit erkennbar ist, was
sich weglassen laesst: der Abgleich allein kommt rein lesend aus, nur die
Issue-Anbindung schreibt.

**GitLab ist der unangenehme Fall.** Es kennt keinen schmalen Schreib-Scope
fuer Issues - dort geht nur "api", also alles, was das Konto darf. Das steht
jetzt ausdruecklich da, samt der Alternative: bei read_api bleiben und auf
die Issue-Anbindung verzichten. Der Abgleich laeuft dann vollstaendig, und
geschlossene Issues werden weiterhin erkannt, nur nicht zurueckgeschrieben.

Ebenfalls festgehalten, was Nebula *nicht* braucht: Schreibrechte auf Code,
Adminrechte, Rechte zum Anlegen von Webhooks. Letzteres ist der Grund, warum
der Haken von Hand eingetragen wird - so bleibt der Token davon frei.

Der Hinweis in lib/git/meta.ts steht direkt am Eingabefeld und ist die
Stelle, die tatsaechlich gelesen wird; er ist deshalb mitgezogen. Dazu ein
Waechter in meta.test.ts: jeder Provider muss in GitClient createIssue und
setIssueState koennen, folglich muss auch jeder Hinweis sagen, was das an
Rechten kostet. Genau diese Kopplung war hier gerissen.

Geprueft: 267 Unit-Tests (6 neue), 36 E2E-Tests, Hinweistext je System gegen
die laufende Anwendung gelesen, axe-core auf 375px und 1280px ohne
Beanstandung.

Refs #10
florian.wilde added 1 commit 2026-08-18 10:57:11 +00:00
docs(git): jeden ausgehenden Aufruf einzeln mit seinem Recht belegen
CI / pruefen (pull_request) Canceled after 0s
Details
e9f01ba8fa 
Die Faelle A und B beantworteten die Frage auf Ebene der Scopes, nicht
auf Ebene der Aufrufe. Wer nachpruefen wollte, ob ein Recht wirklich
noetig ist, musste die drei Clients selbst lesen.

Jetzt steht in der README je System eine vollstaendige Tabelle: Aufruf,
Zweck, benoetigtes Recht. Die Zuordnung bei GitHub folgt der offiziellen
Berechtigungsuebersicht - dass /tags und /stats/commit_activity unter
Metadata fallen und nicht unter Contents, ist nicht zu erraten. Fuer
GitLab ist mit Quellenangabe belegt, dass es unterhalb von 'api' keinen
Schreibzugriff auf Issues gibt.

Ausserdem war offen, woher die Kommentare an den Issues stammen: Nebula
schreibt keine. Der Schreibzugriff besteht aus genau zwei Aufrufen. Ein
Test klopft dafuer die Clients ab - kaeme ein dritter dazu, wuerde die
Empfehlung 'nimm ein lesendes Token' still falsch, ohne dass jemand
einen Fehler saehe.

Der Hinweis am Eingabefeld nannte Actions nicht, obwohl der CI-Zustand
bei GitHub genau daran haengt.

Refs #10
florian.wilde merged commit 77567c06cd into main 2026-08-18 11:51:07 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
blockiert
Offene Rueckfrage, Uhr steht
 in-arbeit
Claude arbeitet daran, Zeiterfassung laeuft
 zu-testen
Umgesetzt, PR offen, wartet auf Test
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
florian.wilde (Florian Wilde)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: florian.wilde/nebula#11