GitHub Akcije kao CI/CD za lokaciju na statičkom generatoru i GitHub stranicama

Nakon što sam malo pregledao Habr, iznenadio sam se da je vrlo malo članaka objavljeno na temu GitHubove (beta) funkcije - Akcije.

Čini se da se takvo potcjenjivanje može objasniti činjenicom da je funkcionalnost još uvijek u testiranju, iako „beta“. Ali to je korisna karakteristika beta verzije koja omogućava da se ovaj alat koristi u privatnim repozitorijumima. Radi se o radu s ovom tehnologijom o čemu ću govoriti u ovom članku.

Praistorija

Ako krenemo redom, onda je vjerojatno vrijedno spomenuti da sam u procesu traženja brze, pogodne, jednostavne i besplatne opcije za pohranjivanje lične web stranice „O meni“ morao provesti nekoliko noći i pročešljati mnoge članke.

Neki ljudi biraju hosting, drugi cloud server, a oni koji ne žele razumjeti rad, interakciju i plaćanje za sve ovo poput uploada statičnih stranica u spremište, jer sada to može da se radi i na GitHubu i GitLabu.

Naravno, ovo je svačiji lični izbor.

Moj konačni izbor su bile GitHub stranice.

About Pages

Ko ne zna gh-pages - ovo je opcija za pohranjivanje dokumentacije u obliku web stranice i obezbjeđuje se besplatno, a pored dokumentacije predlaže se i pohranjivanje ličnih web stranica. Ovu funkcionalnost GitHub pruža svim korisnicima i dostupna je u postavkama spremišta.

Repozitorijum projekta koristi granu gh-pages, za korisničku stranicu - zasebno spremište s imenom username.github.io sa izvorima sa sajta master grana.

Možete vidjeti više detalja u dokumentaciji, ali dozvolite mi samo da napomenem da je GitHub iznenađujuće velikodušan u dopuštanju bilo kome da poveže svoju domenu sa takvim sajtom jednostavnim dodavanjem fajla CNAME sa imenom domene i postavljanjem DNS-a vašeg provajdera domena na GitHub serverima.

Siguran sam da ovdje ima mnogo članaka o tome kako razviti takvu stranicu, tako da to nije ono o čemu ću dalje govoriti.

Kada dođe do problema

Problem je bio u tome što kada se koristi statički generator, postoji potreba za pisanjem dodatnih skripti i korištenjem biblioteka kako bi se pojednostavio proces generiranja stranica i njihovog učitavanja u spremište. Jednostavno, ako pohranjujete izvore u zasebno privatno spremište, onda je svaki put kada dođe do bilo kakve promjene na stranici, bilo potrebno implementirati lokalno okruženje za naknadno generiranje statičkih stranica i objavljivanje u glavnom spremištu stranice.

Postoji obilje statički generatori i svi imaju isti problem. Ove radnje oduzimaju previše vremena i truda i na kraju usporavaju rad na web stranici, posebno nakon nekoliko migracija s OS-a na OS ili incidenata s gubitkom podataka na tvrdim diskovima (to je bio slučaj u mom slučaju).

Nedavno je, bilo u pop-up notifikaciji na web stranici ili u biltenu sa GitHub-a, primjećen novoizgrađeni CI/CD, koji je omogućio da se ove radnje izvedu uz minimalan napor.

O generatorima statičkih stranica

Neću se posebno fokusirati na ovu podtačku, ali ću podijeliti par teza do kojih sam došao prilikom odabira i korištenja sljedećeg:

1) odaberite generator koji odgovara vašem programskom jeziku, ili onaj koji je što jasniji. Na ovu ideju sam došao u trenutku kada sam i sam morao da dodam neke funkcionalnosti da bi sajt radio, da dodam štake za njegovu veću stabilnost i automatizaciju. Osim toga, ovo je dobar razlog da sami napišete dodatnu funkcionalnost u obliku dodataka;

2) koji generator odabrati je lični izbor, ali vrijedi uzeti u obzir da za početno uranjanje u rad funkcionalnosti GitHub Pages prvo morate instalirati Jekyll. Na sreću, omogućava vam da generišete web stranicu iz izvora direktno u spremištu (Ponoviću ovo sa svojim izborom).

Moj izbor generatora je zasnovan na prvoj tački. Pelikan koji je napisan na Pythonu lako je zamijenio Jekyll-a, koji mi je stran (koristio skoro godinu dana). Kao rezultat toga, čak i kreiranje i uređivanje članaka i rad na web stranici daje dodatno iskustvo na jeziku koji mi je zanimljiv.

Izjava o problemu

Glavni zadatak će biti pisanje skripte (u stvari konfiguracionu datoteku) koja će automatski generisati statičke stranice iz privatnog spremišta. Rješenje će uključivati funkcionalnost virtuelnog okruženja. Sama skripta će dodati gotove stranice u javno spremište.

Alati za rješenje

Alati koje ćemo koristiti za rješavanje problema:

GitHub Actions;
Python3.7;
Pelikan;
Git;
GitHub stranice.

Rešavanje problema

Dakle, nakon što smo se malo upoznali sa dokumentacijom i shvatili kako se pišu skripte za Akcije, postalo je jasno da će ovaj mehanizam u potpunosti riješiti nastali problem. U vrijeme pisanja, morate se pretplatiti na korištenje ove funkcionalnosti. za beta testiranje!

GitHub Akcije kao CI/CD za lokaciju na statičkom generatoru i GitHub stranicama
Opis nove funkcionalnosti od samog Githuba

Pisanje Actions skripte počinje kreiranjem imenovane datoteke u fascikli .github i njegov podfolder workflows. Ovo se može uraditi bilo ručno ili iz uređivača na kartici Akcije na stranici spremišta.

GitHub Akcije kao CI/CD za lokaciju na statičkom generatoru i GitHub stranicama
Primjer praznog obrasca skripte

Ukratko ću komentirati obrazac

name: CI    # название скрипта: будет отображаться во вкладке Actions

on: [push]  # действие, по которому запускается данный скрипт

jobs:       # роботы, которые будут выполняться
  build:    # сборка, которая..

    runs-on: ubuntu-latest      # ..будет запущена на основе этого образа

    steps:              # шаги которые будут проделаны после запуска образа
    - uses: actions/checkout@v1     # переход в самую актуальную ветку
    - name: Run a one-line script   # имя работы номер 1
      run: echo Hello, world!       # суть работы номер 1 (bash-команда записана в одну строку)
    - name: Run a multi-line script   # имя работы номер 2
      run: |                    # суть работы номер 2 (многострочная)
        echo Add other actions to build,
        echo test, and deploy your project.

Hajde da napišemo svoje na osnovu šablona:

0) Također možete ostaviti naziv “CI”. To je stvar ukusa.

1) Zatim morate odabrati akciju/okidač koji će pokrenuti skriptu, u našem slučaju ovo je uobičajeno guranje novog urezivanja u spremište.

on:
  push

2) Slika na osnovu koje će se pokrenuti skripta također će biti ostavljena iz primjera, budući da Ubuntu Sasvim je zadovoljavajuće u smislu potrebne funkcionalnosti. Gledajući na dostupni alati postaje jasno da to može biti bilo koja potrebna ili jednostavno zgodna slika (ili Docker kontejner na osnovu nje).

  build:
    runs-on: ubuntu-latest

3) U koracima ćemo prvo postaviti okruženje za pripremu za glavni posao.

3.1) idite na granu koja nam je potrebna (standardni korak checkout):

- uses: actions/checkout@v1

3.2) instalirajte Python:

    - name: Set up Python
      uses: actions/setup-python@v1
      with:
        python-version: 3.7

3.3) instalirajte zavisnosti našeg generatora:

    - name: Install dependencies
      run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

3.4) kreirajte direktorij u kojem će se generirati stranice stranice:

   - name: Make output folder
      run: mkdir output

4) Da bi rad na sajtu bio dosledan, odnosno da se ne brišu prethodne promene i da bi se mogle bez sukoba dodavati izmene u repozitorijum sajta, sledeći korak će biti kloniranje repozitorija sajta svaki put:

   - name: Clone master branch
      run: git clone "https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git" --branch master --single-branch ./output

Ovaj korak poziva sistemske varijable:

varijabla GITHUB_ACTOR GitHub se sam instalira, a ovo je korisničko ime čijom je greškom ova skripta pokrenuta;
varijabla secrets.ACCESS_TOKEN ovo se generiše token za upravljanje Githubom, možemo je proslijediti kao varijablu okruženja tako što ćemo je postaviti na kartici Secrets postavke našeg spremišta. Imajte na umu da će nam tokom generiranja token biti dostavljen jednom, više mu neće biti pristupa. Kao i vrijednosti predmeta Secrets.

5) Pređimo na generiranje naših stranica:

   - name: Generate static pages
      run: pelican content -o output -s publishconf.py

Parametri koji se prosleđuju generatoru su odgovorni za direktorijum u koji će se poslati generisani fajlovi (-o output) i konfiguracijski fajl koji koristimo za generiranje (-s publishconf.py; O pristupu odvajanju lokalne konfiguracije i konfiguracije za objavljivanje možete pročitati u dokumentaciji Pelican).

Dozvolite mi da vas podsjetim šta se nalazi u našem folderu output Skladište stranice je već klonirano.

6) Postavimo git i indeksirajmo naše promijenjene datoteke:

    - name: Set git config and add changes
      run: |
          git config --global user.email "${GITHUB_ACTOR}@https://users.noreply.github.com/"
          git config --global user.name "${GITHUB_ACTOR}"
          git add --all
      working-directory: ./output

U ovom trenutku se koristi već poznata varijabla i naznačuje se radni direktorij u kojem će se pokrenuti naredbe iz ovog koraka. Komanda za odlazak u radni direktorij bi inače izgledala ovako - cd output.

7) Hajde da generišemo poruku urezivanja, urezujemo promene i gurnemo ih u spremište. Tako da urezivanje nije uzaludno i stoga ne proizvodi grešku u bash-u (izlazni rezultat nije 0) — prvo da provjerimo da li je uopće potrebno nešto ulagati i gurati. Za to koristimo naredbu git diff-index --quiet --cached HEAD -- koji će izlaziti na terminal 0 ako nema promjena u odnosu na prethodnu verziju stranice, i 1 postoje takve promjene. Zatim obrađujemo rezultat ove naredbe. Tako ćemo u informaciju o izvršavanju skripte bilježiti korisne informacije o stanju stranice u ovoj fazi, umjesto da se automatski ruši i šalje nam izvještaj o padu skripte.

Ove radnje također provodimo u našem imeniku sa gotovim stranicama.

   - name: Push and send notification
      run: |
          COMMIT_MESSAGE="Update pages on $(date +'%Y-%m-%d %H:%M:%S')"
          git diff-index --quiet --cached HEAD -- && echo "No changes!" && exit 0 || echo $COMMIT_MESSAGE
          # Only if repo have changes
          git commit -m "${COMMIT_MESSAGE}"
          git push https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git master
      working-directory: ./output

rezultat

Kao rezultat toga, takva skripta vam omogućava da ne razmišljate o stvaranju statičnih stranica. Dodavanjem promjena direktno u privatno spremište, bilo radom sa git-om iz bilo kojeg sistema ili kreiranjem datoteke preko GitHub web sučelja, Actions će sve učiniti same. Ako se skripta neočekivano sruši, obavijest će biti poslana na vašu e-poštu.

Pun kod

Ostaviću svoju radnu verziju, u kojoj zadnji korak dodaje slanje obavijesti da je urezivanje gurnuto u glavno spremište.

Koriste se gore opisane tajne, gdje se dodaje bot token i korisnički ID kome treba poslati poruku.

name: Push content to the user's GitHub pages repository

on:
  push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Set up Python
      uses: actions/setup-python@v1
      with:
        python-version: 3.7
    - name: Install dependencies
      run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
    - name: Make output folder
      run: mkdir output
    - name: Clone master branch
      run: git clone "https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git" --branch master --single-branch ./output
    - name: Generate static pages
      run: pelican content -o output -s publishconf.py
    - name: Set git config and add changes
      run: |
          git config --global user.email "${GITHUB_ACTOR}@https://users.noreply.github.com/"
          git config --global user.name "${GITHUB_ACTOR}"
          git add --all
      working-directory: ./output
    - name: Push and send notification
      run: |
          COMMIT_MESSAGE="Update pages on $(date +'%Y-%m-%d %H:%M:%S')"
          git diff-index --quiet --cached HEAD -- && echo "No changes!" && exit 0 || echo $COMMIT_MESSAGE
          git commit -m "${COMMIT_MESSAGE}"
          git push https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git master
          curl "https://api.telegram.org/bot${{ secrets.BOT_TOKEN }}/sendMessage?text=$COMMIT_MESSAGE %0ALook at ${GITHUB_ACTOR}.github.io %0ARepository%3A github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io&chat_id=${{ secrets.ADMIN_ID }}"
      working-directory: ./output

Snimke ekrana

GitHub Akcije kao CI/CD za lokaciju na statičkom generatoru i GitHub stranicama
Rezultat jednog od pokretanja prikazan je na kartici Akcije izvornog spremišta