Uso de bloques de creación escritos previamente en el flujo de trabajo

Información general

En el flujo de trabajo puede usar bloques de creación escritos previamente, denominados acciones. Una acción es un conjunto predefinido y reutilizable de trabajos o código que realiza tareas específicas dentro de un flujo de trabajo.

Las acciones pueden ser:

• Reutilizables: las acciones se pueden usar en diferentes flujos de trabajo y repositorios, lo que le permite evitar volver a escribir el mismo código.
• Escritas previamente: muchas acciones están disponibles en GitHub Marketplace, y abarcan una amplia gama de tareas, como las de extracción de código del repositorio, configuración de entornos, ejecución de pruebas e implementación de aplicaciones.
• Configurables: puede configurar acciones con entradas, salidas y variables de entorno para adaptarlas a necesidades específicas.
• Controladas por la comunidad: puede crear acciones propias y compartirlas con otros usuarios, o bien usar acciones desarrolladas por la comunidad.

Las acciones que utilizas en tu flujo de trabajo pueden definirse en:

• El mismo repositorio que tu archivo de flujo de trabajo
• Un repositorio interno con la mismo cuenta empresarial que se configuró para permitir el acceso a los flujos de trabajo
• Cualquier repositorio público
• Una imagen del contenedor Docker publicada en Docker Hub

GitHub Marketplace es una ubicación central para que busque acciones creadas por la comunidad de GitHub. En la página GitHub Marketplace puede filtrar las acciones por categoría.

Buscar las acciones de Marketplace en el editor de flujo de trabajo

Puedes buscar acciones manualmente o por coincidencia exacta directamente en el editor de flujo de datos de tu repositorio. Desde la barra lateral, puedes buscar una acción específica, ver las acciones destacadas, y buscar manualmente las categorías destacadas. También puedes ver la cantidad de estrellas que una acción ha recibido desde la comunidad GitHub.

1. En tu repositorio, navega hasta el archivo de flujo de trabajo que deseas editar.
2. En la esquina superior derecha de la vista del archivo, haga clic en para abrir el editor de flujos de trabajo.
   
3. A la derecha del editor, utiliza la barra lateral de GitHub Marketplace para buscar las acciones. Las acciones con la insignia de indican que GitHub verificó que el creador de la acción es una organización asociada.
   

Agregar una acción a tu flujo de trabajo

Puedes agregar una acción a tu flujo de trabajo si la referencias en tu archivo de flujo de trabajo.

Puedes ver las acciones referenciadas en tus flujos de trabajo de GitHub Actions como dependencias en la gráfica de dependencias del repositorio que contiene tus flujos de trabajo. Para más información, vea "Acerca del gráfico de dependencias".

Agregar una acción desde GitHub Marketplace

Las páginas de listado de acciones incluyen la versión de la acción y la sintaxis de flujo de trabajo que se requiere para utilizar dicha acción. Para mantener estable a tu flujo de trabajo, aún cuando se hagan actualizaciones en una acción, puedes referenciar la versión de la acción a utilizar si especificas el número de etiqueta de Git o de Docker en tu archivo de flujo de trabajo.

1. Navega hasta la acción que deseas usar en tu flujo de trabajo.
2. Haga clic para ver la lista completa de Marketplace para la acción.
3. En "Instalación", haga clic en para copiar la sintaxis del flujo de trabajo.
   
4. Pega la sintaxis como un nuevo paso en tu flujo de trabajo. Para obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».
5. Si la accion requiere que proprociones información de entrada, configúrala en tu flujo de trabajo. Para obtener información sobre las entradas que puede requerir una acción, consulte "Uso de bloques de creación escritos previamente en el flujo de trabajo".

También puedes habilitar las Dependabot version updates para las acciones que agregas a tu flujo de trabajo. Para obtener más información, vea «Mantener tus acciones actualizadas con el Dependabot».

Agregar una acción desde el mismo repositorio

Si una acción se define en el mismo repositorio donde el archivo de flujo de trabajo usa la acción, puede hacer referencia a la acción con la sintaxis {owner}/{repo}@{ref} o ./path/to/dir en el archivo de flujo de trabajo.

Ejemplo de estructura de archivo de repositorio:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

La ruta de acceso es relativa (./) al directorio de trabajo predeterminado (github.workspace, $GITHUB_WORKSPACE). Si la acción comprueba el repositorio en una ubicación diferente del flujo de trabajo, se debe actualizar la ruta de acceso relativa que se usa para las acciones locales.

Ejemplo de archivo de flujo de trabajo:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

El archivo action.yml se usa a fin de proporcionar metadatos para la acción. Obtenga información sobre el contenido de este archivo en "Sintaxis de metadatos para Acciones de GitHub".

Agregar una acción desde un repositorio diferente

Si se define una acción en un repositorio diferente al del archivo de flujo de trabajo, puede hacer referencia a la acción con la sintaxis {owner}/{repo}@{ref} en el archivo de flujo de trabajo.

La acción debe almacenarse en un repositorio público o interno que se configure para permitir el acceso a los flujos de trabajo. Para obtener más información, consulte "Compartir acciones y flujos de trabajo con tu empresa".

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

Hacer referencia a un contenedor en Docker Hub

Si se define una acción en una imagen de contenedor Docker publicada en Docker Hub, debe hacer referencia a la acción con la sintaxis docker://{image}:{tag} en el archivo de flujo de trabajo. Para proteger tu código y tus datos, te recomendamos que verifiques la integridad de la imagen del contenedor Docker de Docker Hub antes de usarla en tu flujo de trabajo.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Para obtener algunos ejemplos de acciones de Docker, vea el flujo de trabajo Docker-image.yml y "Creación de una acción de contenedor de Docker".

Protección de la seguridad para el uso de acciones en los flujos de trabajo

GitHub proporciona características de seguridad que puede usar para aumentar la seguridad de los flujos de trabajo. Puede usar las características integradas de GitHub para asegurarse de que se le notifican las vulnerabilidades en las acciones que consume o para automatizar el proceso de mantener actualizadas las acciones de los flujos de trabajo. Para obtener más información, vea «Uso de las características de seguridad de GitHub para proteger el uso de Acciones de GitHub».

Utilizar la administración de lanzamientos para tus acciones personalizadas

Los creadores de una acción comunitaria tienen la opción de utilizar etiquetas, ramas, o valores de SHA para administrar los lanzamientos de la acción. Similar a cualquier dependencia, debes indicar la versión de la acción que te gustaría utilizar basándote en tu comodidad con aceptar automáticamente las actualizaciones para dicha acción.

Designarás la versión de la acción en tu archivo de flujo de trabajo. Revisa la documentación de la acción para encontrar información de su enfoque sobre la administración de lanzamientos, y para ver qué etiqueta, rama, o valor de SHA debes utilizar.

Usar etiquetas

Las etiquetas son útiles para que te permitan decidir cuándo cambiar entre versiones mayores y menores, pero son más efímeras y el mantenedor puede moverlas o borrarlas. Este ejemplo se muestra cómo seleccionar una acción etiquetada como v1.0.1:

steps:
  - uses: actions/javascript-action@v1.0.1

Utilizar SHAs

Si necesitas utilizar un versionamiento más confiable, debes utilizar el valor de SHA asociado con la versión de la acción. Los SHA son inmutables y, por lo tanto, más confiables que las etiquetas o las ramas. Sin embargo, este acercamiento significa que no recibirás actualizaciones para una acción automáticamente, incluyendo las correcciones de errores y actualizaciones de seguridad. Debes utilizar un valor SHA completo de la confirmación y no un valor abreviado. Al seleccionar un SHA, debe comprobar que se encuentra en el repositorio de la acción y no en una bifurcación de repositorio. Este ejemplo tiene como objetivo el SHA de una acción:

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Utilizar ramas

El especificar una rama destino para la acción significa que ésta siempre ejecutará la versión que se encuentre actualmente en dicha rama. Este acercamiento puede crear problemas si una actualización a la rama incluye cambios importantes. Este ejemplo tiene como destino una rama denominada @main:

steps:
  - uses: actions/javascript-action@main

Para obtener más información, vea «Acercad e las acciones personalizadas».

Utilizar entradas y salidas con una acción

Una acción a menudo acepta o requiere entradas y genera salidas que puedes utilizar. Por ejemplo, una acción podría requerir que especifiques una ruta a un archivo, el nombre de una etiqueta, u otros datos que utilizará como parte del procesamiento de la misma.

Para ver las entradas y salidas de una acción, compruebe action.yml o action.yaml en el directorio raíz del repositorio.

En este ejemplo action.yml, la palabra clave inputs define una entrada necesaria denominada file-path e incluye un valor predeterminado que se usará si no se especifica ninguno. La palabra clave outputs define una salida denominada results-file, que indica dónde buscar los resultados.

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

Pasos siguientes

Para continuar el aprendizaje sobre GitHub Actions, consulta "Entender las GitHub Actions".