Comandos de flujo de trabajo para Acciones de GitHub

Acerca de los comandos de flujo

Las acciones pueden comunicarse con la máquina del ejecutor para establecer variables de entorno, valores de salida utilizados por otras acciones, agregar mensajes de depuración a los registros de salida y otras tareas.

La mayoría de los comandos de flujo de trabajo usan el comando echo en un formato específico, mientras que otros se pueden invocar escribiendo en un archivo. Para más información, vea "Archivos de entorno".

Ejemplo de un comando de flujo de trabajo

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

Utilizar comandos de flujo de trabajo para acceder a las funciones de toolkit

En actions/toolkit se incluye una serie de funciones que se pueden ejecutar como comandos de flujo de trabajo. Use la sintaxis :: para ejecutar los comandos de flujo de trabajo dentro del archivo YAML; estos comandos se envían al ejecutor por medio de stdout. Por ejemplo, en lugar de usar código para crear una anotación de error, como aquí:

core.error('Missing semicolon', {file: 'app.js', startLine: 1})

Ejemplo: Crear una anotación de un error

Puedes usar el comando error en tu flujo de trabajo para crear la misma anotación de error:

      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"

      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"

La siguiente tabla muestra qué funciones del toolkit se encuentran disponibles dentro de un flujo de trabajo:

Agregar un mensaje de depuración

Imprime un mensaje de depuración en el registro. Debe crear un secreto denominado ACTIONS_STEP_DEBUG con el valor true para ver los mensajes de depuración establecidos por este comando en el registro. Para obtener más información, vea «Habilitación del registro de depuración».

::debug::{message}

Ejemplo: Configurar un mensaje de depuración

echo "::debug::Set the Octocat variable"

Write-Output "::debug::Set the Octocat variable"

Configurar un mensaje de aviso

Crea un mensaje de aviso e imprime el mensaje en la bitácora. Este mensaje creará una anotación, la cual puede asociar el mensaje con un archivo particular de tu repositorio. Opcionalmente, tu mensaje puede especificar una posición dentro del archivo.

::notice file={name},line={line},endLine={endLine},title={title}::{message}

Ejemplo: configurar un mensaje de notificación

echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Configurar un mensaje de advertencia

Crea un mensaje de advertencia e imprime el mensaje en el registro. Este mensaje creará una anotación, la cual puede asociar el mensaje con un archivo particular de tu repositorio. Opcionalmente, tu mensaje puede especificar una posición dentro del archivo.

::warning file={name},line={line},endLine={endLine},title={title}::{message}

Ejemplo: Configurar un mensaje de advertencia

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Configurar un mensaje de error

Crea un mensaje de error e imprime el mensaje en el registro. Este mensaje creará una anotación, la cual puede asociar el mensaje con un archivo particular de tu repositorio. Opcionalmente, tu mensaje puede especificar una posición dentro del archivo.

::error file={name},line={line},endLine={endLine},title={title}::{message}

Ejemplo: Configurar un mensaje de error

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Agrupar líneas de las bitácoras

Crea un grupo expansible en la bitácora. Para crear un grupo, use el comando group y especifique title. Todo lo que imprima en el registro entre los comandos group y endgroup se anida dentro de una entrada expandible en el registro.

::group::{title}
::endgroup::

Ejemplo: Agrupar líneas de bitácoras

jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"

jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"

Enmascarar un valor en el registro

::add-mask::{value}

El enmascaramiento de un valor impide que una cadena o variable se imprima en el registro. Cada palabra enmascarada separada por un espacio en blanco se reemplaza con el carácter *. Puede usar una variable de entorno o una cadena para el valor value de la máscara. Al enmascarar un valor, se trata como un secreto y se oculta en el ejecutor. Por ejemplo, después de enmascarar un valor, no podrá establecerlo como salida.

Ejemplo: Enmascarar una secuencia

Al imprimir "Mona The Octocat" en el registro, verá "***".

echo "::add-mask::Mona The Octocat"

Write-Output "::add-mask::Mona The Octocat"

Ejemplo: Enmascarar una variable de ambiente

Al imprimir la variable MY_NAME o el valor "Mona The Octocat" en el registro, verá "***" en lugar de "Mona The Octocat".

jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"

jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

Detener e iniciar comandos de flujo de trabajo

Deja de procesar cualquier comando de flujo de trabajo. Este comando especial te permite registrar lo que sea sin ejecutar accidentalmente un comando de flujo de trabajo. Por ejemplo, podrías dejar de registrar para producir un script completo que tenga comentarios.

::stop-commands::{endtoken}

Para detener el procesamiento de los comandos de flujo de trabajo, pase un token único a stop-commands. Para resumir los comandos de flujo de trabajo de procesamiento, pasa el mismo token que utilizaste para detener los comandos de flujo de trabajo.

::{endtoken}::

Ejemplo: Parar e iniciar comandos de flujos de trabajo

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'

jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

Enviar valores a las acciones pre y post

Puedes crear variables de entorno para compartirlas con las acciones pre: o post: del flujo de trabajo, escribiendo para ello en el archivo ubicado en GITHUB_STATE.. Por ejemplo, puede crear un archivo con la acción pre:, pasar la ubicación del archivo a la acción main: y, después, usar la acción post: para eliminar el archivo. Como alternativa, podría crear un archivo con la acción main:, pasar la ubicación del archivo a la acción post: y también usar la acción post: para eliminar el archivo.

Si tienes varias acciones pre: o post:, solo podrás acceder al valor guardado en la acción donde se escribió en GITHUB_STATE. Para más información sobre la acción post:, consulta "Sintaxis de metadatos para Acciones de GitHub".

El archivo GITHUB_STATE solo está disponible dentro de una acción. El valor guardado se almacena como un valor de entorno con el prefijo STATE_.

En este ejemplo se usa JavaScript para escribir en el archivo GITHUB_STATE. La variable de entorno resultante se denomina STATE_processID con el valor de 12345:

import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})

Después, la variable STATE_processID está disponible exclusivamente para el script de limpieza que se ejecuta en la acción main. Este ejemplo se ejecuta en main y usa JavaScript para mostrar el valor asignado a la variable de entorno STATE_processID:

console.log("The running PID from the main action is: " +  process.env.STATE_processID);

Archivos de ambiente

Durante la ejecución de un flujo de trabajo, el ejecutor genera archivos temporales que pueden utilizarse para llevar a cabo ciertas acciones. La ruta a estos archivos se expone a través de variables de ambiente. Necesitarás utilizar codificación UTF-8 cuando escribas en estos archivos para garantizar el procesamiento adecuado de los comandos. Se pueden escribir varios comandos en el mismo archivo, separados por líneas nuevas.

La mayoría de los comandos de los ejemplos siguientes usan comillas dobles para las cadenas de eco, que intentarán interpolar caracteres como $ para nombres de variables de shell. Para usar siempre valores literales en cadenas entre comillas, puedes usar comillas simples en su lugar.

jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

Configuración de una variable de entorno

echo "{environment_variable_name}={value}" >> $GITHUB_ENV

Puede hacer que una variable de entorno esté disponible en cualquier paso posterior de un trabajo de un flujo de trabajo si define o actualiza la variable de entorno, y lo escribe en el archivo de entorno GITHUB_ENV. El paso que crea o actualiza la variable de ambiente no tiene acceso al valor nuevo, pero todos los pasos subsecuentes en un job tendrán acceso. Los nombres de las variables de ambiente distinguen entre mayúsculas y minúsculas y puedes incluir signos de puntuación. Para obtener más información, vea «variables».

Ejemplo de escritura de una variable de entorno en GITHUB_ENV

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'

steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "${{ env.action_state }}" # This will output 'yellow'

Secuencias de línea múltiple

Para las secuencias de lìnea mùltiple, puedes utilizar un delimitador con la siguiente sintaxis.

{name}<<{delimiter}
{value}
{delimiter}

Ejemplo de una cadena de varias líneas

En este ejemplo se selecciona un valor aleatorio para $EOF como delimitador y se establece la variable de entorno JSON_RESPONSE en el valor de la respuesta curl.

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      echo "JSON_RESPONSE<<$EOF" >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo "$EOF" >> $GITHUB_ENV

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "$EOF" >> $env:GITHUB_ENV
    shell: pwsh

Configurar un parámetro de salida

Establece el parámetro de salida de un paso. Ten en cuenta en el paso hay que definir un id para recuperar el valor de salida posteriormente.

echo "{name}={value}" >> $GITHUB_OUTPUT

"{name}=value" >> $env:GITHUB_OUTPUT

Ejemplo de configuración de un parámetro de salida

      - name: Set color
        id: random-color-generator
        run: echo "SELECTED_COLOR=green" >> $GITHUB_OUTPUT
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

      - name: Set color
        id: random-color-generator
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

Adición de un resumen de trabajos

echo "{markdown content}" >> $GITHUB_STEP_SUMMARY

"{markdown content}" >> $env:GITHUB_STEP_SUMMARY

Puedes establecer Markdown personalizado para cada trabajo de modo que se muestre en la página de resumen de una ejecución de flujo de trabajo. Puedes usar resúmenes de trabajos para mostrar y agrupar contenido único, como resúmenes de resultados de pruebas, de modo que alguien que vea el resultado de una ejecución de flujo de trabajo no necesite ir a los registros para ver información importante relacionada con la ejecución, como errores.

Los resúmenes de trabajos admiten Markdown de tipo GitHub y puedes agregar el contenido de Markdown para un paso al archivo de entorno GITHUB_STEP_SUMMARY. GITHUB_STEP_SUMMARY es único para cada paso de un trabajo. Para obtener más información sobre el archivo por paso al que hace referencia GITHUB_STEP_SUMMARY, consulta "Archivos de entorno".

Cuando un trabajo finaliza, los resúmenes de todos los pasos de un trabajo se agrupan en un único resumen de trabajo y se muestran en la página resumen de ejecución del flujo de trabajo. Si varios trabajos generan resúmenes, estos se ordenan según la hora de finalización del trabajo.

Ejemplo de adición de un resumen del trabajo

echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY

"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY

Contenido de Markdown multilínea

En el caso de contenido de Markdown multilínea, puedes usar >> para anexar continuamente contenido al paso actual. Con cada operación de anexión, se agrega automáticamente un carácter de nueva línea.

Ejemplo de contenido de Markdown multilínea

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY

- name: Generate list using Markdown
  run: |
    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY

Sobrescritura de resúmenes de trabajos

Para borrar todo el contenido del paso actual, puedes usar > para sobrescribir cualquier contenido agregado anteriormente.

Ejemplo de sobrescribir resúmenes de trabajos

- name: Overwrite Markdown
  run: |
    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY

- name: Overwrite Markdown
  run: |
    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
    "There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY

Eliminación de resúmenes de trabajos

Para quitar completamente un resumen del paso actual, se puede eliminar el archivo al que hace referencia GITHUB_STEP_SUMMARY.

Ejemplo de eliminación de resúmenes de trabajos

- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY

- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    rm $env:GITHUB_STEP_SUMMARY

Una vez que se ha completado un paso, se cargan los resúmenes de trabajo y los pasos posteriores no pueden modificar el contenido de Markdown cargado anteriormente. Los resúmenes enmascaran automáticamente los secretos que podrían haberse agregado de forma accidental. Si un resumen de trabajo contiene información confidencial que se debe eliminar, puedes eliminar toda la ejecución del flujo de trabajo para quitar todos sus resúmenes de trabajo. Para más información, consulta "Borrar una ejecución de flujo de trabajo".

Aislamiento y límites de pasos

Los resúmenes de trabajo están aislados entre los pasos y cada paso está restringido a un tamaño máximo de 1 MiB. Se aplica aislamiento entre los pasos para que el Markdown que podría tener un formato incorrecto en un paso no pueda interrumpir la representación de Markdown para los pasos posteriores. Si se agrega más de 1 MiB de contenido a un paso, se producirá un error en la carga del paso y se creará una anotación de error. Los errores de carga de resúmenes de trabajos no afectan al estado general de un paso o un trabajo. Se muestra un máximo de 20 resúmenes de trabajos de los pasos por trabajo.

Agregar una ruta de sistema

Antepone un directorio a la variable del sistema PATH y hace que esté disponible automáticamente para todas las acciones posteriores en el trabajo actual; la acción que está actualmente en ejecución no puede acceder a la variable de ruta actualizada. A fin de ver las rutas definidas actualmente para el trabajo, puede usar echo "$PATH" en un paso o una acción.

echo "{path}" >> $GITHUB_PATH

"{path}" >> $env:GITHUB_PATH

Ejemplo de adición de una ruta de acceso del sistema

echo "$HOME/.local/bin" >> $GITHUB_PATH

"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH