edu/stem-launcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d1d23e1cc41267a1afa934645255a7b3cdc55c8
stem-launcher/doc/tokens.md
T
mpabi 6d1d23e1cc Document remote token restore flow
2026-04-27 21:27:51 +02:00

9.1 KiB
Raw Blame History

Tokens

rvctl obsluguje tokeny Gitea w dwoch miejscach:

  • tokens.json - lokalny store sekretow i metadanych tokenow
  • .git/config - git remotes w konkretnym repo

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

Bez --repo komendy tokenow dzialaja na repo rv-launcher. Dla kart pracy albo innych repo podaj --repo PATH.

Szybki Flow

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 zgodnosc remote i store:

./rvctl tokens cmp

Po poprawnej synchronizacji compare/cmp powinien pokazac * przy r1.

Jesli chcesz sprawdzic, czy store da sie odtworzyc z remota, usun 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 sa ustawiane na ?, dlatego update jest zawsze kolejnym krokiem.

Dwa Zrodla

rvctl rozroznia dwa miejsca:

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

Kierunki sa 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 odswieza 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 zrodla bez porownywania:

./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 zrodla jako osobne wiersze

Dla innego repo podaj --repo:

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

Synchronizacja

Remote -> Store

Uzyj, gdy token jest w git remote i chcesz go zapisac 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, wiec 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

Uzyj, gdy token jest juz w tokens.json, a chcesz utworzyc albo odswiezyc git remote:

./rvctl tokens sync store r1

Jesli remote r1 nie istnieje, rvctl buduje URL z pol server.endpoint, org i repo w tokens.json, na przyklad:

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

Opcjonalnie mozna podac URL recznie:

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

Jesli remote ma juz inne credentials, uzyj:

./rvctl tokens sync store r1 --replace

Aktualizacja Metadanych

Po zapisaniu tokena w store odswiez 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.

Porownanie

compare sprawdza zgodnosc store i remote. Skrot: cmp.

./rvctl tokens compare
./rvctl tokens cmp

Marker w kolumnie token_ref:

  • * - store i remote sa zgodne
  • S - token jest tylko w store
  • R - token jest tylko w remote
  • ! - wpis jest sparowany, ale token jest invalid albo wystapil blad API

Gdy marker to S, token nie jest bledny. To znaczy tylko, ze nie ma odpowiadajacego 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 wykonac operacje git przez remote, odtworz remote:

./rvctl tokens sync store r1

Po operacji mozna go znowu usunac:

./rvctl tokens rm remote r1

Usuwanie

Usuwaj tylko to miejsce, ktore naprawde chcesz wyczyscic:

./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

Domyslnie komendy tokenow pracuja na repo zawierajacym 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 tokenow nadal pozostaje jeden:

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

Pozostale Komendy

tokens read

Pokazuje zawartosc 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 odpowiadac nazwie git remote. Przelaczniki sa opcjonalne; jesli ich nie podasz, rvctl zapisuje puste wartosci do pozniejszego uzupelnienia. Wyjatkiem jest server, ktory domyslnie 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

Najczesciej pusty szkielet ma sens wtedy, gdy chcesz recznie wpisac token w tokens.json. sync store r1 nie uzyje pustego tokena. Najpierw trzeba uzupelnic co najmniej value i user. Jesli remote ma byc tworzony bez --url, potrzebne sa tez org i repo.

tokens stats

Pokazuje kontekst, tabele tokens i podsumowanie statusow endpointow.

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

Uprawnienia

W tokens.json uprawnienia sa zapisane jako mapy klucz-wartosc. W tabelach CLI sa pokazywane jako zwarte maski.

Naglowki 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

Wartosci w scope:

  • w - read/write
  • r - read
  • - - no access
  • ? - nie wczytano
  • ! - blad wczytania

Gitea moze zwrocic globalny scope all zamiast listy write:*. Launcher rozwija wtedy all do pelnej maski wwwwwwwww. Scope public-only jest flaga ograniczenia widocznosci 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

Wartosci w org_perm i repo_perm:

  • + - flaga wlaczona
  • - - flaga wylaczona
  • ? - nie wczytano
  • ! - blad wczytania

Model Danych

tokens.json ma format version: 3. Glownym rekordem jest jeden remote-token. Pole id jest obowiazkowe i musi byc 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 wygasniecia, invalid, ? albo !
  • scope - mapa scope tokena
  • org_perm - mapa praw uzytkownika w organizacji
  • repo_perm - mapa praw uzytkownika 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 sa juz wiarygodne.

Minimalny przyklad:

{
  "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"
    }
  ]
}

Przyklad po tokens update r1 moze dodatkowo zawierac:

{
  "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": "+"
  }
}

Pelny schemat pliku jest w doc/tokens.schema.json.

Reference in New Issue View Git Blame Copy Permalink