Salta el contingut
 

Automatització

Joan Puigcerver Ibáñez

j.puigcerveribanez@edu.gva.es

Llicència: CC BY-NC-SA 4.0

(Reconeixement - NoComercial - CompartirIgual) 🅭

License
transform="translate(-1102.015 -54.976)"/>

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 distribuir-los 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 la qualitat del 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, caldrà adaptar els processos de la naturalesa del projecte.

Configuració d'una automatització

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

Documentació

Quickstart for GitHub Actions – GitHub Docs

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.
  • if: Condició que ha de complir-se per a executar la tasca.

  • steps: Llista de passos a executar.

    Cada pas ha de ser una comanda de shell (run) o una acció de GitHub predefinida (uses).

    • name: Nom del pas
    • run: Comanda de shell que s'executarà.

    • uses: Acció de GitHub predefinida que s'executarà.

      Cada acció pot tenir els seus propis paràmetres de configuració.

Exemples d'automatitzacions a aquest repositori

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

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

.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/spellcheck.yml
name: spellcheck # Nom de l'automatització
on: # Events que disparen l'automatització
  pull_request:
    # Tipus d'events sobre la pull request
    types: ['opened', 'edited', 'reopened', 'synchronize', 'ready_for_review']
    branches:
      - '**' # Quan s'obri un pull request a qualsevol branca

jobs: # Llista de tasques a executar
  changed-files: # Nom de la tasca
    if: github.event.pull_request.draft == false # Condició per executar la tasca

    runs-on: ubuntu-latest # Sistema operatiu on s'executarà la tasca

    outputs:
      EXIST_CHANGED_FILES: ${{ steps.get-changed-files.outputs.EXIST_CHANGED_FILES }}

    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: Get changed files
        id: get-changed-files
        run: |
          CHANGED_FILES=$(git diff --name-only origin/main HEAD | grep 'docs/.*\.md$' || true)
          EXIST_CHANGED_FILES=0
          if [ -n "$CHANGED_FILES" ]; then
              EXIST_CHANGED_FILES=1
          fi
          echo "EXIST_CHANGED_FILES=$EXIST_CHANGED_FILES" >> $GITHUB_OUTPUT


  spellcheck: # Nom de la tasca
    needs: changed-files # Tasca que s'executarà abans
    if: github.event.pull_request.draft == false && needs.changed-files.outputs.EXIST_CHANGED_FILES == '1' # Condició per executar la tasca

    runs-on: ubuntu-latest # Sistema operatiu on s'executarà la tasca

    env: # Variables d'entorn
      DICPATH: .hunspell/
      CHANGED_FILES: ${{ needs.changed-files.outputs.CHANGED_FILES }}

    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
      - 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: CI=false 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: |
          CHANGED_FILES=$(git diff --name-only origin/main HEAD | grep 'docs/.*\.md$' | sed 's/\/index//' | sed 's/docs/site/' | sed 's/.md$/\/index.html/')
          echo "CHANGED_FILES=$CHANGED_FILES"
          for FILE in $(echo "$CHANGED_FILES"); do
              if [ -f $FILE ]; then
                  SOURCES="$SOURCES -S $FILE"
              fi
          done
          echo "SOURCES=$SOURCES"
          if [ -z "$SOURCES" ]; then
              echo "No files to check"
              exit 0
          fi
          SPELL_ARGS="$SPELL_ARGS --name mkdocs $SOURCES"
          pyspelling $SPELL_ARGS
Altres exemples

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ó localment sense haver de publicar canvis en el codi, podem executar-la 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 publicar els canvis al repositori remot.

GitHub Pages

GitHub Pages és un servei de GitHub que permet publicar llocs web estàtics1 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.

Exemple

Aquest lloc web està publicat amb GitHub Pages.

Configuració de GitHub Pages

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

Configuració de GitHub Pages

Figura 1. Configuració de GitHub Pages en aquest repositori

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

  • Mitjançant una automatització: Amb una procés 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.

  1. 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. ↩

📌 Aquest document pot quedar desactualitzat després d’imprimir-lo. Pots consultar la versió més recent a la pàgina web.
🌿 Abans d’imprimir aquest document, considera si és realment necessari. Redueix el consum de paper i ajuda a protegir el nostre entorn.
 
CC BY-NC-SA 4.0 (Reconeixement - NoComercial - CompartirIgual) 🅭 Joan Puigcerver Ibáñez