Cómo usar las variables de entorno de GitHub Actions

Play Video: How to Use GitHub Actions Environment Variables and Secrets

Para mejorar la eficiencia al publicar código funcional en un entorno de producción, es una excelente práctica implementar un pipeline de integración continua y entrega continua (CI/CD). Estos pipelines automatizan la verificación de que un cambio de código está listo para publicarse y ofrecen herramientas para automatizar su lanzamiento en un entorno de producción.

Una forma popular de hacerlo es usar el sistema de control de versiones que ya tienes. GitHub es uno de los sistemas de control de versiones más populares y ofrece GitHub Actions, que permite a los desarrolladores compilar, probar e implementar código automáticamente, y ayuda a crear pipelines de CI/CD seguros.

Es común que los trabajos de GitHub Actions necesiten acceder a variables de entorno. Estas variables se pueden definir con anticipación y solo están disponibles para los pipelines que se ejecutan en ese entorno específico. Esto permite que los desarrolladores cambien el comportamiento del pipeline de CI/CD según las variables de entorno, por ejemplo, para compilar una versión optimizada de producción de la aplicación antes de implementarla en producción.

En este artículo práctico, analizamos las variables de entorno disponibles en GitHub Actions y cuándo conviene usarlas.

Requisitos previos

Para seguir este tutorial, necesitas lo siguiente:

• Acceso a una computadora con un editor de código (en este tutorial usamos Visual Studio Code) y una cuenta de GitHub.

• El código de ejemplo. Este código incluye una aplicación sencilla de Java que usaremos para mostrar cómo funcionan las variables de entorno.

¿Sabías que tenemos un complemento de Snyk para Visual Studio Code que te permite analizar tu proyecto mientras lo desarrollas? Consulta la documentación para obtener más información.

Qué puedes hacer con las variables de entorno de GitHub Actions

Cuando hayas descargado el código de ejemplo, crea un repositorio nuevo en GitHub y agrega el código de ejemplo.

El código de ejemplo ya incluye un archivo de flujo de trabajo de GitHub Actions. El fragmento de código de abajo muestra el contenido del archivo .github/workflows/pipeline.yml:

1name: Java CI with Maven
2
3on:
4  push:
5    branches: [ "main" ]
6  pull_request:
7    branches: [ "main" ]
8
9jobs:
10  build:
11
12    runs-on: ubuntu-latest
13
14    steps:
15    - uses: actions/checkout@v3
16    - name: Set up JDK 21
17      uses: actions/setup-java@v3
18      with:
19        java-version: '21'
20        distribution: 'temurin'
21        cache: maven
22    - name: Build with Maven
23      run: mvn -B package --file pom.xml

Este archivo define un flujo de trabajo sencillo para compilar nuestra aplicación de Java con Maven.

Podemos definir variables de entorno en el archivo de configuración YAML del flujo de trabajo en tres niveles: flujo de trabajo, trabajo y paso. Estos niveles determinan el alcance de las variables de entorno. El nivel del flujo de trabajo usa variables de entorno que se aplican a todo el flujo. El nivel del trabajo usa variables de entorno que se aplican a trabajos específicos. Las variables de entorno del paso se aplican a pasos específicos.

Veamos cada una de estas variables en detalle.

Variables de entorno del flujo de trabajo

Para configurar una variable de entorno a nivel del flujo de trabajo, debemos definirla en el nivel superior del archivo YAML. Agreguemos lo siguiente debajo de la variable NAME, al principio del archivo:

1env:
2  NAME: 'Snyk Demo'

Este código define una variable de entorno llamada NAME, a la que ahora podemos acceder desde cualquier parte del flujo de trabajo. Para acceder a esta variable, debemos usar una sintaxis específica, similar a la que se usa para acceder a las variables de entorno de UNIX. Para usar nuestra variable NAME, debemos anteponerle un signo de dólar y convertirla en $NAME.

Agreguemos un paso nuevo a nuestro flujo de trabajo en la línea 23 para imprimir esta variable:

1- name: Print name
2  run: echo "Hello $NAME"

Confirma y envía este cambio al repositorio.

Luego, abre GitHub en un navegador y ve a la pestaña Actions del repositorio. En Jobs, selecciona el flujo de trabajo más reciente y abre el resultado del trabajo de compilación. Haz clic en Print name. Al expandirlo, verás que la variable de entorno se imprimió correctamente, como se muestra en la imagen de abajo.

Las variables de entorno del flujo de trabajo son útiles para declarar variables que se aplican a todos los trabajos y pasos. Por ejemplo, podemos usarlas para establecer el tipo de entorno en el que se ejecuta el flujo de trabajo: desarrollo, pruebas o producción. Esto puede ser útil para aplicaciones de Node compiladas con npm, ya que pueden usar la variable NODE_ENV. Con esta variable, cada trabajo puede comportarse según el entorno específico. Obtén más información sobre cómo publicar tus paquetes npm de forma segura en este artículo del blog de Snyk.

Variables de entorno del trabajo

Ahora veamos cómo configurar las variables de entorno de los trabajos y los pasos. Se configuran igual que las variables de entorno del flujo de trabajo, pero se definen en la sección correspondiente.

Para la variable del trabajo, queremos definir la versión de Java de la siguiente manera:

1jobs:
2  build:
3    env:
4        JAVA_VERSION: '21'

Ahora podemos usar esta variable en nuestros pasos, como hicimos antes.

1steps:
2- uses: actions/checkout@v3
3- name: Set up JDK ${{env.JAVA_VERSION}}
4  uses: actions/setup-java@v3
5  with:
6    java-version: ${{env.JAVA_VERSION}}
7    distribution: 'temurin'
8    cache: maven

Sin embargo, quizá notes que la sintaxis es un poco diferente cuando usamos nuestra variable de entorno JAVA_VERSION. Este es un ejemplo del uso de contextos para acceder a una variable de entorno. Los contextos permiten que GitHub Actions use nuestras variables de entorno en cualquier máquina virtual, ya que estas tareas no siempre se ejecutan en la misma máquina virtual donde declaramos el entorno.

Puedes usar variables de entorno del trabajo para reemplazar una variable del flujo de trabajo cuando un trabajo específico requiere un valor distinto del que ya se declaró, o para limitar el alcance de la variable a un solo trabajo.

Como se muestra en el ejemplo anterior, podemos usar variables de entorno del trabajo para establecer la versión de Java y así utilizar la variable en cada paso. Si en el futuro queremos usar otra versión de Java, solo tenemos que cambiarla en un lugar y todos los pasos del trabajo usarán automáticamente la nueva versión.

Como ya estás trabajando en una acción de GitHub, puedes integrar Snyk fácilmente en GitHub Actions y analizar tu proyecto de inmediato. Para tu comodidad, tenemos acciones de GitHub de Snyk listas para usar. Así que, si todavía no tienes una, crea una cuenta de Snyk y integra el análisis hoy mismo.

Variables de entorno del paso

También podemos definir variables dentro de un paso. A continuación se muestra un ejemplo de variable de entorno del paso. Modifica el paso Print name del archivo pipeline.yml para que coincida con el fragmento de código de abajo:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
3  env:
4    BUILD: 'We are currently running the Build job'

Las variables de entorno del paso limitan el alcance a un solo paso. Esto es útil para tareas como definir rutas de archivos de entrada o salida específicas de un paso. En el código de ejemplo anterior, usamos la variable del paso para establecer el texto que se imprimirá.

A continuación se muestra un ejemplo del archivo YAML completo del flujo de trabajo de GitHub, con las nuevas variables de entorno del trabajo y del paso:

1name: Java CI with Maven
2
3env:
4  NAME: 'Snyk Demo'
5
6on:
7  push:
8    branches: [ "main" ]
9  pull_request:
10    branches: [ "main" ]
11
12jobs:
13  build:
14    env:
15        JAVA_VERSION: '21'
16
17    runs-on: ubuntu-latest
18
19    steps:
20    - uses: actions/checkout@v3
21    - name: Set up JDK ${{env.JAVA_VERSION}}
22      uses: actions/setup-java@v3
23      with:
24        java-version: ${{env.JAVA_VERSION}}
25        distribution: 'temurin'
26        cache: maven
27    - name: Build with Maven
28      run: mvn -B package --file pom.xml
29    - name: Print name
30      run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
31      env:
32        BUILD: 'We are currently running the Build job'

Confirma este nuevo flujo de trabajo en GitHub y revisa el resultado, que debería verse como la imagen de abajo.

Configuramos nuestra variable de entorno mediante contextos y el paso de impresión funciona según lo esperado.

Si intentáramos usar nuestra variable de entorno sin contextos, recibiríamos el siguiente error:

Esto se debe a que setup-java action no tiene acceso al mismo entorno, por lo que se necesitan contextos para que la variable esté disponible.

Uso de variables predeterminadas y secretos de GitHub

Además de definir nuestras variables de entorno, GitHub proporciona algunas variables predeterminadas a las que puedes acceder desde un flujo de trabajo. Estas variables nos dan acceso a datos como el repositorio de GitHub, la acción de GitHub y el ejecutor del flujo de trabajo. Puedes usarlas igual que las variables de entorno definidas por el usuario. Cuando corresponda, debes acceder a ellas mediante contextos en GitHub Actions.

El último tipo de variable de entorno son los secretos de GitHub. Puedes usarlos para variables que contienen datos confidenciales, ya que GitHub los cifra y los pone a disposición del flujo de trabajo.

Puedes crear variables de entorno cifradas en GitHub desde la sección Settings del repositorio. Selecciona Secrets and variables y luego Actions en el menú de la izquierda. Después, haz clic en New repository secret e ingresa un nombre y un valor para el secreto. Crea un secreto llamado API_KEY y asígnale un valor aleatorio, como se muestra abajo.

Para usar el secreto en el flujo de trabajo, usamos la misma sintaxis que al proporcionar variables de entorno a GitHub Actions mediante contextos. Sin embargo, en lugar de anteponer env. a la variable, usamos secrets..

1${{secrets.API_KEY}}

Agrega ${{secrets.API_KEY}} a la instrucción de impresión que ya creamos en el archivo YAML del flujo de trabajo. Debería coincidir con el fragmento de código de abajo:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION. My API_KEY is ${{secrets.API_KEY}}"
3  env:
4    BUILD: 'We are currently running the Build job'

Confirma los cambios y envíalos al repositorio. Luego, ve a la página Actions de GitHub para ver el resultado de la ejecución más reciente del flujo de trabajo.

Como podemos ver, GitHub oculta automáticamente el valor de nuestro secreto cifrado para que no lo expongamos por accidente.

Los secretos de GitHub ayudan a almacenar datos confidenciales, como contraseñas o claves de autorización de API. Al usar secretos, no tenemos que incluir estos valores directamente en el flujo de trabajo y arriesgarnos a exponerlos a terceros. En su lugar, GitHub los cifra, los transmite de forma segura a las acciones del flujo de trabajo y evita que aparezcan en texto sin formato en los registros.

Conclusión

En este artículo explicamos las variables de entorno de GitHub Actions. Analizamos los tres alcances disponibles para las variables de entorno (flujo de trabajo, trabajo y paso), y cómo definir variables en cada uno. Luego vimos cómo usar contextos para pasar variables de entorno a GitHub Actions y cómo usar secretos para cifrar variables confidenciales.

Las variables de entorno de GitHub Actions permiten a los desarrolladores crear flujos de trabajo dinámicos. Podemos usar estas variables para cambiar el comportamiento del flujo de trabajo según una variable definida por el usuario o una variable predeterminada de GitHub. Debemos usar variables cuando queramos cambiar dinámicamente el funcionamiento del flujo de trabajo o de un trabajo o paso específico, así como las condiciones en que se ejecutan.

El artículo también explicó cómo usar secretos de GitHub como variables de entorno para proteger información confidencial. Es importante recordar que debes usar secretos de GitHub para variables confidenciales, como contraseñas y claves de API, ya que GitHub las cifra y las incorpora al flujo de trabajo sin riesgo de exponerlas.

Y recuerda: ¡la seguridad importa! Descubre cómo Snyk puede agregar una capa adicional de seguridad a tus flujos de trabajo de GitHub y obtén más información sobre cómo integrar Snyk en tu pipeline de CI/CD para proteger de forma integral el código, los contenedores, el código abierto y la infraestructura como código (IaC).