Sintaxis de contextos y expresiones para acciones de GitHub
Puedes acceder a la información de contexto y evaluar las expresiones en flujos de trabajo y acciones.
Acciones de GitHub is available with GitHub gratis, GitHub Pro, Equipo de GitHub, and Nube de GitHub Enterprise. Acciones de GitHub is unavailable for per-repository plans, which are legacy billing plans. For more information, see "GitHub's products."
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
- Leer más
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.
Expressions are commonly used with the conditional if
keyword in a workflow file to determine whether a step should run. 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> }}
When you use expressions in an if
conditional, you do not need to use the expression syntax ({{ }}
) because GitHub automatically evaluates the if
conditional as an expression. 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
Los contextos son una manera de acceder a información acerca de una ejecución de flujo de trabajo, entorno virtual, trabajos y pasos. Los contextos usan la sintaxis de expresión.
{{ <context> }}
Nombre del contexto | Tipo | Descripción |
---|---|---|
github |
objeto |
Información sobre la ejecución del flujo de trabajo. Para obtener más información, consulta github context. |
env |
string |
A step, job, or workflow environment variable. |
job |
objeto |
Información sobre el trabajo actualmente en ejecución. Para obtener más información, consulta job context. |
steps |
objeto |
Información sobre los pasos que se han ejecutado en este trabajo. Para obtener más información, consulta steps context. |
runner |
objeto |
Incluye información sobre el ejecutador que está realizando el trabajo actual. For more information, see runner context. |
secrets |
objeto |
Permite el acceso a los secretos establecidos en un repositorio. Para obtener más información sobre secretos, consulta "Entornos virtuales para Acciones de GitHub". |
estrategia |
objeto |
Brinda acceso a los parámetros de estrategia configurados y la información sobre el puesto actual. Los parámetros de estregia incluyen fail-fast , job-index , job-total y max-parallel . |
matriz |
objeto |
Brinda acceso a los parámetros de la matriz que configuraste para el puesto actual. Por ejemplo, si configuraste una matriz de construcción con las versiones os y nodo , el objeto de contexto de la matriz incluye las versiones os y nodo del puesto actual. |
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 de 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 obtener más información sobre las variables del entorno, consulta "Entornos virtuales para Acciones de GitHub".
Nombre de la propiedad | Tipo | Descripción |
---|---|---|
github |
objeto |
El contexto de nivel superior disponible durante cualquier trabajo o paso en un flujo de trabajo. |
github.event |
objeto |
La carga de webhook del evento completo. Para obtener más información, consulta "Eventos que activan los flujos de trabajo". |
github.workflow |
string |
El nombre del flujo de trabajo. Si el archivo de flujo de trabajo no especifica un nombre , el valor de esta propiedad es la ruta completa del archivo del flujo de trabajo en el repositorio. |
github.actor |
string |
El inicio de sesión del usuario que inició la ejecución del flujo de trabajo. |
github.repository |
string |
El nombre del repositorio y del propietario. Por ejemplo, Codertocat/Hello-World . |
github.event_name |
string |
El nombre del evento que activó la ejecución del flujo de trabajo. |
github.sha |
string |
El SHA de confirmación que activó la ejecución del flujo de trabajo. |
github.ref |
string |
La rama o ref de etiqueta que activó la ejecución del flujo de trabajo. |
github.head_ref |
string |
La rama head_ref o fuente de la solicitud de extracción en una ejecución de flujo de trabajo. Esta propiedad solo está disponible cuando el evento que activa una ejecución de flujo de trabajo es una pull_request . |
github.base_ref |
string |
La rama head_ref o fuente de la solicitud de extracción en una ejecución de flujo de trabajo. Esta propiedad solo está disponible cuando el evento que activa una ejecución de flujo de trabajo es una pull_request . |
contexto de job
El contexto trabajo
contiene información sobre el trabajo de ejecución actual.
Nombre de la propiedad | Tipo | Descripción |
---|---|---|
job |
objeto |
Este contexto cambia para cada trabajo en una ejecución de flujo de trabajo. Puedes acceder a este contexto desde cualquier paso en un trabajo. |
job.status |
string |
El estado actual del trabajo. Los valores posibles son success , failure o cancelled . |
job.container |
objeto |
Información sobre el contenedor del trabajo. Para obtener más información sobre los contenedores, consulta "Sintaxis de flujo de trabajo para Acciones de GitHub". |
job.container.network |
string |
La Id de la red del contenedor. El ejecutor crea la red usada por todos los contenedores en un trabajo. |
job.container.id |
string |
La Id de la red del contenedor. |
job.services |
objeto |
Los contenedores de servicio creados para un trabajo. Para obtener más información sobre los contenedores de servicio, consulta "Sintaxis de flujo de trabajo para Acciones de GitHub". |
job.services.network |
string |
La Id de la red del contenedor de servicio. El ejecutor crea la red usada por todos los contenedores en un trabajo. |
job.services.<service id>.id |
string |
La Id del contenedor de servicio. |
job.services.<service id>.ports |
objeto |
Los puertos expuestos del contenedor. |
contexto de steps
El contexto steps
contiene información sobre los pasos en el trabajo actual que ya se ha ejecutado.
Nombre de la propiedad | Tipo | Descripción |
---|---|---|
steps |
objeto |
Este contexto cambia para cada paso en un trabajo. Puedes acceder a este contexto desde cualquier paso en un trabajo. |
steps.<step id>.outputs |
objeto |
El conjunto de salidas definido para el paso. Para obtener más información, consulta "Sintaxis de metadatos para Acciones de GitHub". |
steps.<step id>.outputs.<output name> |
string |
El valor de un resultado específico. |
runner
context
The runner
context contains information about the runner that is executing the current job.
Nombre de la propiedad | Tipo | Descripción |
---|---|---|
os |
string |
The operating system of the runner executing the job. Possible values are Linux , Windows , or macOS . |
temp |
string |
The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. |
tool_cache |
string |
The path of the directory containing some of the preinstalled tools for GitHub-hosted runners. For more information, see "Software installed on GitHub-hosted runners." |
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
.
Tipo de datos | Valor literal |
---|---|
boolean |
true o falso |
null |
null |
number |
Cualquier formato de número compatible con JSON. |
string |
Debes usar comillas simples. Escapar comillas simples literales con una comilla simple. |
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
Operador | Descripción |
---|---|
( ) |
Agrupación lógica |
[ ] |
Índice |
. |
Desreferencia de propiedad |
! |
No |
< |
Menos que |
< |
Menor o igual |
> |
Mayor que |
>= |
Mayor o igual |
== |
Igual |
!= |
No es igual |
&& |
Y |
|| |
O |
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
devuelve1
falso
devuelve0
Cadena Analizado desde cualquier formato de número JSON legal, de lo contrario NaN
.
Nota: la cadena vacía devuelve0
.Array NaN
Object NaN
-
Una comparación de un
NaN
a otroNaN
no resulta entrue
. 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:
Tipo | Resultado |
---|---|
Null | '' |
Boolean | 'verdadero' o 'falso' |
Number | Formato decimal, exponencial para grandes números |
Array | Las matrices no se convierten en cadenas |
Object | Los objetos no se convierten en cadenas |
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')
regresa a 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)
Returns a single hash for the set of files that matches the path
pattern. The path
is relative to the GITHUB_WORKSPACE
directory and can only include files inside of the GITHUB_WORKSPACE
. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "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" ]