Exploración de contextos y expresiones en GitHub

  • 10 minutos

Los contextos son una manera de acceder a información acerca de las ejecuciones de flujo de trabajo, variable, entornos del ejecutor, trabajos y pasos. Cada contexto es un objeto que contiene propiedades, que pueden ser cadenas u otros objetos.

Puede acceder a los contextos mediante la sintaxis de expresión. Una expresión puede ser cualquier combinación de valores literales, referencias a un contexto o funciones. Puede combinar valores literales, referencias de contexto y funciones mediante operadores.

Contextos

Al crear flujos de trabajo y acciones, siempre debe tener en cuenta si el código podría ejecutar una entrada de posibles atacantes que no es de confianza. Se tratarán algunos contextos como una entrada no de confianza, ya que un atacante podrían insertar su propio contenido malintencionado. Para obtener más información, visite Protección de seguridad para acciones de GitHub".

La tabla siguiente contiene ejemplos de contextos disponibles en GitHub, no es una lista completa.

Nombre del contexto Tipo Descripción
github object Información sobre la ejecución del flujo de trabajo.
env object Contiene variables establecidas en un flujo de trabajo, trabajo o paso.
vars object Contiene variables establecidas a nivel de repositorio, organización o entorno.
job object Información sobre el trabajo que se está ejecutando actualmente.

Sugerencia

Para obtener una lista completa de contextos, visite Acerca de los contextos.

Determinar cuándo utilizar contextos

Acciones de GitHub incluyen dos colecciones de variables denominadas variables predeterminadas y contextos. Estas variables están pensadas para su uso en diferentes puntos del flujo de trabajo:

  • Variables de entorno predeterminadas: estas variables de entorno solo existen en el ejecutor que ejecuta el trabajo.
  • Contextos: puede usar la mayoría de los contextos en cualquier punto del flujo de trabajo, incluido cuando las variables predeterminadas no estarían disponibles.

En el ejemplo siguiente, la instrucción if comprueba el contexto github.ref para determinar el nombre de la rama actual. La if comprobación se procesa y el trabajo solo se envía al ejecutor si el resultado es true. Una vez que el trabajo se envía al ejecutor, se ejecuta el paso y hace referencia a la $GITHUB_REF variable del ejecutor.

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Contextos disponibles en Acciones de GitHub

La tabla siguiente contiene los contextos de nivel superior disponibles, una breve descripción y un vínculo para obtener más información sobre las propiedades del objeto.

Contexto de nivel superior Descripción Propiedades y ejemplos
github El contexto de nivel superior disponible durante cualquier trabajo o paso en un flujo de trabajo. Propiedades del github contexto.
env Contiene variables establecidas en un flujo de trabajo, trabajo o paso. No contiene variables heredadas por el proceso ejecutor. Propiedades del env contexto.
vars Contiene variables de configuración personalizadas establecidas en los niveles de organización, repositorio y entorno. Ejemplos de vars uso.
job Contiene información sobre el trabajo en ejecución. Propiedades del job contexto.
jobs Solo está disponible en flujos de trabajo reutilizables y solo se puede usar para establecer salidas para un flujo de trabajo reutilizable. Propiedades del jobs contexto.
steps Contiene información sobre los pasos completados en el trabajo actual que tienen un id especificado. Propiedades del steps contexto.
runner Contiene información sobre el ejecutor que ejecuta el trabajo actual. Propiedades del runner contexto.
secrets Contiene los nombres y valores de los secretos que están disponibles para una ejecución de flujo de trabajo. Propiedades del secrets contexto.
strategy Contiene información sobre la estrategia de ejecución de matriz para el trabajo actual. Propiedades del strategy contexto.
matrix Contiene las propiedades de matriz definidas en el archivo de flujo de trabajo que se aplican al trabajo actual. Propiedades del matrix contexto.
needs Contiene salidas de todos los trabajos definidos como una dependencia directa del trabajo actual. Propiedades del matrix contexto.
inputs Contiene las propiedades de entrada pasadas a una acción, a un flujo de trabajo reutilizable o a un flujo de trabajo desencadenado manualmente. Propiedades del inputs contexto.

Expresiones

Puede usar expresiones para establecer mediante programación variables de entorno 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. Puede combinar valores literales, referencias de contexto y funciones mediante operadores.

Las expresiones se usan normalmente con la palabra clave if condicional en un archivo de flujo de trabajo para determinar si se debe ejecutar un paso. Cuando un if condicional es true, se ejecuta el paso.

Debe usar una sintaxis específica, ${{ <expression> }}, para indicar a GitHub que evalúe una expresión en lugar de tratarla como una cadena. La excepción a esta regla es cuando se usan expresiones en una if cláusula , donde normalmente se pueden omitir ${{ y }}.

En el ejemplo de código siguiente se muestra cómo establecer una variable de entorno.

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

Literales

Como parte de una expresión, puede usar los tipos de datos boolean, null, number o string. En los condicionales, los valores falsos (false, 0, -0, "", '', null) se convierten a false y los valores verdaderos (true y otros valores no falsos) se convierten a true. A continuación se muestran ejemplos de implementación de literales.

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!' }}

Operadores

Los operadores desempeñan un papel fundamental en la evaluación de expresiones. Una expresión puede constar de valores literales, referencias a contextos o funciones. Los operadores permiten combinar estos elementos para crear expresiones más complejas. Estos son algunos operadores clave:

  • Operadores lógicos:

    • && (y): combina dos condiciones, ambas deben ser verdaderas para que la expresión general se evalúe como true.
    • || (o): combina dos condiciones, y la expresión se evalúa como verdadera si alguna condición es verdadera.
    • ! (no): niega una condición, voltea su valor verdadero.

  • Operadores de igualdad:

    • == (igual): compara dos valores para la igualdad.
    • != (no igual): comprueba si dos valores no son iguales.

  • Operadores de comparación:

    • < (menor que)
    • > (mayor que)
    • <= (menor o igual que)
    • >= (mayor o igual que)

Estos operadores permiten crear flujos de trabajo dinámicos mediante la determinación de cuándo se deben ejecutar pasos específicos en función de las condiciones. Recuerde usar la sintaxis correcta para las expresiones, como $\{\{ <expression> \}\}$, para garantizar la evaluación adecuada.

Para obtener más información sobre los operadores, visite Operadores.