Echipele care lucrează la GitHub se bazează pe datele evenimentului pentru a colabora. Datele înregistrate ca probleme, cereri de extragere și comentarii devin vitale pentru înțelegerea proiectului.

Cu disponibilitatea generală a Acțiunilor GitHub, avem șansa de a accesa și păstra programat datele evenimentelor GitHub în depozitul nostru. A face ca datele să fie parte din depozit în sine este o modalitate de a le păstra în afara GitHub. De asemenea, ne oferă posibilitatea de a prezenta datele pe un site web orientat spre față, cum ar fi cu paginile GitHub.

Și, dacă ești ca mine, te poți întoarce Comentarii despre problema GitHub într-un minunată pagină a cărții de oaspeți din anii 90.

Indiferent de utilizare, conceptele principale sunt aceleași. Putem folosi Acțiuni pentru a accesa, păstra și afișa datele evenimentelor GitHub – cu un singur fișier de flux de lucru. Pentru a ilustra procesul, vă voi duce prin codul fluxului de lucru asta face ca cartea mea de oaspeți să strălucească.

Pentru o privire introductivă asupra Acțiunilor GitHub, inclusiv modul în care sunt declanșate fluxurile de lucru, consultați Un flux CI / CD ușor, cu instrumente agnostice, cu GitHub Actions.

Accesarea datelor evenimentului GitHub

Un flux de lucru Action rulează într-un mediu cu unele variabile de mediu implicite. O mulțime de informații convenabile sunt disponibile aici, inclusiv date despre evenimente. Cea mai completă modalitate de a accesa datele evenimentului este utilizarea $GITHUB_EVENT_PATH variabilă, calea fișierului cu sarcina utilă completă a evenimentului JSON.

Calea extinsă arată /home/runner/work/_temp/_github_workflow/event.json iar datele sale corespund evenimentului său webhook. Puteți găsi documentația pentru datele evenimentelor webhook în GitHub REST API Tipuri de evenimente și încărcături utile. Pentru a face datele JSON disponibile în mediul fluxului de lucru, puteți utiliza un instrument de genul jq pentru a analiza datele evenimentului și a le pune într-o variabilă de mediu.

Mai jos, iau ID-ul comentariului de pe un emite eveniment comentariu:

ID="$(jq '.comment.id' $GITHUB_EVENT_PATH)"

Majoritatea datelor despre evenimente sunt disponibile și prin intermediul github.event variabilă de context fără a fi nevoie să analizăm JSON. Câmpurile sunt accesate folosind notația punctelor, ca în exemplul de mai jos, unde iau același ID de comentariu:

ID=${{ github.event.comment.id }}

Pentru cartea mea de oaspeți, doresc să afișez intrări cu mânerul utilizatorului, precum și data și ora. Pot captura datele despre acest eveniment așa:

AUTHOR=${{ github.event.comment.user.login }}
DATE=${{ github.event.comment.created_at }}

Variabilele Shell sunt la îndemână pentru accesarea datelor, totuși sunt efemere. Mediul fluxului de lucru este creat din nou la fiecare rulare și chiar și variabilele shell stabilite într-un singur pas nu persistă în alte etape. Pentru a păstra datele capturate, aveți două opțiuni: utilizați artefacte sau trimiteți-le în depozit.

Conservarea datelor despre evenimente: folosirea artefactelor

Folosind artefacte, puteți persista date între lucrările fluxului de lucru fără a le trimite în depozitul dvs. Acest lucru este la îndemână atunci când, de exemplu, doriți să transformați sau să încorporați datele înainte de a le pune undeva mai permanent. Este necesar să persistați datele între lucrările fluxului de lucru deoarece:

Fiecare lucrare dintr-un flux de lucru rulează într-o nouă instanță a mediului virtual. La finalizarea lucrării, alergătorul încetează și șterge instanța mediului virtual. (Persistarea datelor fluxului de lucru folosind artefacte)

Două acțiuni ajută la utilizarea artefactelor: upload-artifact și download-artifact. Puteți utiliza aceste acțiuni pentru a face fișiere disponibile pentru alte lucrări din același flux de lucru. Pentru un exemplu complet, a se vedea transmiterea datelor între joburile dintr-un flux de lucru.

upload-artifact acțiune action.yml conține un explicaţie dintre cuvintele cheie. Fișierele încărcate sunt salvate în .zip format. Un alt job din același flux de lucru poate folosi download-artifact acțiune pentru a utiliza datele într-un alt pas.

De asemenea, puteți descărca manual arhiva pe pagina de rulare a fluxului de lucru, sub fila Acțiuni din depozit.

Persistența datelor fluxului de lucru între lucrări nu aduce modificări fișierelor din depozit, deoarece artefactele generate sunt live doar în mediul fluxului de lucru.

Personal, fiind confortabil să lucrez într-un mediu shell, văd un caz de utilizare restrâns pentru artefacte, deși mi-ar fi părut să nu le menționez. Pe lângă transmiterea datelor între locuri de muncă, acestea ar putea fi utile pentru a crea .zip formatează arhive, să zicem, date de ieșire de testare. În cazul exemplului meu de carte de oaspeți, pur și simplu am parcurs toți pașii necesari într-un singur job, negând orice nevoie de trecere a datelor între joburi.

Păstrarea datelor despre evenimente: împingerea fișierelor de flux de lucru în depozit

Pentru a păstra datele captate în fluxul de lucru din depozitul în sine, este necesar să adăugați și să împingeți aceste date în depozitul Git. Puteți face acest lucru în fluxul de lucru creând fișiere noi cu datele sau adăugând date la fișierele existente, utilizând comenzi shell.

Crearea fișierelor în fluxul de lucru

Pentru a lucra cu fișierele din depozit în fluxul de lucru, utilizați checkout acțiune pentru a obține mai întâi o copie pentru a lucra cu:

- uses: actions/checkout@master
  with:
    fetch-depth: 1

Pentru a adăuga comentarii în cartea mea de oaspeți, transform datele despre eveniment capturate în variabilele shell în fișiere adecvate, folosind înlocuiri în extinderea parametrilor shell pentru a igiena informațiile utilizatorilor și a traduce linii noi în paragrafe. Am scris anterior despre de ce inputurile utilizatorilor ar trebui tratate cu atenție.

- name: Turn comment into file
  run: |
    ID=${{ github.event.comment.id }}
    AUTHOR=${{ github.event.comment.user.login }}
    DATE=${{ github.event.comment.created_at }}
    COMMENT=$(echo "${{ github.event.comment.body }}")
    NO_TAGS=${COMMENT//[<>]/`}
    FOLDER=comments

    printf '%bn' "<div class="comment"><p>${AUTHOR} says:</p><p>${NO_TAGS//$'n'/</p><p>}</p><p>${DATE}</p></div>rn" > ${FOLDER}/${ID}.html

Prin utilizarea printf și direcționarea ieșirii sale cu > într-un fișier nou, datele evenimentului sunt transformate într-un fișier HTML, denumit cu numărul ID-ului comentariului, care conține datele evenimentului capturate. Formatat, arată ca:

<div class="comment">
  <p>victoriadrake says:</p>
  <p>This is a comment!</p>
  <p>2019-11-04T00:28:36Z</p>
</div>

Când lucrați cu comentarii, un efect al denumirii fișierelor folosind ID-ul de comentariu este acela că un fișier nou cu același ID îl va suprascrie pe cel anterior. Acest lucru este la îndemână pentru o carte de oaspeți, deoarece permite modificările unui comentariu pentru a înlocui fișierul de comentarii original.

Dacă utilizați un generator de site static precum Hugo, puteți crea un fișier format Markdown, îl puteți lipi în content/ folder, iar construirea obișnuită a site-ului se va ocupa de restul.

În cazul cărții mele de oaspeți simpliste, am un pas suplimentar pentru consolidarea fișierelor de comentarii individuale într-o pagină. De fiecare dată când rulează, acesta suprascrie existentul index.html cu header.html porție (>), apoi găsește și adaugă (>>) toate conținutul fișierelor de comentarii în ordine descrescătoare și, în cele din urmă, adaugă fișierul footer.html porțiune pentru a termina pagina.

- name: Assemble page
  run: |
    cat header.html > index.html
    find comments/ -name "*.html" | sort -r | xargs -I % cat % >> index.html
    cat footer.html >> index.html

Realizarea modificărilor depozitului

Din moment ce checkout acțiunea nu este chiar aceeași cu clonarea depozitului, la momentul scrierii, există unele probleme încă de lucrat. Sunt necesari câțiva pași suplimentari pull, checkout, și cu succes push revine la master ramură, dar acest lucru este destul de banal făcut în shell.

Mai jos este pasul care adaugă, comite și împinge modificările făcute de fluxul de lucru înapoi la depozit master ramură.

- name: Push changes to repo
  run: |
    REMOTE=https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
    git config user.email "${{ github.actor }}@users.noreply.github.com"
    git config user.name "${{ github.actor }}"

    git pull ${REMOTE}
    git checkout master
    git add .
    git status
    git commit -am "Add new comment"
    git push ${REMOTE} master

Telecomanda, de fapt, depozitul nostru, este specificată folosind github.repository variabilă de context. Pentru ca fluxul nostru de lucru să poată fi împins la master, folosim secrets.GITHUB_TOKEN variabil.

Deoarece mediul fluxului de lucru este strălucitor și nou-născut, trebuie să configurăm Git. În exemplul de mai sus, am folosit github.actor variabilă de context pentru a introduce numele de utilizator al contului care inițiază fluxul de lucru. E-mailul este configurat în mod similar folosind Mod implicit noreply Adresa de e-mail GitHub.

Afișarea datelor despre evenimente

Corecția din 6 noiembrie 2019: GitHub Actions necesită un jeton de acces personal pentru a declanșa crearea unui site Pages.

Dacă utilizați paginile GitHub cu valoarea implicită secrets.GITHUB_TOKEN variabilă și fără un generator de site-uri, apăsarea modificărilor la depozitul din fluxul de lucru va actualiza doar fișierele depozitului. Construirea paginilor GitHub va eșua cu o eroare, „Site-ul dvs. are probleme la crearea: construirea paginii a eșuat”.

Pentru a activa acțiunile pentru a declanșa crearea unui site de pagini, va trebui să creați un jeton de acces personal. Acest simbol poate fi stocat ca secret în depozit setări și trecute în fluxul de lucru în locul valorii implicite secrets.GITHUB_TOKEN variabil. Am scris mai multe despre Mediul de acțiuni și variabilele din acest post.

Cu utilizarea unui jeton de acces personal, o apăsare inițiată de fluxul de lucru Acțiuni va actualiza și site-ul Pages. Îl poți vedea singur lăsând un comentariu in al meu cartea de oaspeti! Evenimentul de creare a comentariilor declanșează fluxul de lucru, care durează aproximativ 30 de secunde până la un minut pentru a rula și actualiza pagina cărții de oaspeți.

În cazul în care este necesară crearea unui site pentru ca modificările să fie publicate, cum ar fi atunci când se utilizează Hugo, o acțiune poate face acest lucru și. Cu toate acestea, pentru a evita crearea de bucle neintenționate, un flux de lucru Acțiune nu va declanșa altul. În schimb, este extrem de convenabil să gestionați procesul de construirea site-ului cu un Makefile, pe care orice flux de lucru îl poate rula apoi. Pur și simplu adăugați rularea Makefile ca ultim pas în lucrarea de flux de lucru, cu simbolul depozitului acolo unde este necesar:

- name: Run Makefile
  env:
    TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: make all

Acest lucru asigură că ultimul pas al fluxului de lucru construiește și implementează site-ul actualizat.

Gata cu orizontul de date despre evenimente

GitHub Actions oferă o modalitate îngrijită de a captura și utiliza datele despre evenimente, astfel încât să nu fie disponibile numai în GitHub. Posibilitățile sunt la fel de limitate ca imaginația ta! Iată câteva idei de lucruri care ne permit să creăm:

  1. Un forum public cu probleme, în care clienții fără conturi GitHub pot vizualiza și da feedback despre problemele legate de proiect.
  2. Un flux RSS care se actualizează automat cu noi probleme, comentarii sau PR-uri pentru orice depozit.
  3. Un sistem de comentarii pentru site-urile statice, care utilizează comentariile pentru problemele GitHub ca metodă de introducere.
  4. O minunată pagină a cărții de oaspeți din anii ’90.

Am menționat că am făcut un Pagina cărții de oaspeți din anii 90? Tărâțul meu interior-Geocities este puțin entuziasmat.