Skip to main content

Comandos de flujo de trabajo para Acciones de GitHub

Puedes usar comandos de flujo de trabajo cuando ejecutas comandos de Shell en un flujo de trabajo o en el código de una acción.

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

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

Nota: Los nombres de parámetros y comandos de flujo de trabajo no distinguen mayúsculas de minúsculas.

Advertencia: Si utiliza el símbolo del sistema, omita los caracteres de comillas dobles (") al usar comandos de flujo de trabajo.

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 vez de utilizar código para configurar una salida, como se muestra aquí:

JavaScript
core.setOutput('SELECTED_COLOR', 'green');

Ejemplo: Configurar un valor

Puede usar el comando set-output en el flujo de trabajo para establecer el mismo valor:

YAML
      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"
YAML
      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: random-color-generator
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

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

Funcion del ToolkitComando equivalente del flujo de trabajo
core.addPathAccesible mediante el archivo de entorno GITHUB_PATH
core.debugdebug
core.noticenotice
core.errorerror
core.endGroupendgroup
core.exportVariableAccesible mediante el archivo de entorno GITHUB_ENV
core.getInputAccesible mediante la variable de entorno INPUT_{NAME}
core.getStateAccesible mediante la variable de entorno STATE_{NAME}
core.isDebugAccesible mediante la variable de entorno RUNNER_DEBUG

Configurar un parámetro de salida

Establece un parámetro de salida de la acción.

Code
::set-output name={name}::{value}

Opcionalmente, también puedes declarar parámetros de salida en el archivo de metadatos de una acción. Para más información, vea "Sintaxis de metadatos para GitHub Actions".

Ejemplo;: Configurar un parámetro de salida

Shell
echo "::set-output name=action_fruit::strawberry"
pwsh
Write-Output "::set-output name=action_fruit::strawberry"

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 más información, vea "Habilitación del registro de depuración".

Code
::debug::{message}

Ejemplo: Configurar un mensaje de depuración

Shell
echo "::debug::Set the Octocat variable"
pwsh
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.

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

| Parámetro | Valor | | :- | :- | | title | Título personalizado | | file | Nombre de archivo | | col | Número de columna, empezando en 1 | | endColumn | Número de columna final | | line | Número de línea, empezando en 1 | | endLine | Número de línea final |

Ejemplo: configurar un mensaje de notificación

Shell
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
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.

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

| Parámetro | Valor | | :- | :- | | title | Título personalizado | | file | Nombre de archivo | | col | Número de columna, empezando en 1 | | endColumn | Número de columna final | | line | Número de línea, empezando en 1 | | endLine | Número de línea final |

Ejemplo: Configurar un mensaje de advertencia

Shell
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
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.

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

| Parámetro | Valor | | :- | :- | | title | Título personalizado | | file | Nombre de archivo | | col | Número de columna, empezando en 1 | | endColumn | Número de columna final | | line | Número de línea, empezando en 1 | | endLine | Número de línea final |

Ejemplo: Configurar un mensaje de error

Shell
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
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.

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

Ejemplo: Agrupar líneas de bitácoras

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"
YAML
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::"

Grupo plegable en la bitácora de una ejecución de flujo de trabajo

Enmascarar un valor en el registro

Code
::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á "***".

Shell
echo "::add-mask::Mona The Octocat"
pwsh
Write-Output "::add-mask::Mona The Octocat"

Advertencia: asegúrate de registrar el secreto con "add-mask" antes de generarlo en los registros de compilación o usarlo en cualquier otro comando de flujo de trabajo.

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".

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"
YAML
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.

Code
::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.

Advertencia: Asegúrese de que el token que usa se genera aleatoriamente y es único para cada ejecución.

Code
::{endtoken}::

Ejemplo: Parar e iniciar comandos de flujos de trabajo

YAML
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.'
YAML
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.'

Hacer eco en las salidas de comando

Habilita o inhabilita el hacer eco en los comandos de los flujos de trabajo. Por ejemplo, si usa el comando set-output en un flujo de trabajo, establece un parámetro de salida pero el registro de la ejecución de flujo de trabajo no muestra el propio comando. Si habilita el eco de comandos, el registro muestra el comando, como ::set-output name={name}::{value}.

Code
::echo::on
::echo::off

El eco de comando se encuentra inhabilitado predeterminadamente. Sin embargo, los comandos de flujo de trabajo hacen eco si existen errores para procesarlos.

Los comandos add-mask, debug, warning y error no admiten el eco, porque sus salidas ya se han reproducido en el registro.

También puede habilitar el eco de comandos globalmente si activa el registro de depuración de pasos mediante el secreto ACTIONS_STEP_DEBUG. Para más información, vea "Habilitación del registro de depuración". Por el contrario, el comando de flujo de trabajo echo permite habilitar el eco de comandos en un nivel más granular, en vez de habilitarlo para cada flujo de trabajo en un repositorio.

Ejemplo: Alternar el eco de comandos

YAML
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          echo '::set-output name=action_echo::disabled'
          echo '::echo::on'
          echo '::set-output name=action_echo::enabled'
          echo '::echo::off'
          echo '::set-output name=action_echo::disabled'
YAML
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: toggle workflow command echoing
        run: |
          write-output "::set-output name=action_echo::disabled"
          write-output "::echo::on"
          write-output "::set-output name=action_echo::enabled"
          write-output "::echo::off"
          write-output "::set-output name=action_echo::disabled"

El ejemplo anterior imprime las siguientes líneas en la bitácora:

Code
::set-output name=action_echo::enabled
::echo::off

Solo los segundos comandos de flujo de trabajo set-output y echo se incluyen en el registro, porque el eco de comandos solo se ha habilitado al ejecutarlos. Aunque no siempre hace eco, el parámetro de salida se configura en todos los casos.

Enviar valores a las acciones pre y post

Puede usar el comando save-state para crear variables de entorno a fin de compartirlas con las acciones pre: o post: del flujo de trabajo. 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 tiene varias acciones pre: o post:, solo puede acceder al valor guardado en la acción donde se ha usado save-state. Para más información sobre la acción post:, vea "Sintaxis de metadatos para GitHub Actions".

El comando save-state solo se puede ejecutar dentro de una acción y no está disponible para los archivos YAML. El valor guardado se almacena como un valor de entorno con el prefijo STATE_.

En este ejemplo se usa JavaScript para ejecutar el comando save-state. La variable de entorno resultante se denomina STATE_processID con el valor de 12345:

JavaScript
console.log('::save-state name=processID::12345')

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:

JavaScript
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.

Nota: En las versiones 5.1 y posteriores de PowerShell (shell: powershell) no se usa UTF-8 de forma predeterminada, por lo que debe especificar la codificación UTF-8. Por ejemplo:

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

En las versiones 6 y superiores de PowerShell Core (shell: pwsh) se usa UTF-8 de forma predeterminada. Por ejemplo:

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

Configuración de una variable de entorno

Shell
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
  • Utilizar PowerShell versión 6 y superior:

    pwsh
    "{environment_variable_name}={value}" >> $env:GITHUB_ENV
  • Utilizar PowerShell versión 5.1 e inferior:

    powershell
    "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append

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 más información, vea "Variables de entorno".

Ejemplo

YAML
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'
YAML
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.

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

Advertencia: Asegúrate de que el delimitador que usas se genera aleatoriamente y es único para cada ejecución. Para más información, consulta "Descripción del riesgo de las inyecciones de scripts".

Ejemplo

En este ejemplo se usa EOF como delimitador y se establece la variable de entorno JSON_RESPONSE en el valor de la respuesta curl.

YAML
steps:
  - name: Set the value in bash
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://example.lab >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV
YAML
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      "JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.lab").Content >> $env:GITHUB_ENV
      "EOF" >> $env:GITHUB_ENV
    shell: pwsh

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.

Shell
echo "{path}" >> $GITHUB_PATH
pwsh
"{path}" >> $env:GITHUB_PATH

Ejemplo

En este ejemplo se muestra cómo agregar el directorio de usuario $HOME/.local/bin a PATH:

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

En este ejemplo se muestra cómo agregar el directorio de usuario $env:HOMEPATH/.local/bin a PATH:

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