Skip to main content

Utilizar scripts para probar tu código en un ejecutor

Cómo utilizar características esenciales de GitHub Actions para una integración continua (IC).

Resumen de ejemplo

This article uses an example workflow to demonstrate some of the main CI features of GitHub Actions. Cuando se activa este flujo de trabajo, este ejecuta automáticamente un script que verifica si el sitio de GitHub Docs tiene enlaces rotos.

The following diagram shows a high level view of the workflow's steps and how they run within the job:

Diagrama de resumen de los pasos del flujo de trabajo

Características utilizadas en este ejemplo

The example workflow demonstrates the following capabilities of GitHub Actions:

CaracterísticaImplementación
Triggering a workflow to run automatically:push
Triggering a workflow to run automatically:pull_request
Manually running a workflow from the UI:workflow_dispatch
Setting permissions for the token:permissions
Controlling how many workflow runs or jobs can run at the same time:concurrency
Ejecutar el job en ejecutores diferentes, dependiendo del repositorio:runs-on
Cloning your repository to the runner:actions/checkout
Installing node on the runner:actions/setup-node
Utilizar una acción de terceros:trilom/file-changes-action

Ejemplo de flujo de trabajo

The following workflow was created by the GitHub Docs Engineering team. To review the latest version of this file in the github/docs repository, see link-check-all.yml.

Note: Each line of this workflow is explained in the next section at "Understanding the example."

YAML
name: 'Link Checker: All English'

# **What it does**: Renders the content of every page and check all internal links.
# **Why we have it**: To make sure all links connect correctly.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: read
  # Needed for the 'trilom/file-changes-action' action
  pull-requests: read

# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

jobs:
  check-links:
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm

      - name: Install
        run: npm ci

      # Creates file "$/files.json", among others
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

      # For verification
      - name: Show files changed
        run: cat $HOME/files.json

      - name: Link check (warnings, changed files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --max 100 \
            --check-anchors \
            --check-images \
            --verbose \
            --list $HOME/files.json

      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

Cómo entender el ejemplo

The following table explains how each of these features are used when creating a GitHub Actions workflow.

Código Explicación
YAML
name: 'Link Checker: All English'

The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.

YAML
on:

La palabra clave on te permite definir los eventos que se activan cuando se ejecuta el flujo de trabajo. Puedes definir eventos múltiples aquí. Para obtener más información, consulta la sección "Activar un flujo de trabajo".

YAML
  workflow_dispatch:

Agrega el evento workflow_dispatch si quieres poder ejecutar este flujo de trabajo manualmente desde la IU. Para obtener más información, consulta workflow_dispatch.

YAML
  push:
    branches:
      - main

Agrega el evento push para que el flujo de trabajo se ejecute automáticamente cada vez que se suba una confirmación a una rama llamada main. Para obtener más información, consulta push.

YAML
  pull_request:

Agrega el evento pull_request para que el flujo de trabajo se ejecute automáticamente cada que se cree o actualice una solicitud de cambios. Para obtener más información, consulta pull_request.

YAML
permissions:
  contents: read
  pull-requests: read

Modifica los permisos predeterminados que se otorgan al GITHUB_TOKEN. Esto variará dependiendo de las necesidades de tu flujo de trabajo. Para obtener más información, consulta la sección "Asignar permisos a los jobs".

YAML
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'

Crea un grupo de concurrencia para los eventos específicos y utiliza el operador || para definir los valores de reserva. Para obtener más información, consulta la sección "Utilizar concurrencia".

YAML
  cancel-in-progress: true

Cancela cualquier job o flujo de trabajo concurrentes en el mismo grupo de concurrencia.

YAML
jobs:

Agrupa todos los jobs que se ejecutan en el archivo de flujo de trabajo.

YAML
  check-links:

Define un job con la ID check-links que se almacena dentro de la llave jobs.

YAML
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}

Configura el job para ejecutarse en un ejecutor hospedado en GitHub o en un ejecutor auto-hospedado, dependiendo del repositorio que ejecuta el flujo de trabajo. En este ejemplo, el job se ejecutará en un ejecutor auto-hospedado si se nombra al repositorio docs-internal y está dentro de la organización github. Si el repositorio no empata con esta ruta, entonces se ejecutará en un ejecutor ubuntu-latest hospedado por GitHub. Para obtener más información sobre estas opciones, consulta la sección "Elegir el ejecutor para un job".

YAML
    steps:

Agrupa a todos los pasos que se ejecutarán como parte del job check-links. Cada job en un flujo de trabajo tiene su propia sección de steps.

YAML
      - name: Checkout
        uses: actions/checkout@v3

La palabra clave uses le indica al job recuperar la acción llamada actions/checkout. Esta es una acción que revisa tu repositorio y lo descarga al ejecutor, lo que te permite ejecutar acciones contra tu código (tales como las herramientas de prueba). Debes utilizar la acción de verificación cada que tu flujo de trabajo se ejecute contra el código del repositorio o cada que estés utilizando una acción definida en el repositorio.

YAML
      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm

Este paso utiliza la acción actions/setup-node para instalar la versión específica del paquete de software de Node.js en el ejecutor, lo cual te da acceso al comando npm.

YAML
      - name: Install
        run: npm ci

La palabra clave run le indica al job ejecutar un comando en el ejecutor. En este caso, npm ci se utiliza para instalar los paquetes de software de npm para el proyecto.

YAML
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

Utiliza la acción trilom/file-changes-action para juntar todos los archivos que cambiaron. Este ejemplo se fija a una versión específica de la acción utilizando el SHA a6ca26c14274c33b15e6499323aac178af06ad4b.

YAML
      - name: Show files changed
        run: cat $HOME/files.json

Lista el contenido de files.json. Esto se podrá ver en la bitácora de ejecución de flujo de trabajo y podrá ser útil para la depuración.

YAML
      - name: Link check (warnings, changed files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --max 100 \
            --check-anchors \
            --check-images \
            --verbose \
            --list $HOME/files.json

Este paso usa el comando run para ejecutar un script que está almacenado en el repositorio en script/rendered-content-link-checker.mjs y pasa todos los parámetros que necesita para ejecutarse.

YAML
      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

Este paso también utiliza el comando run para ejecutar un script que se almacena en el repositorio en script/rendered-content-link-checker.mjs y pasa un conjunto de parámetros diferentes.

Pasos siguientes