Evaluación de expresiones en flujos de trabajo y acciones

Puedes utilizar expresiones para configurar variables de ambiente con programación en los 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 valores literales, referencias de contexto y funciones usando operadores. Para obtener más información sobre los contextos, consulta Acceso a información contextual sobre ejecuciones de flujo de trabajo.

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 ejecutarse. Cuando un condicional if es true, el paso se ejecutará.

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

${{ <expression> }}

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

Como parte de una expresión, puedes usar los tipos de datos boolean, null, number o string.

Ten en cuenta que en los condicionales, los valores falsificados (false, 0, -0, "", '', null) se convierten a false y los verdaderos (true y otros valores no falsificados) se convierten a true.

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

realiza comparaciones de igualdad flexible.

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

  Tipo	Resultado
  Null	0
  Boolean	true devuelve 1. false devuelve 0.
  String	Se analiza desde cualquier formato de número JSON legal; de lo contrario, NaN. Nota: La cadena vacía devuelve 0.
  Array	NaN
  Object	NaN

• Cuando NaN es uno de los operandos de cualquier comparación relacional (>, <, >=, <=), el resultado siempre es false. Para obtener más información, consulta la documentación de NaN Mozilla.

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

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

proporciona una manera de crear lógica condicional en expresiones mediante operadores lógicos binarios (&& y ||). Este patrón se puede usar para lograr una funcionalidad similar al operador ternario (?:) que se encuentra en muchos lenguajes de programación, mientras que realmente solo usa operadores binarios.

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

contains( search, item )

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

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

contains(.event.issue.labels.*.name, 'bug') devuelve true si el problema relacionado con el evento tiene una etiqueta "bug".

Para más información, consulta Filtros de objetos.

En lugar de escribir .event_name == "push" || .event_name == "pull_request", puedes usar contains() con fromJSON() para comprobar si una matriz de cadenas contiene un item.

Por ejemplo, contains(fromJSON('["push", "pull_request"]'), .event_name) devuelve true si .event_name es "push" o "pull_request".

startsWith( searchString, searchValue )

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

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

endsWith( searchString, searchValue )

Devuelve true si la cadena searchString está situada al final de la cadena searchValue. Esta función no distingue mayúsculas de minúsculas. Fusiona valores en una cadena.

endsWith('Hello world', 'ld') devuelve true.

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

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

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

Devuelve 'Hello Mona the Octocat'.

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

Devuelve '{Hello Mona the Octocat!}'.

join( array, optionalSeparator )

El valor de array puede ser una matriz o una cadena. Todos los valores de array se concatenan en una cadena. Si proporcionas optionalSeparator, se inserta entre los valores concatenados. De lo contrario, se usa el separador predeterminado ,. Fusiona valores en una cadena.

join(.event.issue.labels.*.name, ', ') puede devolver "bug, help wanted"

toJSON(value)

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

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

fromJSON(value)

Devuelve un objeto JSON o un tipo de datos JSON para value. Puedes usar esta función para proporcionar un objeto JSON como una expresión evaluada o convertir cualquier tipo de datos que se pueda representar en JSON o JavaScript, como cadenas, valores booleanos, valores NULL, matrices y objetos.

Este flujo de trabajo configura una matriz de JSON en un trabajo, y lo pasa al siguiente trabajo utilizando una salida y fromJSON.

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

Este flujo de trabajo usa fromJSON para convertir variables de entorno de una cadena a un valor booleano o entero.

name: print
on: push
env:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - continue-on-error: ${{ fromJSON(env.continue) }}
        timeout-minutes: ${{ fromJSON(env.time) }}
        run: echo ...

name: print
on: push
env:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - continue-on-error: ${{ fromJSON(env.continue) }}
        timeout-minutes: ${{ fromJSON(env.time) }}
        run: echo ...

El flujo de trabajo usa la función fromJSON() para convertir la variable de entorno continue de una cadena en un valor booleano, lo que le permite determinar si desea continuar con el error o no. Del mismo modo, convierte la variable de entorno time de una cadena en un entero y establece el tiempo de espera del trabajo en minutos.

hashFiles(path)

Devuelve un hash único para el conjunto de archivos que coincide con el patrón path. Puede proporcionar un único patrón path o varios patrones path separados por comas. path es relativo al directorio _WORKSPACE y solo puede incluir archivos dentro de _WORKSPACE. Esta función calcula un hash SHA-256 individual para cada archivo coincidente, y luego usa esos hashes para calcular un hash SHA-256 final para el conjunto de archivos. Si el patrón path no coincide con ningún archivo, devuelve una cadena vacía. Para obtener más información sobre SHA-256, consulta SHA-2.

Puedes usar caracteres de coincidencia de patrones para encontrar nombres de archivos. La coincidencia de patrones de hashFiles se ajusta a la coincidencia de patrones globales y no distingue mayúsculas de minúsculas en Windows. Para obtener más información sobre los caracteres de coincidencia de patrones admitidos, consulte la sección Patrones de la documentación de @actions/glob.

Coincide con cualquier archivo package-lock.json del repositorio.

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

Coincide con todos los archivos .js del directorio src en el nivel raíz, pero omite los subdirectorios de src.

hashFiles('/src/*.js')

Coincide con todos los archivos .rb del directorio lib en el nivel raíz, incluidos los subdirectorios de lib.

hashFiles('/lib/**/*.rb')

Crea un hash para todos los archivos package-lock.json y Gemfile.lock del repositorio.

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

Crea un hash para todos los archivos .rb del directorio lib en el nivel raíz, incluidos los subdirectorios de lib, pero sin incluir los archivos .rb del subdirectorio foo .

hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb')

Puedes usar las siguientes funciones de comprobación de estado como expresiones en condicionales if. Se aplica una comprobación de estado predeterminada de success() a menos que incluyas una de estas funciones. Para más información sobre los condicionales if, consulta Sintaxis del flujo de trabajo para Actions y Sintaxis de metadatos para Acciones de .

Devuelve true cuando todos los pasos anteriores se han realizado correctamente.

steps:
  ...
  - name: The job has succeeded
    if: ${{ success() }}

Hace que el paso siempre se ejecute y devuelve true, incluso cuando se cancela. La expresión always se usa mejor en el nivel de paso o en las tareas que se espera ejecutar incluso cuando se cancela un trabajo. Por ejemplo, puedes usar always para enviar registros incluso cuando se cancela un trabajo.

if: ${{ always() }}

Devuelve true si el flujo de trabajo se ha cancelado.

if: ${{ cancelled() }}

Devuelve true cuando se produce un error en cualquier paso anterior de un trabajo. Si tienes una cadena de trabajos dependientes, failure() devuelve true si se produce un error en algún trabajo antecesor.

steps:
  ...
  - name: The job has failed
    if: ${{ failure() }}

Puedes incluir condiciones adicionales para que un paso se ejecute después de un error, pero todavía debes incluir failure() para invalidar la comprobación de estado predeterminada de success() que se aplica automáticamente a las condiciones if que no contienen una función de comprobación de estado.

steps:
  ...
  - name: Failing step
    id: demo
    run: exit 1
  - name: The demo step has failed
    if: ${{ failure() && steps.demo.conclusion == 'failure' }}

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

Por ejemplo, considera una matriz de objetos denominada fruits.

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

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

También puedes usar la sintaxis * en un objeto. Por ejemplo, supongamos que tienes un objeto denominado vegetables.

{
  "scallions":
  {
    "colors": ["green", "white", "red"],
    "ediblePortions": ["roots", "stalks"],
  },
  "beets":
  {
    "colors": ["purple", "red", "gold", "white", "pink"],
    "ediblePortions": ["roots", "stems", "leaves"],
  },
  "artichokes":
  {
    "colors": ["green", "purple", "red", "black"],
    "ediblePortions": ["hearts", "stems", "leaves"],
  },
}

El filtro vegetables.*.ediblePortions podría evaluarse como:

[
  ["roots", "stalks"],
  ["hearts", "stems", "leaves"],
  ["roots", "stems", "leaves"],
]

Dado que los objetos no conservan el orden, no se puede garantizar el orden de la salida.