Statik Jeneratör Sitesi ve GitHub Sayfaları için CI/CD Olarak GitHub Eylemleri

Habr'ı biraz araştırdıktan sonra GitHub'ın (beta) özelliği olan Eylemler hakkında çok az makalenin yayınlanmış olmasına şaşırdım.

Görünüşe göre bu kadar yetersiz ifade, işlevselliğin "beta" da olsa hala test aşamasında olmasıyla açıklanabilir. Ancak bu aracın özel depolarda kullanılmasına izin veren betanın kullanışlı bir özelliğidir. Bu yazıda bahsedeceğim konu bu teknolojiyle çalışmakla ilgili.

tarih öncesi

Sırayla başlarsak, kişisel bir "Hakkımda" web sitesini depolamak için hızlı, kullanışlı, kolay ve ücretsiz bir seçenek arama sürecinde, birkaç gece geçirmek ve birçok makaleyi taramak zorunda kaldığımı muhtemelen belirtmekte fayda var.

Bazı insanlar barındırmayı, diğerleri bir bulut sunucusunu seçiyor ve statik siteleri bir depoya yüklemek gibi tüm bunların işini, etkileşimini ve ödemesini anlamak istemeyenler, çünkü artık bu hem GitHub hem de GitLab'da yapılabiliyor.

Elbette bu herkesin kişisel tercihidir.

Son tercihim GitHub Pages'dı.

Sayfalar Hakkında

Kim bilmiyor gh-pages - bu, belgeleri bir web sitesi biçiminde saklamak için bir seçenektir ve ücretsiz olarak sağlanır ve belgelere ek olarak kişisel web sitelerinin de saklanması önerilmektedir. Bu işlevsellik GitHub tarafından tüm kullanıcılara sağlanır ve depo ayarlarında mevcuttur.

Proje deposu bir dal kullanıyor gh-pages, bir kullanıcı sitesi için - adında ayrı bir depo username.github.io site kaynaklarıyla birlikte master dal.

daha fazlasını görebilirsin belgelerde, ancak GitHub'ın herkesin kendi alan adını böyle bir siteye basit bir dosya ekleyerek bağlamasına izin verme konusunda şaşırtıcı derecede cömert olduğunu belirtmek isterim. CNAME alan adını kullanarak ve alan adı sağlayıcınızın DNS'sini GitHub sunucularında kurarak.

Burada böyle bir sitenin nasıl geliştirileceğine dair pek çok makale olduğundan eminim, bu yüzden bundan sonra bahsetmeyeceğim.

Ortaya çıkan sorun

Sorun, statik bir oluşturucu kullanırken, sayfa oluşturma ve bunları depoya yükleme sürecini basitleştirmek için ek komut dosyaları yazmaya ve kitaplıkları kullanmaya ihtiyaç duyulmasıydı. Basitçe, kaynakları ayrı bir özel depoda saklarsanız, sitede her değişiklik olduğunda, sonraki nesil statik sayfalar için yerel ortamın dağıtılması ve ana site deposunda yayınlanması gerekliydi.

Bolluk var statik jeneratörler ve hepsinde aynı sorun var. Bu eylemler çok fazla zaman ve çaba gerektirir ve özellikle işletim sisteminden işletim sistemine yapılan birkaç geçişten veya sabit disklerde veri kaybına neden olan olaylardan sonra sitedeki çalışmayı yavaşlatır. (benim durumumda böyleydi).

Kısa bir süre önce, web sitesindeki bir açılır bildirimde veya GitHub'dan gelen bir haber bülteninde, bu eylemlerin minimum çabayla gerçekleştirilmesine olanak tanıyan yeni oluşturulmuş bir CI/CD fark edildi.

Statik sayfa oluşturucular hakkında

Bu alt madde üzerinde çok fazla durmayacağım ancak aşağıdakilerin seçimi ve kullanımı sırasında aklıma gelen birkaç tezi paylaşacağım:

1) programlama dilinize uygun veya mümkün olduğunca anlaşılır bir oluşturucu seçin. Bu fikre, sitenin çalışması için bazı işlevler eklemem, daha fazla stabilite ve otomasyon için koltuk değneği eklemem gerektiği bir zamanda geldim. Ayrıca bu, eklentiler biçiminde ek işlevleri kendiniz yazmanız için iyi bir nedendir;

2) hangi oluşturucuyu seçeceğiniz kişisel bir seçimdir, ancak GitHub Sayfaları işlevselliğinin çalışmasına ilk daldırma için önce yüklemeniz gerektiğini düşünmeye değer. Jekyll. Neyse ki, doğrudan depodaki kaynaklardan bir web sitesi oluşturmanıza olanak tanır (Bunu kendi tercihimle tekrarlayacağım).

Jeneratör seçimim ilk noktaya dayanmaktadır. Pelikan Python'da yazılmış olan bana yabancı olan Jekyll'ın yerini kolayca aldı (neredeyse bir yıldır kullanıyorum). Sonuç olarak, makaleler oluşturup düzenlemek ve bir web sitesinde çalışmak bile ilgimi çeken bir dilde ek deneyim sağlıyor.

Sorunun formüle edilmesi

Ana görev, özel bir depodan otomatik olarak statik sayfalar oluşturacak bir komut dosyası (aslında bir yapılandırma dosyası) yazmak olacaktır. Çözüm, sanal bir ortamın işlevselliğini içerecektir. Komut dosyasının kendisi hazır sayfaları genel depoya ekleyecektir.

Çözüm için araçlar

Sorunu çözmek için kullanacağımız araçlar:

GitHub Eylemleri;
Python3.7;
Pelikan;
Git;
GitHub Sayfaları.

Çözelti

Böylece, belgelere biraz aşina olduktan ve Eylemler için komut dosyalarının nasıl yazıldığını anladıktan sonra, bu mekanizmanın ortaya çıkan sorunu tamamen çözeceği ortaya çıktı. Yazma sırasında bu işlevi kullanmak için abone olmanız gerekir. beta testi için!

Statik Jeneratör Sitesi ve GitHub Sayfaları için CI/CD Olarak GitHub Eylemleri
Yeni işlevselliğin Github'un kendisi tarafından açıklaması

Actions komut dosyasının yazılması, bir klasörde adlandırılmış bir dosya oluşturmakla başlar .github ve onun alt klasörü workflows. Bu, manuel olarak veya depo sayfasındaki Eylemler sekmesindeki düzenleyiciden yapılabilir.

Statik Jeneratör Sitesi ve GitHub Sayfaları için CI/CD Olarak GitHub Eylemleri
Boş komut dosyası formu örneği

Form hakkında kısaca yorum yapacağım

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.

Şablona göre kendi yazımızı yazalım:

0) Ayrıca “CI” adını da bırakabilirsiniz. Bu bir zevk meselesi.

1) Daha sonra, betiği başlatacak eylemi/tetikleyiciyi seçmeniz gerekir; bizim durumumuzda bu, depoya yeni bir işlemin olağan şekilde gönderilmesidir.

on:
  push

2) Komut dosyasının başlatılacağı görsel de örnekten çıkarılacaktır, çünkü Ubuntu Gerekli işlevsellik açısından oldukça tatmin edici. Şuraya bakıldığında: dağıtım bilgileri bunun herhangi bir gerekli veya basit bir görüntü (veya buna dayalı bir Docker kapsayıcısı) olabileceği açıkça ortaya çıkıyor.

  build:
    runs-on: ubuntu-latest

3) Adımlarda öncelikle asıl çalışmaya hazırlanmak için ortamı ayarlayacağız.

3.1) ihtiyacımız olan şubeye gidin (standart adım checkout):

- uses: actions/checkout@v1

3.2) Python'u yükleyin:

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

3.3) jeneratörümüzün bağımlılıklarını kurun:

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

3.4) site sayfalarının oluşturulacağı bir dizin oluşturun:

   - name: Make output folder
      run: mkdir output

4) Sitedeki çalışmanın tutarlı olması, yani önceki değişikliklerin silinmemesi ve site deposuna çakışmalar olmadan değişiklik ekleyebilmek için bir sonraki adım, site deposunu her seferinde klonlamak olacaktır:

   - 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

Bu adım sistem değişkenlerini çağırır:

değişken GITHUB_ACTOR GitHub kendi kendini kuruyor ve bu, bu betiğin başlatılmasına neden olan kullanıcı adıdır;
değişken secrets.ACCESS_TOKEN bu oluşturuldu Github'u yönetmek için belirteç, bunu sekmede ayarlayarak ortam değişkeni olarak aktarabiliriz Secrets depo ayarlarımız. Oluşturma sırasında belirtecin bize bir kez sağlanacağını ve ona daha fazla erişim sağlanamayacağını lütfen unutmayın. Sırlar öğelerinin değerlerinin yanı sıra.

5) Sayfalarımızı oluşturmaya geçelim:

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

Oluşturucuya iletilen parametreler, oluşturulan dosyaların gönderileceği dizinden sorumludur (-o output) ve oluşturmak için kullandığımız yapılandırma dosyası (-s publishconf.py; Pelican belgelerinde yerel yapılandırma ile yayınlanmak üzere yapılandırmayı ayırma yaklaşımını okuyabilirsiniz.).

Klasörümüzde ne olduğunu size hatırlatayım output Site deposu zaten klonlanmış.

6) Git'i ayarlayalım ve değiştirilen dosyalarımızı indeksleyelim:

    - 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

Bu noktada önceden bilinen bir değişken kullanılır ve bu adımdaki komutların başlatılacağı çalışma dizini belirtilir. Aksi halde çalışma dizinine gitme komutu şuna benzer: cd output.

7) Bir taahhüt mesajı oluşturalım, değişiklikleri taahhüt edelim ve bunları depoya itelim. Taahhütün boşuna olmaması ve dolayısıyla bash'ta hata üretmemesi için (çıkış sonucu 0) — önce, bir şeyi taahhüt etmenin ve itmenin gerekli olup olmadığını kontrol edelim. Bunu yapmak için şu komutu kullanıyoruz: git diff-index --quiet --cached HEAD -- terminale çıktı verecek 0 sitenin önceki sürümüne göre herhangi bir değişiklik yoksa ve 1 böyle değişiklikler var. Daha sonra bu komutun sonucunu işliyoruz. Böylece, betiğin çalıştırılmasıyla ilgili bilgilerde, otomatik olarak çökmek ve bize betiğin çökmesiyle ilgili bir rapor göndermek yerine, sitenin bu aşamada durumu hakkında faydalı bilgileri kaydedeceğiz.

Bu işlemleri de rehberimizde hazır sayfalarla gerçekleştiriyoruz.

   - 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

sonuç

Sonuç olarak böyle bir komut dosyası, statik sayfalar oluşturmayı düşünmemenizi sağlar. Değişiklikleri doğrudan özel bir depoya ekleyerek, ister herhangi bir sistem altından git ile çalışarak ister GitHub web arayüzü aracılığıyla bir dosya oluşturarak, Actions her şeyi kendisi yapacaktır. Komut dosyası beklenmedik bir şekilde çökerse e-postanıza bir bildirim gönderilecektir.

Tam kod

Son adımın, bir taahhüdün ana depoya aktarıldığına dair bir bildirim göndermeyi eklediği çalışma sürümümü bırakacağım.

Bot token ve mesajın gönderilmesi gereken kullanıcı ID'sinin eklendiği yukarıda açıklanan Sırlar kullanılır.

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

Ekran görüntüleri

Statik Jeneratör Sitesi ve GitHub Sayfaları için CI/CD Olarak GitHub Eylemleri
Kaynak havuzun Eylemler sekmesinde görüntülenen çalıştırmalardan birinin sonucu