edu/stem-launcher

Fork 0

Files

T

mpabi f121ef232f Rework token workflow documentation

2026-04-27 21:10:23 +02:00

8.5 KiB

Raw Blame History

Tokens

Ten dokument opisuje praktyczna obsluge tokenow Gitea w rvctl.

rvctl traktuje tokens.json jako lokalny store tokenow. Rekord tokena zawiera sekret, endpoint serwera, login uzytkownika oraz docelowe org/repo. Git remote jest tylko miejscem, z ktorego token mozna jednorazowo wczytac albo do ktorego mozna go tymczasowo wpisac, gdy Git ma wykonac fetch albo push.

Operacyjnie sa dwa zrodla stanu:

tokens.json - lokalny store sekretow i metadanych API
.git/config - konfiguracja git remotes w wybranym repo

rv-launcher jest domyslnym repo, na ktorym dzialaja komendy tokenow bez --repo. Dla kart pracy albo innych repo trzeba podac --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 compare

Po poprawnej synchronizacji compare powinien pokazac * przy r1.

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 usuwa git remote
remove 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.

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:

./rvctl tokens compare

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 remove remote r1
./rvctl tokens list store
./rvctl tokens compare

Wtedy compare 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 remove remote r1

Usuwanie

Usuwaj tylko to miejsce, ktore naprawde chcesz wyczyscic:

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

Znaczenie:

remove remote usuwa git remote i sekret z .git/config, ale zostawia store
remove store usuwa rekord z tokens.json, ale nie dotyka git remota
remove 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

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.

8.5 KiB Raw Blame History