Automatització

Autor: Joan Puigcerver Ibáñez

Correu electrònic: j.puigcerveribanez@edu.gva.es

Llicència: CC BY-NC-SA 4.0

(Reconeixement - NoComercial - CompartirIgual) 🅭

Automatització en CI/CD¶

El concepte d'Integració Contínua (Continuous Integration o CI) i Desplegament Continu (Continuous Deployment o CD) és una pràctica que permet als equips de desenvolupament integrar els canvis en el codi de manera regular i posar-los en producció de manera automàtica.

Les tasques més comunes que es poden automatitzar són:

Compilació i empaquetatge de l'aplicació
Proves i validacions
Anàlisi de codi: linters, anàlisi estàtica, etc.
Desplegament de l'aplicació i gestió de llançaments
Generació i publicació de documentació

GitHub Actions¶

GitHub Actions és una funcionalitat de GitHub que permet automatitzar aquestes tasques dins del flux de treball de desenvolupament de software.

Aquestes tasques poden ser automatitzades a l'apartat Actions en un repositori de GitHub

Important

Cada projecte té unes necessitats pròpies i, per tant, necessitarà d'una adaptació de les tasques d'automatització a aquestes necessitats.

Configuració d'una automatització¶

Les tasques d'automatització es defineixen en un fitxer de configuració YAML, que s'ha de situar dins del directori .github/workflows/.

Documentació

Documentació de GitHub Actions

La configuració bàsica d'una tasca d'automatització es fa amb els següents camps:

name: Nom de la tasca
on: Esdeveniments que faran que s'execute la tasca.
jobs: Llista de tasques a executar.

Cada tasca té les següents seccions:

runs-on: Tipus de màquina on s'executarà la tasca.
steps: Llista de passos a executar.

Cada pas ha de ser una comanda de shell (run) o una acció de GitHub (uses).
- name: Nom del pas
- run: Comanda de shell que s'executarà.
- uses: Acció de GitHub que s'executarà.
  
  Cada acció pot tenir els seus propis paràmetres de configuració.

Exemple de workflow

Aquest lloc web està configurat amb dues tasques d'automatització.

Podeu consultar les execucions d'aquestes tasques en l'apartat Actions del repositori.

Publicació del lloc webCorrecció ortogràfica

.github/workflows/deploy.yml

name: deploy # Nom de l'automatització
on: # Events que disparen l'automatització
  push:
    branches:
      - main # Quan es fa un push a la branca main
  workflow_dispatch:

permissions: # Permisos que es concedeixen a l'automatització
  contents: write # Permet escriure al repositori

jobs: # Llista de tasques a executar
  deploy: # Nom de la tasca
    runs-on: ubuntu-latest # Sistema operatiu on s'executarà la tasca

    steps: # Passos a executar
      - uses: actions/checkout@v4 # Acció per clonar i còpiar el repositori a l'entorn d'execució
        with:
          fetch-depth: 0
      - name: Configure Git Credentials # Acció per configurar les credencials de Git
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5 # Acció per configurar Python
        with:
          python-version: 3.x
          cache: 'pip'
      - name: Install dependencies # Acció per instal·lar les dependències
        run: pip install -r requirements.txt
      - name: Build and deploy # Acció per compilar i desplegar la documentació
        run: mkdocs gh-deploy --force

.github/workflows/build.yml

name: build # Nom de l'automatització
on: # Events que disparen l'automatització
  push:
    branches:
      - 'main' # Quan es fa un push a la branca main
    tags:
      - '**' # Quan es crea qualsevol etiqueta
  pull_request:
    branches:
      - '**' # Quan s'obri un pull request a qualsevol branca

jobs: # Llista de tasques a executar
  documents: # Nom de la tasca
    runs-on: ubuntu-latest # Sistema operatiu on s'executarà la tasca
    env: # Variables d'entorn
      DICPATH: .hunspell/

    steps: # Passos a executar
      - uses: actions/checkout@v4 # Acció per clonar i còpiar el repositori a l'entorn d'execució
      - uses: actions/setup-python@v5 # Acció per configurar Python
        with:
          python-version: 3.x
          cache: 'pip'
      - name: Install dependencies # Acció per instal·lar les dependències
        run: pip install -U -r requirements.txt
      - name: Install pyspelling # Acció per instal·lar el paquet pyspelling
        run: pip install pyspelling
      - name: Install hunspell # Acció per instal·lar el corrector ortogràfic hunspell
        run: |
          sudo apt update
          sudo apt install hunspell -y
      - name: Build documents # Acció per compilar la documentació
        run: mkdocs build --clean

      - name: Download dictionary # Acció per descarregar el diccionari que s'utilitzarà en el corrector ortogràfic
        run: |
          mkdir -p .hunspell
          curl -L https://raw.githubusercontent.com/Softcatala/catalan-dict-tools/refs/heads/master/resultats/hunspell/catalan-valencia.dic -o .hunspell/ca_ES_valencia.dic
          curl -L https://raw.githubusercontent.com/Softcatala/catalan-dict-tools/refs/heads/master/resultats/hunspell/catalan-valencia.aff -o .hunspell/ca_ES_valencia.aff
          hunspell -D
      - name: Spell check # Acció per comprovar l'ortografia dels documents
        run: pyspelling

Execució d'una automatització¶

Les tasques d'automatització s'executen automàticament quan es compleixen les condicions definides en la secció on de la configuració.

No obstant, podem configurar una tasca perquè es puga executar manualment. Hem de definir un esdeveniment workflow_dispatch en la secció on de la configuració. que permet llançar la tasca des de l'apartat Actions del repositori.

on:
  workflow_dispatch:

A més, si necessitem provar una tasca d'automatització sense haver de publicar canvis en el codi, podem executar-la de manera local en el nostre entorn de desenvolupament amb l'eina act.

act -W '.github/workflows/checks.yml'

Aquesta eina utilitza Docker per simular l'entorn d'execució semblant a l'entorn de GitHub Actions, que permet provar les tasques sense haver de fer commits en el codi.

GitHub Pages¶

GitHub Pages és un servei de GitHub que permet publicar llocs web estàtics¹ directament des d'un repositori de GitHub.

Nota

En comptes de GitHub gratuïts, es permet configurar GitHub Pages en repositoris públics. En canvi, en els repositoris privats, es requereix d'un compte de pagament.

No obstant això, GitHub proporciona llicències gratuïtes per a estudiants i professors des de GitHub Education.

Aquest servei és útil per a publicar:

La documentació d'un projecte.
Portafolis personals o de projectes.
Llocs web estàtics generats per eines com Jekyll o MkDocs.

Configuració de GitHub Pages¶

GitHub Pages pot ser habilitat i configurat en la secció Settings del repositori, dins de l'apartat Pages.

GitHub Pages pot ser configurat per publicar-se de dues maneres diferents:

Mitjançant GitHub Actions: Amb una tasca d'automatització que genera i publica el lloc web estàtic.
A partir del contingut d'una branca i directori concrets del repositori.

Es pot triar qualsevol branca, però sols els directoris / (arrel del repositori) o /docs.

Un lloc web estàtic és un lloc web que no requereix d'un servidor web per generar les pàgines HTML, sinó que les pàgines ja estan generades i són servides directament. ↩