Personalización del flujo de trabajo con variables de entorno

Completado

En esta unidad, aprenderá a configurar y administrar el comportamiento específico del entorno mediante variables, contextos y scripts personalizados en flujos de trabajo de Acciones de GitHub.

Para implementar este proceso, aprenderá a:

• Use variables de entorno predeterminadas y personalizadas.
• Acceso a información contextual en flujos de trabajo.
• Establezca variables de entorno en distintos ámbitos de flujo de trabajo.
• Uso de scripts personalizados con la palabra clave ejecutar.
• Aplicar protecciones de entorno para implementaciones.

Variables de entorno y contextos predeterminados

Dentro del flujo de trabajo de Acciones de GitHub, hay varias variables de entorno predeterminadas disponibles para su uso, pero solo dentro del ejecutor que ejecuta un trabajo. Estas variables predeterminadas distinguen mayúsculas de minúsculas y hacen referencia a los valores de configuración del sistema y al usuario actual. Se recomienda usar estas variables de entorno predeterminadas para hacer referencia al sistema de archivos en lugar de usar rutas de acceso de archivo codificadas de forma rígida. Para usar una variable de entorno predeterminada, especifique $ seguido del nombre de la variable de entorno.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Además de las variables de entorno predeterminadas, puede usar variables definidas como contextos. Los contextos y las variables predeterminadas son similares, ya que proporcionan acceso a la información del entorno, pero tienen algunas diferencias importantes. Aunque las variables de entorno predeterminadas solo se pueden usar dentro del ejecutor, puede usar variables de contexto en cualquier punto del flujo de trabajo. Por ejemplo, las variables de contexto permiten ejecutar una instrucción if para evaluar una expresión antes de ejecutar el 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"

En este ejemplo se usa el contexto github.ref para comprobar la rama que ha desencadenado el flujo de trabajo. Si la rama es main, el ejecutor se ejecuta e imprime "Implementación en el servidor de producción en la rama $GITHUB_REF". La variable $GITHUB_REF de entorno predeterminada se usa en el ejecutor para hacer referencia a la rama. Tenga en cuenta que las variables de entorno predeterminadas están en mayúsculas, mientras que las variables de contexto están en minúsculas.

Información contextual disponible en un flujo de trabajo

Use contextos para acceder a información sobre ejecuciones de flujo de trabajo, variables, entornos de ejecutor, trabajos y pasos. Cada contexto es un objeto que contiene propiedades que pueden ser otros objetos o cadenas. Los contextos disponibles incluyen github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs y inputs.

En la tabla siguiente se enumeran los contextos y descripciones del flujo de trabajo:

Contexto	Descripción
github	Información sobre la ejecución del flujo de trabajo. Para obtener más información, consulte githubcontexto.
env	Contiene variables que se establecen en un flujo de trabajo, un trabajo o un paso. Para obtener más información, consulte envcontexto.
vars	Contiene variables que se establecen en el nivel de repositorio, organización o entorno. Para obtener más información, consulte varscontexto.
job	Información sobre el trabajo que se está ejecutando actualmente. Para obtener más información, consulte jobcontexto.
jobs	Solo para flujos de trabajo reutilizables, contiene salidas de trabajos del flujo de trabajo reutilizable. Para obtener más información, consulte jobscontexto.
steps	Información sobre los pasos que se ejecutaron en el trabajo actual. Para obtener más información, consulte stepscontexto.
runner	Información sobre el ejecutor que ejecuta el trabajo actual. Para obtener más información, consulte runnercontexto.
secrets	Contiene los nombres y valores de los secretos que están disponibles para una ejecución de flujo de trabajo. Para obtener más información, consulte secretscontexto.
strategy	Información sobre la estrategia de ejecución de matriz para el trabajo actual. Para obtener más información, consulte strategycontexto.
matrix	Contiene las propiedades de matriz definidas en el flujo de trabajo que se aplican al trabajo actual. Para obtener más información, consulte matrixcontexto.
needs	Contiene las salidas de todos los trabajos que se definen como una dependencia del trabajo actual. Para obtener más información, consulte needscontexto.
inputs	Contiene las entradas de un flujo de trabajo reutilizable o desencadenado manualmente. Para obtener más información, consulte inputscontexto.

Hay diferentes contextos disponibles en momentos diferentes en una ejecución de flujo de trabajo. Por ejemplo, puede usar el contexto secrets solo en lugares específicos de una tarea. Además, puede usar algunas funciones, como la hashFiles función , solo en lugares específicos.

En la tabla siguiente se enumeran las restricciones de cada contexto y función especial en un flujo de trabajo. Los contextos enumerados solo están disponibles para la clave de flujo de trabajo indicada. No se pueden usar en ningún otro lugar. Puede usar una función en cualquier lugar a menos que se muestre en la tabla siguiente.

Clave de flujo de trabajo	Contexto	Funciones especiales
run-name	github, , inputs, vars	Ninguno
concurrency	github, , inputs, vars	Ninguno
env	github, secrets, , inputs, vars	Ninguno
jobs.<job_id>.concurrency	github, needs, strategy, matrix, , inputs, vars	Ninguno
jobs.<job_id>.container	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.container.credentials	github, needs, strategy, matrix, env, vars, , secretsinputs	Ninguno
jobs.<job_id>.container.env.<env_id>	github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Ninguno
jobs.<job_id>.container.image	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.continue-on-error	github, needs, strategy, vars, , matrix, inputs	Ninguno
jobs.<job_id>.defaults.run	github, needs, strategy, matrix, env, , varsinputs	Ninguno
jobs.<job_id>.env	github, needs, strategy, matrix, vars, , secretsinputs	Ninguno
jobs.<job_id>.environment	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.environment.url	github, needs, strategy, matrix, job, runner, env, vars, steps, inputs	Ninguno
jobs.<job_id>.if	github, needs, , vars, inputs	always, canceled, , success, failure
jobs.<job_id>.name	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.outputs.<output_id>	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	Ninguno
jobs.<job_id>.runs-on	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.secrets.<secrets_id>	github, needs, strategy, matrix, secrets, , inputsvars	Ninguno
jobs.<job_id>.services	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.services.<service_id>.credentials	github, needs, strategy, matrix, env, vars, , secretsinputs	Ninguno
jobs.<job_id>.services.<service_id>.env.<env_id>	github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Ninguno
jobs.<job_id>.steps.continue-on-error	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.env	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.if	github, needs, strategy, matrix, job, runner, env, vars, steps, inputs	always, , canceled, success, failure, hashFiles
jobs.<job_id>.steps.name	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.run	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	** github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.with	github, needs, strategy, matrix, job, env, runner, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.steps.working-directory	github, needs, strategy, matrix, job, env, runner, vars, secrets, steps, inputs	hashFiles
jobs.<job_id>.strategy	github, necesidades, vars, inputs,	Ninguno
jobs.<job_id>.timeout-minutes	github, needs, strategy, matrix, , vars, inputs	Ninguno
jobs.<job_id>.with.<with_id>	github, needs, strategy, matrix, , inputs, vars	Ninguno
on.workflow_call.inputs.<inputs_id>.default	github, , inputs, vars	Ninguno
on.workflow_call.outputs.<output_id>.value	github, trabajos, vars, inputs	Ninguno

Variables de entorno personalizadas

De forma similar al uso de variables de entorno predeterminadas, en el archivo de flujo de trabajo puede utilizar variables de entorno personalizadas. Para crear una variable personalizada, debe definirla en el archivo de flujo de trabajo mediante el contexto env. Si quiere usar el valor de una variable de entorno dentro de un ejecutor, puede utilizar el método normal del sistema operativo del ejecutor para leer variables de entorno.

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

Establecimiento de variables de entorno personalizadas en un flujo de trabajo

Puede definir variables de entorno cuyo ámbito sea todo el flujo de trabajo mediante el uso env en el nivel superior del archivo de flujo de trabajo. Determinar el alcance del contenido de un trabajo dentro de un flujo de trabajo usando jobs.<job_id>.env. Puede definir el ámbito de una variable de entorno en un paso específico dentro de un trabajo mediante jobs.<job_id>.steps[*].env.

Este es un ejemplo que muestra los tres escenarios de un archivo de flujo de trabajo:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Uso de un contexto predeterminado en un flujo de trabajo

La plataforma de GitHub establece variables de entorno predeterminadas. No se definen en un flujo de trabajo, pero puede usar una variable de entorno predeterminada en un flujo de trabajo en el contexto adecuado. La mayoría de estas variables, excepto CI, comienzan por GITHUB_* o RUNNER_*. Los dos últimos tipos no se pueden sobrescribir. Además, estas variables predeterminadas tienen una propiedad de contexto correspondiente y con un nombre similar. Por ejemplo, la RUNNER_* serie de variables predeterminadas tiene una propiedad de contexto coincidente de runner.*.

Este es un ejemplo de cómo acceder a variables predeterminadas en un flujo de trabajo aplicando estos métodos:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Para obtener más información, consulte Variables de entorno predeterminadas.

Pasar variables de entorno personalizadas a un flujo de trabajo

Puede pasar variables de entorno personalizadas desde una etapa de un trabajo de flujo de trabajo a las etapas posteriores dentro del trabajo. Genere un valor en un paso de un trabajo y asigne el valor a una variable de entorno existente o nueva. A continuación, escriba el par variable/valor en el archivo de entorno de GITHUB_ENV. Puede usar el archivo de entorno en una acción o desde un comando de shell en el trabajo del flujo de trabajo mediante la palabra clave run.

El paso que crea o actualiza la variable de entorno no tiene acceso al nuevo valor, pero todos los pasos posteriores de un trabajo tienen acceso.

Este es un ejemplo:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Adición de protecciones de entorno

Puede agregar reglas de protección para entornos definidos para el repositorio de GitHub.

Para agregar un entorno en el repositorio:

1. Haga clic en Configuración.

   

2. En el panel izquierdo, seleccione Entorno.

   

3. Seleccione el botón Nuevo entorno para agregar y configurar un entorno y agregar protecciones.

   

Acerca de los entornos

Use entornos para describir un destino de implementación general, como producción, ensayo o desarrollo. Cuando se implementa un flujo de trabajo de Acciones de GitHub en un entorno, el entorno aparece en la página principal del repositorio. Puede usar entornos para requerir la aprobación de un trabajo para continuar, restringir qué ramas pueden desencadenar un flujo de trabajo, controlar las implementaciones mediante reglas de protección de implementación personalizadas o limitar el acceso a secretos.

Cada trabajo de un flujo de trabajo puede hacer referencia a un entorno. Las reglas de protección que establezca para el entorno deben pasar antes de que se envíe un trabajo que haga referencia al entorno a un ejecutor. El trabajo puede acceder a los secretos del entorno solo después de enviar el trabajo a un ejecutor.

Cuando un flujo de trabajo hace referencia a un entorno, el entorno aparece en las implementaciones del repositorio.

Reglas de protección del entorno

Las reglas de protección de implementación del entorno requieren condiciones específicas para pasar antes de que continúe un trabajo que haga referencia al entorno. Puede usar reglas de protección de implementación para requerir una aprobación manual, retrasar un trabajo o restringir el entorno a ramas específicas. También puede crear e implementar reglas de protección personalizadas con tecnología de Aplicaciones de GitHub para usar sistemas asociados para controlar las implementaciones que hacen referencia a entornos configurados en GitHub.

Esta es una explicación de estas reglas de protección:

• Reglas de protección de revisores necesarias. Use esta regla para requerir que una persona o equipo específico apruebe los trabajos de flujo de trabajo que hacen referencia al entorno. Puede enumerar hasta seis usuarios o equipos como revisores. Los revisores deben tener al menos permisos de lectura en el repositorio. Solo un revisor necesario debe aprobar el trabajo para que continúe.

  También puede evitar revisiones automáticas para implementaciones en un entorno protegido. Si habilita esta configuración, los usuarios que inician una implementación no pueden aprobar el trabajo de implementación, incluso si son un revisor necesario. Al habilitar las revisiones automáticas, garantiza que más de una persona revise las implementaciones en entornos protegidos.

  Para obtener más información sobre cómo revisar los trabajos que hacen referencia a un entorno con revisores necesarios, consulte Revisión de las implementaciones.

• Reglas de proyección del temporizador de espera. Puede usar una regla de protección del temporizador de espera para retrasar un trabajo durante un período de tiempo específico después de que el trabajo se desencadene inicialmente antes de que continúe la implementación del entorno. El tiempo (en minutos) debe ser un entero entre 1 y 43.200 (30 días). El tiempo de espera no cuenta para el tiempo facturable.

• Reglas de protección de ramas y etiquetas. Puede usar reglas de protección de etiquetas y rama de implementación para restringir qué ramas y etiquetas se usan para implementar en el entorno. Tiene varias opciones para las reglas de protección de etiquetas y rama de implementación para un entorno.

  • Ninguna restricción establece ninguna restricción en qué rama o etiqueta se puede implementar en el entorno.
  • Solo ramas protegidas permiten que solo las ramas con reglas de protección habilitadas puedan implementarse en el entorno. Si no se definen reglas de protección de rama para ninguna rama del repositorio, todas las ramas se pueden implementar. La configuración Ramas y etiquetas seleccionadas garantiza que solo las ramas y etiquetas que coincidan con los patrones de nombre especificados pueden implementarse en el entorno.
  • Si especifica releases/* como una rama de implementación o una regla de etiquetas, solo una rama o etiqueta con un nombre que comience por releases/ puede implementarse en el entorno. (Los caracteres comodín no coinciden con /. Para buscar coincidencias con ramas o etiquetas que comienzan por release/ y contienen otra barra diagonal única, use release/*/*). Si agrega main como regla de rama, una rama denominada main también se puede implementar en el entorno.

• Reglas de protección de implementación personalizadas. Puede crear reglas de protección personalizadas para restringir los despliegues y usar servicios de socios. Por ejemplo, puede usar sistemas de observabilidad, sistemas de administración de cambios, sistemas de calidad de código u otras configuraciones manuales que use para evaluar la preparación y proporcionar aprobaciones automatizadas para las implementaciones en GitHub.

  Después de crear reglas de protección de implementación personalizadas e instalarlas en un repositorio, puede habilitar la regla de protección de implementación personalizada para cualquier entorno del repositorio.

  

Nota:

Si tiene un plan de GitHub Free, GitHub Pro o GitHub Team, las reglas de proyección de implementación del entorno solo están disponibles para repositorios públicos; excepto para las reglas de protección de ramas y etiquetas. Para los usuarios que tienen planes de GitHub Pro o GitHub Team, las reglas de protección de ramas y etiquetas también están disponibles para repositorios privados.

Scripts en el flujo de trabajo

En los ejemplos de fragmentos de flujo de trabajo anteriores, se usa la palabra clave run para imprimir una cadena de texto. Como la palabra clave run indica al trabajo que ejecute un comando en el ejecutor, se usa la palabra clave run para ejecutar acciones o scripts.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

En este ejemplo, se usa npm para instalar el bats paquete de pruebas de software mediante la run palabra clave . También puede ejecutar un script como una acción. Puede almacenar el script en el repositorio, normalmente en un directorio .github/scripts/ y, después, proporcionar la ruta de acceso y el tipo de shell mediante la palabra clave run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash