Configuración de Proxy en GitHub Actions y CI/CD

La configuración de proxy en GitHub Actions y CI/CD implica configurar variables de entorno de proxy estándar como HTTP_PROXY, HTTPS_PROXY y NO_PROXY dentro de la definición de su flujo de trabajo, típicamente a nivel de trabajo o paso. Esto permite que las acciones, scripts y herramientas ejecutadas dentro del pipeline de CI/CD enruten su tráfico de red a través de un servidor proxy especificado.

Las organizaciones a menudo implementan servidores proxy para controlar el acceso saliente a la red, aplicar políticas de seguridad, filtrar contenido y almacenar en caché recursos de acceso frecuente. Para los pipelines de CI/CD que operan en dichos entornos, configurar los ajustes del proxy es esencial para permitir que las herramientas de compilación, los gestores de dependencias y los scripts de prueba accedan a servicios externos, repositorios de paquetes o APIs. Los ejecutores de GitHub Actions, particularmente los ejecutores autohospedados, pueden requerir configuración de proxy para acceder a GitHub mismo o a otros recursos de internet.

Configuración de variables de entorno de proxy

El método más común y universalmente reconocido para configurar un proxy en un entorno basado en Linux (que utilizan principalmente los ejecutores alojados en GitHub) es a través de variables de entorno.

• HTTP_PROXY: Especifica el servidor proxy para solicitudes HTTP.
• HTTPS_PROXY: Especifica el servidor proxy para solicitudes HTTPS.
• NO_PROXY: Una lista separada por comas de nombres de host, dominios o direcciones IP que deben omitir el proxy. Esto es crítico para acceder directamente a recursos internos.

El formato para HTTP_PROXY y HTTPS_PROXY es típicamente http://[user:password@]host:port.
Tanto las versiones en mayúsculas (HTTP_PROXY) como en minúsculas (http_proxy) de estas variables suelen ser respetadas por varias herramientas; usar mayúsculas es una práctica estándar para las variables de entorno.

Configuración de proxy a nivel de flujo de trabajo

Aplicar la configuración del proxy a nivel de trabajo asegura que todos los pasos dentro de ese trabajo hereden la configuración.

name: CI con Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

Configuración de proxy a nivel de paso

Para escenarios que requieren diferentes configuraciones de proxy para pasos específicos, o para anular configuraciones a nivel de trabajo, las variables de entorno se pueden definir a nivel de paso.

name: CI con Proxy de Paso Específico
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Default proxy for the job (if any)
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

Autenticación de proxy con secretos

Si su proxy requiere autenticación, incluya el nombre de usuario y la contraseña directamente en la URL del proxy. Por seguridad, almacene las credenciales como secretos de GitHub Actions y reférencialas en el flujo de trabajo.

Primero, cree secretos de repositorio (por ejemplo, PROXY_USER, PROXY_PASS) en la configuración de su repositorio de GitHub.

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # or curl, etc.

Herramientas comunes e interacción con el proxy

Aunque HTTP_PROXY y HTTPS_PROXY son ampliamente respetados, algunas herramientas ofrecen métodos de configuración específicos.

Comandos git

git generalmente respeta HTTP_PROXY y HTTPS_PROXY para operaciones remotas. Para una configuración explícita o en casos donde las variables de entorno son insuficientes, se puede usar git config.

# Set proxy for HTTP and HTTPS git operations
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Configure a specific proxy for a particular remote
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

Los gestores de paquetes de Node.js como npm y yarn respetan las variables de entorno HTTP_PROXY y HTTPS_PROXY. También proporcionan sus propios comandos de configuración para ajustes persistentes.

# Using npm config
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# Using yarn config
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker (Compilación de imagen y tiempo de ejecución de contenedor)

La configuración del proxy para Docker requiere un manejo específico tanto para el tiempo de compilación de la imagen como para el tiempo de ejecución del contenedor.

Proxy en tiempo de compilación de Docker

Para los comandos ejecutados durante un docker build (por ejemplo, RUN apk add, RUN apt-get update), la configuración del proxy debe pasarse como argumentos de compilación.

Ejemplo de Dockerfile:

FROM alpine:latest

# Define build arguments for proxy settings
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Set environment variables for subsequent RUN commands
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Example: Use proxy for package installation
RUN apk add --no-cache curl

# ... rest of your Dockerfile

Paso del flujo de trabajo de GitHub Actions:

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Proxy en tiempo de ejecución del contenedor Docker

Si su flujo de trabajo ejecuta un contenedor Docker (por ejemplo, usando la clave container: o docker run), la configuración del proxy debe pasarse como variables de entorno al contenedor.

Usando la clave container::

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

Usando docker run en un paso:

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Aplicaciones Java (Maven, Gradle)

Las aplicaciones Java, incluidas las herramientas de compilación como Maven y Gradle, suelen requerir que la configuración del proxy se pase como propiedades del sistema Java. Esto se hace comúnmente a través de las variables de entorno MAVEN_OPTS o _JAVA_OPTIONS.

# For Maven
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# For Gradle (also applies to other JVM-based tools)
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

Alternativamente, Maven se puede configurar a través de ~/.m2/settings.xml, y Gradle a través de gradle.properties en el directorio del proyecto o del usuario.

Solución de problemas de proxy

• Verificar variables de entorno: Use run: env | grep -i proxy en un paso para confirmar que las variables de entorno del proxy están configuradas correctamente y son visibles para el shell del ejecutor.
• Verificar NO_PROXY: Asegúrese de que cualquier host interno o dominio de GitHub esté correctamente listado en NO_PROXY para evitar un proxy innecesario o problemas de enrutamiento.
• Registros del servidor proxy: Si es posible, revise los registros del servidor proxy en busca de intentos de conexión desde la dirección IP del ejecutor de GitHub Actions. Esto ayuda a determinar si la solicitud está llegando al proxy y por qué podría ser rechazada (por ejemplo, fallo de autenticación, acceso denegado).
• Conectividad de red: Use curl -v --proxy <su-url-de-proxy> <url-de-destino> dentro de un paso del flujo de trabajo para probar explícitamente la conectividad a través del proxy a un punto final externo conocido.
• Problemas de certificados SSL/TLS: Si está utilizando un proxy HTTPS o accediendo a sitios HTTPS a través de un proxy HTTP, y el proxy realiza una inspección SSL, el ejecutor podría encontrar errores de validación de certificados. Esto requiere que el certificado de CA raíz del proxy se agregue al almacén de confianza del ejecutor. Esta es una configuración compleja a menudo gestionada por configuraciones de ejecutores autohospedados.

Resumen de la configuración del proxy