edu/stem-launcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
edab6c268a268bafb173ebb5756c0233b56ea8bb
stem-launcher/doc/tokens.md
T
mpabi b67c5b5204 Use Polish diacritics in docs
2026-04-29 02:09:30 +02:00

9.4 KiB
Raw Blame History

Tokens

rvctl obsługuje tokeny Gitea w dwóch miejscach:

  • tokens.json - lokalny store sekretów i metadanych tokenów
  • .git/config - git remotes w konkretnym repo

Rekord w tokens.json zawiera token, endpoint serwera, login oraz docelowe org/repo. Git remote służy tylko do operacji Git (fetch, push) albo do pierwszego wczytania tokena do store.

Bez --repo komendy tokenów działają na repo rv-launcher. Dla kart pracy albo innych repo podaj --repo PATH.

Szybki przepływ

Startujemy od git remota z tokenem w URL-u:

git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git

Sprawdzamy, co jest zapisane w remote i store:

./rvctl tokens list remote
./rvctl tokens list store
./rvctl tokens list both

Kopiujemy token z remota do tokens.json:

./rvctl tokens sync remote r1

Pobieramy z API metadane tokena:

./rvctl tokens update r1

Sprawdzamy zgodność remote i store:

./rvctl tokens cmp

Po poprawnej synchronizacji compare/cmp powinien pokazać * przy r1.

Jeśli chcesz sprawdzić, czy store da się odtworzyć z remota, usuń tylko rekord ze store i wczytaj go ponownie z git remota:

./rvctl tokens rm store r1
./rvctl tokens sync remote r1
./rvctl tokens update r1
./rvctl tokens cmp

Po sync remote metadane API są ustawiane na ?, dlatego update jest zawsze kolejnym krokiem.

Dwa Źródła

rvctl rozróżnia dwa miejsca:

  • git remote w repo, np. http://u1:SECRET@host/org/repo.git
  • lokalny store ~/dev/workspace/rv/tokens/tokens.json

Komendy zapisujące store same tworzą katalog nadrzędny, jeżeli go nie ma. Katalog tokens dostaje prawa 700, a plik tokens.json prawa 600.

Kierunki są jawne:

  • sync remote r1 czyta git remote i zapisuje rekord do tokens.json
  • sync store r1 czyta tokens.json i zapisuje auth do git remota
  • update r1 nie synchronizuje sekretu, tylko odświeża metadane z API
  • remove remote r1 albo rm remote r1 usuwa git remote
  • remove store r1 albo rm store r1 usuwa rekord z tokens.json

Listowanie

list pokazuje źródła bez porównywania:

./rvctl tokens list store
./rvctl tokens list remote
./rvctl tokens list both

Znaczenie:

  • store - rekordy zapisane w tokens.json
  • remote - git remotes zapisane w .git/config
  • both - oba źródła jako osobne wiersze

Dla innego repo podaj --repo:

./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03

Synchronizacja

Remote -> Store

Użyj, gdy token jest w git remote i chcesz go zapisać w store:

./rvctl tokens sync remote r1

Ta komenda kopiuje sekret, usera, endpoint, org i repo z URL-a remota do tokens.json. Nie pyta API o uprawnienia, więc zawsze zeruje metadane API: valid ustawia na ?, maski scope, org_perm i repo_perm ustawia na ?, a expires_at usuwa. Realne uprawnienia wpisuje dopiero:

./rvctl tokens update r1

Store -> Remote

Użyj, gdy token jest już w tokens.json, a chcesz utworzyć albo odświeżyć git remote:

./rvctl tokens sync store r1

Jeśli remote r1 nie istnieje, rvctl buduje URL z pól server.endpoint, org i repo w tokens.json, na przykład:

http://77.90.8.171:3001/edu-tools/rv-launcher.git

Opcjonalnie można podać URL ręcznie:

./rvctl tokens sync store r1 --url http://77.90.8.171:3001/edu-tools/rv-launcher.git

Jeśli remote ma już inne credentials, użyj:

./rvctl tokens sync store r1 --replace

Aktualizacja Metadanych

Po zapisaniu tokena w store odśwież jego metadane z API:

./rvctl tokens update r1

update zapisuje w tokens.json:

  • valid
  • scope
  • org_perm
  • repo_perm

Ta komenda nie zmienia git remota i nie kopiuje sekretu.

Porównanie

compare sprawdza zgodność store i remote. Skrót: cmp.

./rvctl tokens compare
./rvctl tokens cmp

Marker w kolumnie token_ref:

  • * - store i remote są zgodne
  • S - token jest tylko w store
  • R - token jest tylko w remote
  • ! - wpis jest sparowany, ale token jest invalid albo wystąpił błąd API

Gdy marker to S, token nie jest błędny. To znaczy tylko, że nie ma odpowiadającego git remota.

Store-only

Po pierwszej konfiguracji wygodny tryb pracy to trzymanie tokena tylko w tokens.json.

./rvctl tokens rm remote r1
./rvctl tokens list store
./rvctl tokens cmp

Wtedy compare/cmp pokazuje S, a list store nadal pokazuje znane metadane tokenu. Gdy trzeba wykonać operacje git przez remote, odtwórz remote:

./rvctl tokens sync store r1

Po operacji można go znowu usunąć:

./rvctl tokens rm remote r1

Usuwanie

Usuwaj tylko to miejsce, które naprawdę chcesz wyczyścić:

./rvctl tokens rm remote r1
./rvctl tokens rm store r1
./rvctl tokens rm both r1

Znaczenie:

  • remove remote / rm remote usuwa git remote i sekret z .git/config, ale zostawia store
  • remove store / rm store usuwa rekord z tokens.json, ale nie dotyka git remota
  • remove both / rm both usuwa oba miejsca

Inne Repo

Domyślnie komendy tokenów pracują na repo zawierającym rvctl. Dla kart pracy albo innych repo podaj --repo.

./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens compare --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03

Store tokenów nadal pozostaje jeden:

~/dev/workspace/rv/tokens/tokens.json

Pozostałe Komendy

tokens read

Pokazuje zawartość tokens.json.

./rvctl tokens read
./rvctl tokens read --server http://77.90.8.171:3001
./rvctl tokens read --show-secrets

tokens add

Dodaje szkielet rekordu do tokens.json. REMOTE_ID musi odpowiadać nazwie git remote. Przełączniki są opcjonalne; jeśli ich nie podasz, rvctl zapisuje puste wartości do późniejszego uzupełnienia. Wyjątkiem jest server, który domyślnie pochodzi z workspace.json.

./rvctl tokens add r1
./rvctl tokens add r1 --server http://77.90.8.171:3001 --user u1 --org edu-tools --repo rv-launcher

Najczęściej pusty szkielet ma sens wtedy, gdy chcesz ręcznie wpisać token w tokens.json. sync store r1 nie użyje pustego tokena. Najpierw trzeba uzupełnić co najmniej value i user. Jeśli remote ma być tworzony bez --url, potrzebne są też org i repo.

tokens stats

Pokazuje kontekst, tabelę tokens i podsumowanie statusów endpointów.

./rvctl tokens stats
./rvctl tokens stats --repo ~/dev/workspace/rv/tools/rv-launcher

Uprawnienia

W tokens.json uprawnienia są zapisane jako mapy klucz-wartość. W tabelach CLI są pokazywane jako zwarte maski.

Nagłówki masek:

  • scope: aAimnopru
  • org: oawrc-
  • repo: oawr--

Kategorie scope:

  • a - activitypub
  • A - admin
  • i - issue
  • m - misc
  • n - notification
  • o - organization
  • p - package
  • r - repository
  • u - user

Wartości w scope:

  • w - read/write
  • r - read
  • - - no access
  • ? - nie wczytano
  • ! - błąd wczytania

Gitea może zwrócić globalny scope all zamiast listy write:*. Launcher rozwija wtedy all do pełnej maski wwwwwwwww. Scope public-only jest flagą ograniczenia widoczności API i nie zmienia kategorii w tej masce.

Kategorie org_perm:

  • o - owner
  • a - admin
  • w - write
  • r - read
  • c - create repository

Kategorie repo_perm:

  • o - owner
  • a - admin
  • w - write
  • r - read

Wartości w org_perm i repo_perm:

  • + - flaga włączona
  • - - flaga wyłączona
  • ? - nie wczytano
  • ! - błąd wczytania

Model Danych

tokens.json ma format version: 3. Głównym rekordem jest jeden remote-token. Pole id jest obowiązkowe i musi być takie samo jak nazwa git remote, np. r1 albo r1a.

Pola synchronizowane z git remote:

  • id - nazwa git remote, np. r1
  • server.endpoint - endpoint serwera, np. http://77.90.8.171:3001
  • server.type - typ serwera, np. gitea, github, gitlab, unknown
  • user - login z URL-a, czyli lewa strona http://u1:SECRET@...
  • value - sekret tokena
  • org - organizacja z URL-a
  • repo - repo z URL-a

Pola pobierane z API przez tokens update r1:

  • valid - forever, data wygaśnięcia, invalid, ? albo !
  • scope - mapa scope tokena
  • org_perm - mapa praw użytkownika w organizacji
  • repo_perm - mapa praw użytkownika w repo

tokens sync remote r1 nadpisuje pola z git remota i oznacza te metadane jako nieznane. To celowe: po zmianie sekretu, usera albo repo stare metadane API nie są już wiarygodne.

Minimalny przykład:

{
  "version": 3,
  "tokens": [
    {
      "id": "r1",
      "value": "SECRET",
      "server": {
        "type": "gitea",
        "endpoint": "http://77.90.8.171:3001",
        "scheme": "http",
        "host": "77.90.8.171",
        "port": 3001
      },
      "user": "u1",
      "org": "edu-tools",
      "repo": "rv-launcher"
    }
  ]
}

Przykład po tokens update r1 może dodatkowo zawierać:

{
  "valid": "forever",
  "scope": {
    "a": "w",
    "A": "w",
    "i": "w",
    "m": "w",
    "n": "w",
    "o": "w",
    "p": "w",
    "r": "w",
    "u": "w"
  },
  "org_perm": {
    "o": "+",
    "a": "+",
    "w": "+",
    "r": "+",
    "c": "+"
  },
  "repo_perm": {
    "o": "+",
    "a": "+",
    "w": "+",
    "r": "+"
  }
}

Pełny schemat pliku jest w doc/tokens.schema.json.

Reference in New Issue View Git Blame Copy Permalink