Sintaxis de contextos y expresiones para acciones de GitHub

En este artículo

• Acerca del contexto y las expresiones
• Contextos
• Literales
• Operadores
• Funciones
• Funciones de verificación del estado del trabajo
• Filtros de objetos

Acerca del contexto y las expresiones

Puedes usar expresiones para establecer variables programáticamente en archivos de flujo de trabajo y contextos de acceso. Una expresión puede ser cualquier combinación de valores literales, referencias a un contexto, o funciones. Puedes combinar literales, referencias de contexto y funciones usando operadores.

Las expresiones se utilizan comúnmente con la palabra clave condicional if en un archivo de flujo de trabajo para determinar si un paso debe ejecutar. Cuando un condicional if es true, se ejecutará el paso.

Debes usar una sintaxis específica para decirle a GitHub que evalúe una expresión en lugar de tratarla como una cadena.

{{ <expression> }}

Cuando usas expresiones if condicionales, no necesitas usar la sintaxis de la expresión ({{ }}) porque GitHub evalúa automáticamente el if condicional como una expresión. For more information about if conditionals, see "Workflow syntax for Acciones de GitHub."

Expresión de ejemplo en un condicional if

steps:
  - uses: actions/hello-world-javascript-action@master
    if: <expression>

Ejemplo de parámetros en una variable de entorno

env:
  my_env_var: ${{ <expression> }}

Contextos

Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Los contextos usan la sintaxis de expresión.

{{ <context> }}

Como parte de una expresión, puedes acceder a la información del contexto usando una de dos sintaxis.

• Sintaxis del índice: github['sha']
• Sintaxis de desreferencia de propiedad: github.sha

Para usar la sintaxis de desreferencia de propiedad, el nombre de la propiedad debe cumplir con lo siguiente:

• comienza con a-Z o _.
• esté seguido por a-Z 0-9 - o _.

contexto github

El contexto de github contiene información sobre la ejecución del flujo de trabajo y el evento que desencadenó la ejecución. Puedes leer la mayoría de los datos de contexto de github en las variables del entorno. Para más información sobre las variables de entorno, consulta "Utilizando variables de entorno."

contexto job

El contexto job contiene información sobre el trabajo de ejecución actual.

contexto steps

El contexto steps contiene información sobre los pasos en el trabajo actual que ya se ha ejecutado.

Contexto runner

El contexto runner contiene información sobre el ejecutador (runner) que está ejecutando el trabajo actual.

Ejemplo de impresión de información de contexto de un archivo de registro

Para inspeccionar la información accesible en cada contexto, puedes utilizar este ejemplo de archivo de flujo de trabajo.

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

Literales

Como parte de una expresión, puedes usar tipos de datos boolean, null, number o string. Los literales booleanos no reconocen minúsculas de mayúsculas, por lo que puedes usar true o Treu.

Ejemplo

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99-e2 }}
  myString: ${{ 'Mona the Octocat' }}
  myEscapedString: ${{ 'It''s open source!' }

Operadores

GitHub realiza comparaciones de igualdad flexible.

• Si los tipos no coinciden, GitHub fuerza el tipo a un número. GitHub fusiona los tipos de datos con un número usando estas conversiones:

  Tipo	Resultado
  Null	0
  Boolean	true devuelve 1 falso devuelve 0
  Cadena	Analizado desde cualquier formato de número JSON legal, de lo contrario NaN. Nota: la cadena vacía devuelve 0.
  Array	NaN
  Object	NaN

• Una comparación de un NaN a otro NaN no resulta en true. Para obtener más información, consulta "Documentos Mozilla NaN".

• GitHub ignora las mayúsculas y minúsculas al comparar cadenas.

• Los objetos y matrices solo se consideran iguales si son la misma instancia.

Funciones

GitHub ofrece un conjunto de funciones integradas que puedes usar en expresiones. Algunas funciones fusionan valores en una cadena para realizar las comparaciones. GitHub fusiona los tipos de datos con una cadena usando estas conversiones:

Contiene

contains( searchString, searchValue )

Devuelve true si searchString contiene searchValue. Si searchString es una matriz, esta función devuelve true si searchValue es un elemento en la matriz. Esta función no distingue mayúsculas de minúsculas. Fusiona valores en una cadena.

Ejemplo

contains('Hello world', 'llo') devuelve true

startsWith

startsWith( searchString, searchValue )

Devuelve true cuando searchString contiene searchValue. Esta función no distingue mayúsculas de minúsculas. Fusiona valores en una cadena.

Ejemplo

startsWith('Hello world', 'He') devuelve true

endsWith

endsWith( searchString, searchValue )

Devuelve true si searchString contiene searchValue. Esta función no distingue mayúsculas de minúsculas. Fusiona valores en una cadena.

Ejemplo

endsWith('Hello world', 'He') devuelve true

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

Reemplaza valores en la cadena, con la variable replaceValueN. Las variables en la cadena se especifican con la sintaxis {N}, donde N es un entero. Debes especificar al menos un replaceValue y una cadena. No existe un máximo para el número de variables (replaceValueN) que puedes usar. Escapar llaves usando llaves dobles.

Ejemplo

Devuelve 'Hello Mona the Octocat'

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

Ejemplo de evasión de llaves

Devuelve '{Hello Mona the Octocat}'

format('{{Hello {0} {1} {2}}}', 'Mona', 'the', 'Octocat')

join

join( element, optionalElem )

El valor para element puede ser una matriz o una cadena. Todos los valores en element están concatenados en una cadena. Si proporcionas optionalElem, el valor se agrega al final del elemento. Fusiona valores en una cadena.

Ejemplo con matriz

join(['Hello', 'Mona', 'the'], 'Octocat') devuelve 'Hello Mona the Octocat'

Ejemplo con cadena

join('Hello', 'world!') devuelve 'Hello world!'

toJson

toJSON(value)

Devuelve una representación JSON con formato mejorado de valor. Puedes usar esta función para depurar la información suministrada en contextos.

Ejemplo

toJSON(job) puede devolver { "status": "Success" }

hashFiles

hashFiles(path)

Devuelve un solo hash para el conjunto de archivos que coinciden con el patrón de path. El path es relativo al directorio GITHUB_WORKSPACE y sólo puede incluir archivos dentro del directorio GITHUB_WORKSPACE. Esta función calcula un hash SHA-256 individual para cada archivo coincidente, y luego usa esos hash para calcular un hash final SHA-256 para el conjunto de archivos. Para más información sobre SHA-256, consulta "SHA-2."

You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "Workflow syntax for Acciones de GitHub."

Ejemplo

Matches any package-lock.json file in the repository.

hashFiles('**/package-lock.json')

Funciones de verificación del estado del trabajo

Puedes usar las siguientes funciones de verificación de estado como expresiones en condicionales if (si). Si la expresión if no contiene ninguna de las funciones de estado, se obtendrá automáticamente con success(). Para obtener información sobre los condicionales if, consulta "Sintaxis de flujo de trabajo para acciones de GitHub".

success

Devuelve true cuando el paso previo de un trabajo es exitoso.

Ejemplo

pasos:
  - name: my first step
    if: success()

always

Fuerza un condicional para evaluar como true incluso cuando está cancelado. No se ejecutará un trabajo o paso cuando una falla crítica impida que la tarea se ejecute. Por ejemplo, si fallaron las fuentes.

Ejemplo

if: always()

cancelled

Devuelve true si se canceló el flujo de trabajo.

Ejemplo

if: cancelled()

failure

Devuelve true cuando falla el paso previo de un trabajo.

Ejemplo

pasos:
  - name: my first step
    if: failure()

Filtros de objetos

Puedes usar la sintaxis * para aplicar un filtro y seleccionar los elementos coincidentes en una recopilación.

Por ejemplo, considera una matriz de objetos llamada fruits.

[
  { "name": "apple", "quantity": 1 },
  { "name": "orange", "quantity": 2 },
  { "name": "pear", "quantity": 1 }
]

El filtro fruits.*.name devuelve la matriz [ "apple", "orange", "pear" ]