Exemplo completo

En conxunto, todos os elementos presentados (workflow → jobs → steps → actions → runners) conforman unha estrutura moi flexible que permite automatizar todo o ciclo de vida dunha aplicación web. Neste apartado veremos como configurar un workflow dunha aplicación Node.js.

O obxectivo será construír un fluxo de traballo que:

1. Compile e probe automaticamente o proxecto cada vez que se suba código.
2. Se todo funciona correctamente, despregue automaticamente a aplicación nun servidor remoto.

Este fluxo compoñerase de dous jobs:

1. build: valida o código (instalando dependencias e executando tests).
2. deploy: desprega a aplicación nun servidor (só se o build tivo éxito).

Os dous traballos estarán definidos nun único ficheiro YAML dentro do repositorio: .github/workflows/ci-cd.yml.

---

Que se consegue con este workflow?

• Automatizar a verificación do código en cada subida.
• Garantir que só se despregan versións estables.
• Evitar erros humanos no proceso de despregamento.
• Manter a aplicación web sempre actualizada e operativa.

---

Código completo do workflow

.github/workflows/ci-cd.yml

name: CI/CD - App Node.js

# 1. Eventos que disparan o workflow
on:
  push:
    branches: [ "main" ]     # Execútase cada vez que se fai push a main
  pull_request:
    branches: [ "main" ]     # Tamén en cada pull request cara a main

# 2. Definición dos jobs
jobs:
  # ---------- JOB 1: BUILD ----------
  build:
    name: Build e Test da aplicación
    runs-on: ubuntu-latest     # O job execútase nunha máquina Linux

    steps:
      # Step 1: Clonar o código fonte do repositorio
      - name: Checkout do repositorio
        uses: actions/checkout@v4

      # Step 2: Configurar Node.js (versión 20)
      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # Step 3: Instalar dependencias do proxecto
      - name: Instalar dependencias
        run: npm install

      # Step 4: Executar tests automáticos
      - name: Executar tests
        run: npm test

      # Step 5: Gardar artefactos xerados (por exemplo, o build)
      - name: Gardar build como artefacto
        if: success()          # Só se os tests pasan
        run: npm run build
      - name: Subir artefacto
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: ./dist          # Cartafol que contén o resultado de npm run build

  # ---------- JOB 2: DEPLOY ----------
  deploy:
    name: Despregamento da aplicación
    runs-on: ubuntu-latest
    needs: build                # Este job execútase só se o build remata correctamente

    steps:
      # Step 1: Descargar artefacto do job anterior
      - name: Descargar artefacto do build
        uses: actions/download-artifact@v4
        with:
          name: build-output
          path: ./dist

      # Step 2: Subir ficheiros ao servidor remoto
      # Neste exemplo úsase SCP (Secure Copy Protocol)
      - name: Despregar en servidor remoto
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          source: "./dist/*"
          target: "/var/www/mi-aplicacion"

      # Step 3: Reiniciar o servizo remoto (opcional)
      - name: Reiniciar servizo en servidor remoto
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            pm2 restart mi-aplicacion || pm2 start dist/index.js --name mi-aplicacion

---

Explicación detallada paso a paso

Paso 1 - Activación do workflow

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

O fluxo actívase automaticamente cada vez que:

• Se sobe código (push) á rama principal (main).
• Se crea ou actualiza unha pull request cara a esa rama.

Deste modo, o fluxo verifica o código antes de integralo definitivamente en produción.

---

Paso 2 - Job 1: build

Este job valida que o proxecto funcione correctamente.

jobs:
  build:
    runs-on: ubuntu-latest

O job execútase nunha máquina virtual Linux proporcionada por GitHub.

Pasos dentro do job:

Paso	Acción	Explicación
Checkout	actions/checkout@v4	Clona o repositorio para que GitHub Actions poida acceder ao código fonte.
Configurar Node	actions/setup-node@v4	Instala Node.js (neste caso, a versión 20).
Instalar dependencias	npm install	Descarga as librarías definidas en package.json.
Executar tests	npm test	Lanza as probas automatizadas (unitarias, integración, etc.).
Gardar build	npm run build + upload-artifact	Crea unha versión compilada da aplicación (por exemplo, en dist/) e almacénaa para usala despois.

Nota

O uso de actions/upload-artifact permite pasar ficheiros entre jobs, algo esencial cando o despregamento ocorre noutro job distinto.

---

Paso 3 - Job 2: deploy

Este segundo job só se executa se o anterior (build) finalizou correctamente.

Especifícase mediante a liña:

needs: build

Deste modo evitamos despregar versións con erros.

Pasos dentro do job:

Paso	Acción	Explicación
Descargar artefacto	actions/download-artifact@v4	Recupera os ficheiros xerados polo job build.
Subir ao servidor	appleboy/scp-action@v0.1.7	Usa o protocolo SCP para copiar os ficheiros ao servidor remoto.
Reiniciar o servizo	appleboy/ssh-action@v1.2.0	Conéctase ao servidor por SSH e reinicia a aplicación (por exemplo, usando pm2).

---

Paso 4 - Variables secretas e seguridade

As credenciais de acceso ao servidor (IP, usuario, chave SSH) nunca deben escribirse directamente no ficheiro YAML.

No seu lugar, gárdanse na configuración do repositorio en Settings → Secrets and variables → Actions.

Alí defínense as variables:

• SERVER_HOST
• SERVER_USER
• SERVER_SSH_KEY

Estas invócanse dentro do workflow coa sintaxe ${{ secrets.NOME }}.

Deste xeito, o despregamento é seguro e automatizado.