Aquesta eina serveix per a recollir mètriques dels repositoris d'una organització. A continuació s'expliquen els passos per a configurar-la. Aquests passos cal que els faci el propietari (owner) de l'organització de GitHub de la que es vol recollir les mètriques.
El primer que cal fer és crear un repositori públic nou a l'organització a partir d'aquest template, amb el botó Use this template i l'opció Create a new repository a dalt a la dreta d'aquest repositori:
Al crear-lo, marqueu la casella Include all branches, que el Owner sigui la vostra organització i que sigui públic. En aquest exemple, l'organització s'anomena ProvaMetriques:
Un cop creat s'executarà el GitHub actions i fallarà, ja que encara no està configurat, per tant, és normal i podeu ignorar-ho de moment.
Per continuar, cal anar a la branca gh-pages, o si no s'ha marcat la casella Include all branches crear-la, obrir docs/config.json i posar a excluded_repos el nom del repo que acabeu de crear (només el nom). És molt important fer-ho a la branca gh-pages, si ho feu a main o master no funcionarà. Pel que fa als membres de l'organització que són professors i bots, heu de posar els seus noms d'usuari a excluded_members (per exemple: carlesf). Després us heu d'assegurar que metrics_scope i members posi org (ja hauria d'estar configurat així per defecte). Un cop heu acabat, feu commit a la branca gh-pages.
En la següent imatge hi ha un exemple, on el repositori per a les mètriques es diu Metrics i hi ha un bot i un professor:
Després heu d'anar a configuració, i dintre de la categoria Code and automation, anar a Pages, i un cop a Pages, deixeu Source a Deploy from a branch, i a branch poseu la branca gh-pages i canvieu la carpeta de /(root) a /docs i cliqueu save.
Un cop fet això podeu tornar a la pàgina de Code i a la secció About a la dreta de la pantalla, si cliqueu per configurar a l'engranatge, ressaltat en blau a la imatge que hi ha a continuació, hi ha un apartat que es diu website, i una checkbox Use your GitHub Pages website, marqueu-la i feu Save Changes. Podeu copiar aquest link i posar-lo al About de tots els repositoris de la vostra organització. Si aneu ara a la pàgina, us dirà que encara no hi ha metrics.json, però només funcionarà si continueu amb la configuració.
L'últim pas és anar a la configuració de l'usuari que és el propietari de l'organització i anar a Developer setting (a baix de tot).
Un cop a Developer setting, heu d'anar Personal access tokens i Fine-graiend tokens, i donar-li a Generate new token. Si no heu creat mai cap, es veurà com la primera captura, si ja heu creat algun, es veurà com a la segona.
Poseu-li el nom que vulgueu (metrics, p. ex). Heu de canviar el Resource Owner del token a l'organització, i això només ho pot fer el propietari de l'organització, per això és important que ho faci aquest. També poseu una Expiration date que duri fins al final del projecte, si per exemple és un projecte que entregueu el 19 de desembre, podeu posar una setmana més.
A Repository acces poseu All repositories.
A Repository permissions heu de seleccionar:
-Actions: read and write
-Contents: read-only
-Issues: read-only
-Pull requests: read-only
A Organization permissions heu de seleccionar:
-Members: read-only
-Projects: read-only
Si ho heu seleccionat tot bé, quan li doneu a Generate token, us sortiran els permisos següents:
Un cop generat, copieu el token temporalment a algun lloc, com a un arxiu de text, perquè un cop sortiu de la pàgina ja no podreu veure'l més.
Ara heu d'anar al repositori que heu creat, configuració i a l'apartat Security, aneu a Secrets and variables, i seleccioneu Actions, i veureu que hi ha una pestanya Secrets ja seleccionada.
Heu de crear un nou Secret amb el botó verd New repository secret. És molt important que sigui a Secrets i no variables, perquè no funcionarà i a més a més tothom podria veure el token, que per seguretat ha de ser privat. A name, en aquest cas cal que li poseu de nom ORG_TOKEN perquè funcioni, i enganxeu el token que heu copiat abans a l'apartat Secret, i cliqueu Add secret. Encara no borreu l'arxiu amb el token copiat.
Ara el repositori de mètriques ja està configurat del tot, però perquè reculli mètriques quan feu push, creeu pull requests, o modifiqueu issues a altres repositoris, cal que configureu a cada repositori una última cosa.
Per a cada repositori de la vostra organització, cal seguir els pasos per afegir el token a cadascun d'ells, amb el mateix nom, ORG_TOKEN, i per últim, heu de copiar els arxius trigger_workflow.yml i remote_repo.json que són a la carpeta docs del repositori que acabeu de crear, poseu el nom del repositori amb el format owner/name, on owner és l'organització i name és el nom del repositori, i a cada un dels repositoris, important que sigui a la branca main o master, crear una carpeta .github, el punt davant és important, amb una altra a dins que es digui workflows, i a dins posar els dos arxius. Un cop fet això, ja està configurat tot el repositori. Un cop posat el token a tots els repositoris, ja podeu eliminar l'arxiu de text temporal amb el token. Aquest token es perdrà, però si us fa falta afegir un altre repositori, sempre en podeu crear un de nou amb els mateixos permisos.
Aquí hi ha l'exemple de remote_repo.json en un repositori diferent del de mètriques de l'organització ProvaMetriques, on surt el nom del repositori de mètriques, que es diu Metrics:
Ara ja està configurada l'eina, i no cal que feu res més. Podeu visitar sempre que vulgueu la pàgina web, que sempre tindrà la informació més actualitzada.