Guia del professor — Sessió 5 (Fase 5)

«Crear apps amb IA, des de zero»

Munta la canonada: del merge al desplegament. Avui és la sessió més tècnica del curs (CI/CD), però amb un gir clau: no la lideres tu a la pantalla escrivint comandes. La munta l'agent de cada alumne: l'alumne li dona un prompt mestre i l'agent crea el .clasp.json, el workflow de GitHub Actions i li diu quin secret afegir. Tu fas de xarxa de seguretat quan un agent s'encalla. L'objectiu: muntar una sola vegada una canonada de CI/CD perquè, cada cop que es fusioni un canvi a main, l'app es publiqui sola al /exec, sense tocar Apps Script. A partir d'avui: desplegar = fusionar. És presencial, com la S1 i la S3.


1. Fitxa de la sessió

Camp Detall
Sessió 5 (Fase 5) — Munta la canonada: del merge al desplegament
Format Presencial amb tu. És la sessió més tècnica del curs, però la fa l'agent; tu ets la xarxa de seguretat
Durada total ~150 min (2 h 30 min), amb una pausa curta
Objectiu Que cada alumne munti una vegada una canonada de CI/CD (GitHub Action amb clasp dins) perquè fusionar a main publiqui sol al /exec, i que entengui i sàpiga depurar aquest flux
Material de l'alumne Portàtil (avui sí, de debò), compte personal de Google, compte i repo de GitHub (S3) amb la seva app, domini del flux branca → PR → revisió → merge (S4), el seu Script ID d'Apps Script a mà i el correu per autoritzar
Material teu Projector/bona connexió, la canonada sencera ja muntada per tu abans (amb un agent, perquè coneguis cada error real), un repo de prova amb una app d'Apps Script, un workflow d'exemple que funcioni, i tenir localitzats: clasp login, l'activació de l'API d'Apps Script i la creació del secret (a mà i amb gh)

Què s'enduen (resultats d'aprenentatge)

Requisits previs (comprova'ls a l'inici)

  1. El repositori de la S3/S4 amb la seva app a dins (Codi.gs, Index.html, carpeta context/).
  2. Dominar el flux de la S4: branca → PR → revisió → merge. Avui hi posem el desplegament a sobre.
  3. El seu Script ID d'Apps Script a mà (a Apps Script: Configuració del projecte → ID) i el correu del compte amb què autoritzaran.

El que canvia respecte de la S4: fins ara, fusionar no publicava res —seguien copiant a Apps Script a mà—. Avui muntem la peça que faltava: el merge publica sol. El flux d'abans (branca → PR → revisió → merge) agafa tot el sentit.

Avui el portàtil no és opcional. Es treballa al Codespace, amb la terminal, el gh i la pestanya Actions. Amb mòbil no es fa.


2. Preparació prèvia del professor (CRÍTICA — dedica-hi molt)

Aquesta és la part més important de la guia. La canonada fallarà la primera vegada gairebé sempre (nom del secret, API no activada, Script ID, versió de l'acció o de clasp, permisos). Si TU l'has muntada abans amb un agent, coneixeràs cada error real i podràs desencallar en segons. Si no, t'enxamparà en directe. Dedica-hi el temps que calgui: és el que farà que la sessió surti bé.

Munta la canonada sencera, de zero, amb un agent, abans de la classe:

No t'inventis versions ni rutes. Les comandes de clasp, els noms de les accions de GitHub i les pantalles de Google canvien sovint. Quan ho muntis, apunta't les versions que et van funcionar a tu i digues a classe que cal comprovar-ho (deixa que l'agent porti l'última versió).

Prepara el missatge del dia: «Avui no us ensenyo jo comandes a la pantalla. Cada agent munta la canonada. Jo soc aquí per desencallar quan peti —i petarà, és normal—. I recordeu: clasp viu dins de l'Action, no a la vostra terminal. A partir d'avui, desplegar = fusionar.»


3. Minutat bloc a bloc (~150 min)

Porta el rellotge a la mà. El cor del dia és: l'agent munta la canonada (Bloc B) → els 3 clics de l'alumne (Bloc C) → provar-la (Bloc D) → depurar quan falla (Bloc E). El Bloc E NO és un imprevist: és part del pla, perquè gairebé sempre falla el primer cop. Protegeix-lo: si vas just, sacrifica l'obertura llarga, no la depuració.

# Bloc Min Acumulat
A Obertura: per què (merge = deploy; clasp dins l'Action) 15 15
B L'agent munta la canonada (el prompt mestre: .clasp.json + workflow) 30 45
C Els 3 clics que només pot fer l'alumne (login, API, secret) 30 75
— Pausa curta 5 80
D Provar la canonada (branca → PR → merge → Actions → /exec) 25 105
E Quan l'Action falla (el bucle de depuració del CI/CD) 25 130
F Protegeix main (un ruleset: ningú hi puja directe, només via PR) 10 140
G Tancament i pont a la Fase 6 10 150

Total: 150 minuts.

Per què el Bloc E és tan llarg: perquè és on s'aprèn de debò. La primera execució falla gairebé sempre, i corregir-la (amb l'agent) és exactament el bucle de depuració que ja dominen, ara aplicat al CI/CD. No el corris ni el tractis com un problema: és el contingut.


Bloc A — Obertura: per què (15 min)

Curta i clara. L'objectiu és que entenguin dues decisions abans de tocar res: merge = deploy i clasp dins de l'Action.

Frase per repetir: «Desplegar = fusionar. clasp viu dins de l'Action, no a la teva terminal.»

Bloc B — L'agent munta la canonada (30 min)

Aquí l'alumne dona el prompt mestre (Annex B) al seu agent i l'agent munta la infraestructura. Agnòstic d'eina: si l'agent té mode agent (executa ordres), fa la feina ell; si és només xat, dona els fitxers/ordres perquè l'alumne els enganxi (flux copiar-enganxar, com sempre).

  1. Enganxar el prompt mestre (Annex B) al xat de l'agent, amb el seu Script ID ben posat. El prompt demana a l'agent que creï: - El .clasp.json (apunta al seu Script ID i diu on són els fitxers). - El workflow .github/workflows/deploy.yml que, en fer push a main, fa clasp push (puja el codi a Apps Script) i clasp deploy (publica una versió nova). - I que li digui clarament quin secret afegir (nom i d'on surt el valor).
  2. Si l'agent té mode agent: que el deixi crear els fitxers ell mateix al repo. Que comprovin que apareixen .clasp.json i .github/workflows/deploy.yml a l'explorador.
  3. Si l'agent és només xat: que copiï els fitxers que torna i els creï al repo a mà (a l'explorador del Codespace o per github.com). El mètode és copiar i enganxar, com sempre.
  4. El missatge central: «Tant és quin agent tingueu. Uns ho fan sols, altres us donen el text per enganxar. El resultat és el mateix: dos fitxers nous al repo i una instrucció clara de quin secret afegir.»

No revisis el workflow línia a línia a la pantalla. No és una classe de YAML. N'hi ha prou que el fitxer hi sigui i que l'alumne entengui què fa (en fer push a main: puja + publica). El detall el portarà l'agent; tu valides que existeix i que apunta al Script ID correcte.

Vigila el Script ID. L'error més silenciós del dia: que el .clasp.json apunti a un projecte equivocat (o a un de nou que crea l'agent) en lloc del projecte real lligat al seu full. Recorda'ls: el Script ID surt de Apps Script → Configuració del projecte, del seu projecte.

Bloc C — Els 3 clics que només pot fer l'alumne (30 min)

El bloc més humà del dia. L'agent ho munta gairebé tot, però hi ha 3 coses que NO pot fer per ells, perquè són del seu compte de Google/GitHub. Insisteix: l'agent et DIU on clicar; tu només dius «sí, soc jo».

Clic 1 — clasp login (autoritzar + enganxar el codi): - Que executin el clasp login (l'agent els dona la comanda exacta). S'obre una autorització de Google: han de triar el compte correcte (el del seu full) i acceptar els permisos. - Els torna un codi: l'han d'enganxar on toqui per completar el login. Això genera la credencial (.clasprc.json) al seu Codespace. - Aquest valor és el que anirà al secret (Clic 3).

Clic 2 — activar l'API d'Apps Script: - Anar a la configuració del seu Google (script.google.com/home/usersettings) i posar a ON l'interruptor de l'API d'Apps Script. - «Sense això, clasp no pot tocar el vostre projecte. És un interruptor de seguretat del vostre compte: l'heu d'activar vosaltres.»

No et garanteixo la ruta exacta d'aquesta pantalla: Google la canvia. Tingues localitzat on és avui (ho hauràs vist a la preparació) i digues a classe que pot tenir un aspecte una mica diferent.

Clic 3 — afegir el secret a GitHub: - El workflow llegeix la credencial des d'un secret del repo (p. ex. CLASPRC_JSON). Cal crear-lo amb el valor del login (Clic 1). - Dues vies (agnòstic d'eina): - A mà: repo → Settings → Secrets and variables → Actions → New repository secret → nom (exactament el que demana el workflow) i valor (la credencial). - Amb el gh: l'agent pot proposar una comanda gh secret set ... (el gh ja està autenticat al Codespace). Però el valor surt del SEU login: l'agent no el pot inventar. - El nom ha de COINCIDIR amb el que diu el workflow. Aquest és l'error número 1 del bloc.

Frase per repetir: «L'agent ho fa; tu autoritzes. Aquests 3 clics són del teu compte: són teus i de ningú més.»

(Pausa curta de 5 min després d'aquest bloc: ve la part més intensa.)

Bloc D — Provar la canonada (25 min)

El moment «uau». Aquí es veu si la cinta transportadora funciona. Fan un canvi pel flux de la S4 i miren si l'app es publica sola.

  1. Un canvi petit i visible, pel flux que ja dominen: crear una branca → fer un canvi mínim amb l'agent (un text, un color) → commit + push a la branca → obrir un PR → (opcional, ràpid) revisió amb IA → merge a main.
  2. Mirar la pestanya Actions (a github.com): just després del merge, hi apareix l'execució del workflow en marxa (rodeta groga). «Aquesta és la màquina treballant: està agafant el vostre codi i publicant-lo.»
  3. El moment «uau»: quan l'Action es posa verda, obrir el /exec (o recarregar-lo) i veure el canvi publicat, sense haver tocat Apps Script. «Acabeu de desplegar fusionant. Mai més copiar a mà.»
  4. Tanca la idea: «El que fa estona era copiar i enganxar a Apps Script ara ho fa la canonada, sola. Vosaltres només heu fusionat.»

Si surt verda a la primera, celebra-ho fort —però avisa que és poc habitual—. El més probable és que falli, i això és el Bloc E. No ho visquis com un fracàs: estava previst.

Bloc E — Quan l'Action falla: el bucle de depuració del CI/CD (25 min) EL COR DEL DIA

Gairebé sempre falla el primer cop. I està molt bé: és exactament el bucle de depuració que dominen des de la S2, ara aplicat al CI/CD. El teu paper de xarxa de seguretat és aquí.

  1. L'Action es posa VERMELLA. Primer missatge: «Tranquils. Això NO és un problema, és el procés. Mai una canonada surt bé a la primera. Ara la depurem com hem depurat sempre.»
  2. El bucle, idèntic al de sempre: - Obrir l'execució vermella a Actions i buscar el log vermell (el pas que ha fallat). - Enganxar a l'agent: el log de l'error + el workflow (deploy.yml) + el .clasp.json si cal. Demanar-li què falla i com arreglar-ho (prompt de l'Annex B). - Aplicar el canvi que proposa (al workflow, al secret, a l'API…). - Tornar a executar (re-run de l'Action, o un nou push petit) i mirar si ara surt verda. - Repetir fins a verd. «Cada volta del bucle us acosta. És el que ja sabeu fer.»
  3. Els errors típics que veuràs (vegeu la taula de la secció 4 per a la solució): - Nom del secret que no coincideix amb el del workflow. - API d'Apps Script no activada (Clic 2 oblidat). - Script ID equivocat o d'un altre projecte. - Versió de l'acció/clasp desfasada. - Permisos del gh o del secret. - Action verda però el /exec no canvia (falta clasp deploy, o apunta a un deployment diferent).
  4. El teu rol: circula. Quan algú s'encalli més de 2–3 voltes, mira-li el log amb ell, identifica de quin dels errors típics es tracta i guia'l a enganxar el material correcte a l'agent. No els ho arreglis tu en silenci: que ho facin ells amb l'agent, perquè aprenguin el bucle.

Frase per repetir: «Si peta, és el bucle. Enganxa el log vermell + el workflow a l'agent, arregla, torna a executar.»

Celebra cada verd. Quan a algú li surt la primera execució verda després de depurar, fes-ho públic: «Ho ha aconseguit! I fixeu-vos que no ho he arreglat jo: ho ha depurat ell amb el seu agent. Així és com es treballa de debò.»

Bloc F — Protegeix main (10 min)

Ara que fusionar publica, main és sagrada de debò: la bloquem perquè ningú hi pugui pujar codi directament. Així l'única manera d'arribar a main (i, per tant, de publicar) és un pull request — esdevé impossible desplegar saltant-se la revisió de la S4. És una automatització més de la canonada: a banda de publicar, ara protegeix la versió bona.


Bloc G — Tancament i pont a la Fase 6 (10 min)


4. On s'encallaran i com desencallar-los (xarxa de seguretat)

Recorda el marc general: si peta, és el bucle (enganxar el log + workflow a l'agent). Aquesta taula és perquè TU reconeguis de seguida de quin error es tracta i guiïs l'alumne al material correcte.

Símptoma Causa Solució ràpida
clasp login no es completa No han autoritzat al Google correcte, o no han enganxat el codi Repetir el login triant el compte del seu full i acceptant els permisos; copiar el codi que torna i enganxar-lo on toqui. La credencial (.clasprc.json) ha de quedar generada.
L'Action falla amb error d'autorització/API API d'Apps Script desactivada (Clic 2) Anar a script.google.com/home/usersettings i posar a ON l'interruptor de l'API d'Apps Script. Tornar a executar.
L'Action no troba la credencial / falla al llegir el secret Nom del secret ≠ el que diu el workflow Que coincideixin exactament (p. ex. CLASPRC_JSON). Comprovar-ho al workflow i al secret (Settings → Secrets → Actions).
clasp publica però a un projecte que no és el seu Script ID equivocat al .clasp.json (o un de nou que ha creat l'agent) Posar l'Script ID real del projecte lligat al seu full (Apps Script → Configuració del projecte → ID).
L'agent ha creat un projecte d'Apps Script nou Ha confós el projecte lligat al full amb un de nou Apuntar el .clasp.json al projecte lligat al full (el que publica el /exec que ja coneixen), no a un de nou.
Error de permisos del gh o del secret El gh no té permís per crear secrets, o el repo no ho permet Crear el secret a mà (Settings → Secrets and variables → Actions → New repository secret). El gh és una comoditat, no una obligació.
No es pot protegir main / la protecció demana pagament Repo privat amb protecció «clàssica» (de pagament) Fer servir un ruleset (gratuït en privats) o posar el repo públic. L'agent pot crear el ruleset amb gh; si no té permisos, fer-ho a Settings → Rules.
Action VERDA però el /exec NO canvia Falta clasp deploy, o apunta a un deployment diferent del que miren Comprovar que el workflow fa clasp deploy (no només push) i que actualitza el mateix deployment del /exec que tenen obert. L'agent ho ajusta amb el log.
Versió de l'acció/clasp desfasada Una versió antiga ja no funciona igual Demanar a l'agent que actualitzi la versió de l'acció/clasp del workflow. (No memoritzis versions: canvien; deixa que l'agent porti l'actual.)
El log els espanta (molt text vermell) No saben on mirar El que importa és el pas vermell i les últimes línies de l'error. «No cal entendre-ho tot: enganxa-ho a l'agent amb el workflow.»

Truc de prevenció: abans del Bloc D, fes que cadascú confirmi en veu alta els 3 clics: «He fet login? L'API està ON? El secret es diu igual que al workflow?» Aquests tres punts són la meitat dels errors del dia.


5. Pla B de contingències

Si a algú no li funciona la canonada avui

Si un agent no té mode agent (només xat)

Si cap agent funciona

Si la connexió de l'aula va justa

Objectiu mínim del dia: que tothom surti entenent que desplegar = fusionar i amb els fitxers + els 3 clics fets. Provar i depurar fins al verd, si avui no hi arriben, a casa amb l'agent.


6. Errors pedagògics a evitar (tu, professor)


7. Ponts amb la resta del curs

D'on venen — Sessió 4 (branques, PRs i revisió amb IA)

Cap a on van — Fase 6 (online i INFINITA)


Annex A — Frases per a la pissarra


Annex B — Prompts per copiar-enganxar

Recordatori: no t'inventis versions ni rutes exactes (clasp, accions de GitHub i pantalles de Google canvien sovint). El prompt demana a l'agent que porti l'última versió i que expliqui cada pas. Si l'agent té mode agent, que faci la feina; si no, que doni els fitxers i comandes per enganxar.

Prompt MESTRE (per muntar la canonada):

Ets el meu agent i m'ajudes a muntar un desplegament automàtic per a la meva app
d'Apps Script. Explica-m'ho EN CATALÀ i senzill, pas a pas, com a principiant.

CONTEXT:
- La meva app és d'Apps Script: Codi.gs (motor) + Index.html (cara) + un full de Google.
- El meu Script ID és: <ENGANXO AQUÍ EL MEU SCRIPT ID>
- Treballo en un repositori de GitHub, dins d'un Codespace, i ja sé fer
  branques → PR → merge.

VULL: que CADA COP QUE ES FUSIONI un canvi a `main`, l'app es publiqui SOLA al /exec,
SENSE que jo toqui mai Apps Script ni executi clasp a mà a la terminal.

FES (o dona'm els fitxers i comandes per enganxar, si no pots executar):
1. Un fitxer `.clasp.json` que apunti al MEU Script ID i als meus fitxers.
2. Un workflow `.github/workflows/deploy.yml` que, EN FER PUSH A `main`,
   instal·li clasp, llegeixi la credencial des d'un SECRET del repo,
   faci `clasp push` (puja el codi) i `clasp deploy` (publica una versió nova).
   Fes servir l'ÚLTIMA versió de l'acció/clasp i digues-me quina és.
3. Digue'm CLARAMENT:
   - Quina comanda he d'executar JO per al `clasp login` (l'he d'autoritzar amb
     el meu Google i enganxar el codi).
   - Que he d'activar l'API d'Apps Script al meu compte i ON es fa.
   - Quin SECRET he d'afegir a GitHub (NOM exacte i d'on surt el VALOR), i la
     comanda `gh secret set ...` si la puc fer servir.
4. PROTEGEIX la branca `main`: una regla (un `ruleset`) perquè NO es pugui fer
   `push` directe a `main`, només via pull request. Si el repo és privat i la
   protecció clàssica demana pagament, fes servir un `ruleset` (gratuït en privats).
   Fes-ho amb el `gh` si pots; si no, digue'm on clicar.

Recorda'm que hi ha 3 coses que NOMÉS puc fer JO perquè són del meu compte:
el login, activar l'API i posar el secret. Tu em dius on clicar; jo autoritzo.

Prompt de DEPURACIÓ (quan l'Action falla):

La meva GitHub Action de desplegament ha FALLAT (s'ha posat vermella). Ajuda'm a
arreglar-la com un bucle de depuració. Explica-m'ho EN CATALÀ i senzill.

T'enganxo:
1. El LOG vermell de l'Action (el pas que ha fallat i les últimes línies de l'error).
2. El meu workflow `.github/workflows/deploy.yml`.
3. El meu `.clasp.json` (si cal).

Digue'm:
- QUÈ falla exactament i PER QUÈ (en una frase).
- Si és el NOM del secret, l'API d'Apps Script no activada, el Script ID,
  la VERSIÓ de l'acció/clasp, els PERMISOS, o que falta `clasp deploy`.
- COM ho arreglo, pas a pas. Si has de canviar un fitxer, torna-me'l SENCER.

Acaba dient-me què he de fer per TORNAR A EXECUTAR l'Action i comprovar si ja va bé.

--- AQUÍ ENGANXO EL LOG, EL WORKFLOW I EL .clasp.json ---

Com fer servir aquests prompts a classe: el mestre és del Bloc B (muntar). El de depuració és del Bloc E (i del Pla B a casa). Tots dos són agnòstics d'eina: si l'agent no té mode agent, demana-li que torni els fitxers i les comandes i l'alumne els enganxa. Recorda sempre: demana-ho i entén-ho, no ho facis a mà.

Font editable: sessio_5/guia_professor_sessio5.md · aquesta pàgina web es genera automàticament des del Markdown.