Materi ini akan berguna bagi pemula dan mereka yang ingin meningkatkan CI / CD dengan cepat untuk lateks dengan alat GitHub bawaan.
pengantar
Saat menjelajahi repositori dengan CV saya beberapa hari yang lalu (saya membuatnya dalam lateks, untungnya, ada banyak templat ), saya pikir akan menyenangkan untuk mengatur beberapa jenis tempat di mana versi dokumen saat ini selalu berada.
Persyaratan dasarnya sederhana:
- Dengan sedikit usaha untuk meningkatkan situs dengan rilis;
- Lakukan pembaruan konten di situs secara otomatis.
Solusi dalam bentuk pipa ditarik di kepala saya:
- Dorong komit ke GitHub;
- Membangun file .tex di CI / CD;
- Mengirimkan pdf yang dikumpulkan ke rilis GitHub;
- Memperbarui file pdf di situs kartu nama.
Dalam artikel ini, kita akan melihat lebih dekat setiap langkahnya. Situsnya adalah Halaman GitHub. Untuk CI / CD kami akan menggunakan GitHub Actions.
Kita butuh:
- Akun GitHub;
- Alat kompilasi LaTeX;
- Semua editor teks (Saya menggunakan VIM yang dikonfigurasi untuk lateks );
Pergilah!
Menghubungkan Tindakan GitHub
Di sini, semua tindakan dapat dilakukan dari situs tanpa menggunakan konsol.
Buka "Tindakan" (digarisbawahi dengan warna merah).
dan temukan kartu "Alur kerja sederhana" di sana, tempat kami menekan tombol "Siapkan alur kerja ini"
Editor dengan template alur kerja akan terbuka di depan kita. Penting untuk membahas poin ini secara lebih rinci.
Tindakan GitHub berfungsi dengan Alur Kerja , yang dijelaskan dalam file terpisah. Setiap alur kerja terdiri dari:
- Nama (bagian
name: …); - Kondisi awal (bagian
on: …); - Daftar tugas yang harus dilakukan (bagian
jobs: …)
Setiap pekerjaan juga terdiri dari potongan-potongan kecil yang disebut langkah . Setiap langkah adalah tindakan atom (dilakukan sekaligus). Dalam hal ini, langkah memiliki nama sendiri (
name: …) dan daftar perintah ( run: …), dan juga dapat menggunakan siap pakai tindakan ( uses: …) dari pengembang pihak ketiga. Tindakan
pihak ketiga adalah bagian paling kuat dari Tindakan GitHub. Mereka dapat melakukan banyak hal: menginstal JDK , menjalankan pengujian python di tox, dan banyak lagi. Dalam tutorial ini, kita akan menggunakan xu-cheng / latex-action @ v2 untuk mengkompilasi lateks (tidak ada masalah dengan Sirilik) danactions / upload-artifact @ v2 untuk mengupload artefak.
Mari kembali ke editor kita. Template yang diusulkan dapat diperbaiki, membawanya ke formulir:
name: Build and deploy latex sources to GitHub Pages
on: push
jobs:
build:
# , . ubuntu
runs-on: ubuntu-latest
steps:
# action,
- uses: actions/checkout@v2
#
- name: Build document
uses: xu-cheng/latex-action@v2
with:
# ,
root_file: main.tex
# .
working_directory: latex_sources/
# , (latexmk)
# -jobname=<name>
args: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmode
compiler: latexmk
# pdf-
- name: Upload pdf document
uses: actions/upload-artifact@v2
with:
#
name: my_doc
# pdf. «*», «**»
# <working_directory>/<jobname>.pdf
path: latex_sources/my_doc.pdf
Simpan ke file, pilih nama apa saja untuk file tersebut (Anda dapat menggunakan latex.yml). Setelah melakukan pembuatan file ke editor web, build pertama harus menuju ke GitHub Actions, sebagai akibatnya sebuah artefak akan muncul - pdf yang telah dikompilasi.
Hore! Sekarang Anda dapat mulai merilis.
Menyiapkan rilis otomatis
Sistem rilis di GitHub memiliki satu kekhasan: rilis selalu terikat dengan komit dengan tag. Oleh karena itu, kami memiliki dua opsi:
- Tambahkan tag secara manual ke komitmen yang ingin kami kumpulkan dan rilis file pdfnya;
- Otomatis beri tag semua komit dan lepaskan.
Bagi saya, opsi kedua sepertinya lebih nyaman. Saya biasanya berkomitmen dan mendorong saat pekerjaan selesai (baik secara logis atau untuk hari ini). Oleh karena itu, kedepannya saya akan membicarakannya.
Untuk membuat rilis, kami akan menggunakan tindakan tindakan / create-release @ v1 dan untuk mengupload file pdf ke rilis yang dibuat (ya, ini diunggah secara terpisah) kami akan menggunakan tindakan / upload-release-asset @ v1 .
Mari tambahkan pekerjaan baru :
deploy:
runs-on: ubuntu-latest
# master. ,
if: github.ref == 'refs/heads/master'
# job. .
needs: [build]
steps:
# , bash-
- name: Variables
# id : step
id: vars
# echo ${{ steps.<step_id>.outputs.<variable_name> }}
# | — yaml. ,
run: |
echo «::set-output name=date::$(date +'%Y-%m-%d')»
echo «::set-output name=sha8::$(echo ${GITHUB_SHA} | cut -c1-8)»
- name: Download artifacts
uses: actions/download-artifact@v2
with:
# , upload-artifact
name: my_doc
- name: Create Release
uses: actions/create-release@v1
id: create_release
env:
# ., GITHUB_TOKEN
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
with:
# step id=vars (. ).
# “my_doc-< >-< 8 sha >
tag_name: my_doc-${{ steps.vars.outputs.date }}-${{ steps.vars.outputs.sha8 }}
# ,
release_name: My Actions document (version ${{ steps.vars.outputs.date }})
# , false
draft: false
prerelease: false
# step
- name: Upload pdf asset
uses: actions/upload-release-asset@v1
env:
#
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# step id=create_release upload_url —
upload_url: ${{ steps.create_release.outputs.upload_url }}
# latex_sources, download-artifacts
asset_path: ./my_doc.pdf
# ,
asset_name: my_asset_name.pdf
asset_content_type: application/pdf
Tambahkan ke file alur kerja, lakukan perubahan. Buka Tindakan dan lihat bahwa satu langkah lagi telah ditambahkan:
Pada saat yang sama, pdf yang dikompilasi juga muncul dalam rilis.
Satu-satunya yang tersisa adalah mengunggahnya ke situs.
Menampilkan Halaman GitHub
GitHub menyediakan kemampuan untuk setiap proyek untuk membuat halaman web dan menyediakan hosting gratis untuk itu. Tetapi Anda tidak harus tahu JS / CSS / HTML untuk menulis sesuatu yang berharga! Di luar kotak, layanan ini menawarkan beberapa templat cantik yang benar-benar menyelesaikan masalah tata letak. Yang perlu Anda lakukan adalah mengisi dokumen Penurunan Harga, dan sistem akan melakukan sisanya.
Kami pergi ke bagian "Pengaturan" dari repositori dan di tab "Opsi" (dibuka pertama kali secara default) gulir ke bawah ke "Halaman GitHub".
Di sini kami memilih cabang master sebagai sumber, dan / docs sebagai folder (Anda juga dapat menggunakan / root, tetapi saya lebih suka menyimpan jumlah file minimum di root proyek). Klik "Simpan".
Tombol "Pemilih Tema" membuka galeri template, di mana masing-masing dapat disodok, dilihat dan dipilih dengan mengklik tombol hijau "Pilih tema".
Setelah memilih tema, kita akan dilempar ke web editor, di mana diusulkan untuk mengedit file Markdown, yang kemudian akan menjadi situs. Di sini Anda dapat mendeskripsikan semua yang diinginkan hati Anda: dari presentasi sederhana tentang diri Anda hingga tujuan dokumen dan fitur pekerjaan.
Setelah Anda puas dengan isinya, lakukan perubahan Anda.
Dimana halaman saya?
Tautan ke halaman yang dirakit selalu disimpan di Pengaturan -> Halaman GitHub. Lebih baik mendaftarkannya di Situs web repositori (roda gigi di sebelah bidang "Tentang" di halaman utama) agar tidak hilang.
Mendownload rilis terbaru
Ada sedikit trik: rilis terbaru dan semua file di dalamnya selalu dapat direferensikan dengan mengganti tag komit di URL dengan "terbaru". Dalam contoh kami, untuk mendapatkan file my_asset_name.pdf dari rilis terbaru, kami perlu memasukkan tautan
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
Dalam kasus saya, itu adalah: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
Setelah langkah-langkah ini, Halaman GitHub selalu ditautkan ke rilis terbaru.
Hasil
Kami menyiapkan Tindakan GitHub untuk secara otomatis membuat file pdf, melepaskannya, dan membuka situs di Halaman GitHub yang berisi versi terbaru. Versi terakhir proyek dapat ditemukan di sini .
Terima kasih atas perhatian Anda!