⏱ Tiempo estimado: 20–25 minutos

🎯 Rama / Perfil: Developers que quieren pasar de usar Codex manualmente a automatizar tareas repetitivas de ingeniería.

🧠 Conocimiento previo necesario: Git, GitHub, estructura básica de un repositorio y conceptos básicos de GitHub Actions.

💡 ¿Qué vas a lograr? Crear un workflow de GitHub Actions que ejecute Codex sobre tu repositorio y produzca un resultado automatizado.

🛠 Lo que necesitas antes de empezar

• Cuenta de GitHub y un repositorio → GitHub
• Codex → Documentación oficial
• OpenAI Platform → Plataforma oficial
• Un repositorio donde tengas permisos para modificar GitHub Actions.

Para este ejercicio utilizaremos openai/codex-action, la GitHub Action oficial de OpenAI.

📋 Pasos

Paso 1 — Crea una tarea repetible

Primero decide qué trabajo quieres automatizar.

Ejemplo:

Analizar el repositorio y generar un informe de deuda técnica.

La tarea puede tener esta estructura:

Entrada
   ↓
Inspeccionar repositorio
   ↓
Analizar
   ↓
Generar resultado
   ↓
Guardar resultado

Para este ejercicio:

Repositorio
     ↓
Codex
     ↓
technical-debt-report.md

Paso 2 — Crea el workflow

En tu repositorio crea:

.github/
└── workflows/
    └── codex-audit.yml

Dentro coloca:

name: Codex Audit

on:
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest

    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Codex
        uses: openai/codex-action@main
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Analiza este repositorio.

            Identifica:
            - deuda técnica;
            - código duplicado;
            - funciones excesivamente complejas;
            - documentación faltante;
            - tests faltantes.

            No modifiques archivos.

            Genera un informe llamado:
            technical-debt-report.md

            El informe debe incluir:
            - problema;
            - archivo;
            - impacto;
            - recomendación.

Paso 3 — Configura el secreto

En GitHub entra a:

Repository → Settings → Secrets and variables → Actions

Crea:

OPENAI_API_KEY

y coloca allí tu clave.

No pongas la clave directamente dentro del YAML:

# ❌ NO
openai-api-key: sk-xxxxxxxx

Usa:

# ✅
openai-api-key: ${{ secrets.OPENAI_API_KEY }}

La clave debe permanecer fuera del código y del repositorio.

Paso 4 — Ejecuta tu primera fábrica

Haz commit:

git add .github/workflows/codex-audit.yml
git commit -m "ci: add codex audit workflow"
git push

Después entra en:

GitHub → Actions → Codex Audit → Run workflow

El flujo será:

GitHub Actions
      ↓
checkout
      ↓
Codex Action
      ↓
codex exec
      ↓
análisis
      ↓
technical-debt-report.md

Ya no necesitas iniciar Codex manualmente para ejecutar esta tarea.

Paso 5 — Convierte la tarea en una verdadera "fábrica"

No quieres tener diez prompts distintos para diez tareas.

Puedes organizar tareas como:

.codex/
├── audit.md
├── tests.md
├── documentation.md
└── dependencies.md

Por ejemplo:

audit.md
    ↓
Auditoría técnica

tests.md
    ↓
Detectar tests faltantes

documentation.md
    ↓
Detectar documentación incompleta

dependencies.md
    ↓
Revisar dependencias

Después puedes crear workflows diferentes que invoquen cada tarea.

Así empiezas a convertir Codex en una capa de automatización de ingeniería.

Paso 6 — Añade una regla de seguridad fundamental

No permitas inicialmente que tu automatización tenga libertad total.

Empieza con tareas que:

• inspeccionen;
• analicen;
• generen informes;
• ejecuten tests.

Después puedes evolucionar hacia:

analizar
   ↓
proponer
   ↓
crear cambios
   ↓
crear PR
   ↓
humano revisa
   ↓
merge

No saltes directamente al último nivel.

Limita cuidadosamente los permisos de filesystem, GitHub y red cuando permitas que Codex modifique código.

✅ Resultado esperado

Tendrás un workflow de GitHub Actions que puede ejecutar Codex automáticamente y producir un informe sobre tu repositorio.

Más importante aún, habrás creado el primer bloque de una arquitectura reutilizable:

                 ┌── Auditoría
                 │
GitHub Actions ──┼── Tests
                 │
                 ├── Documentación
                 │
                 └── Mantenimiento
                       ↓
                     Codex

Esto cambia el modelo mental de:

"uso Codex para programar"

a:

"diseño procesos donde Codex realiza trabajo de ingeniería".

🔥 Tu reto (siguiente acción)

Transforma el workflow anterior en una pequeña cadena de automatización:

PR
 ↓
Codex analiza
 ↓
Codex identifica problemas
 ↓
Codex genera reporte
 ↓
GitHub Actions publica resultado
 ↓
Tú decides qué corregir

Después crea una segunda tarea:

"Analiza qué partes del proyecto no tienen tests y genera una lista priorizada."

Cuando tengas eso funcionando, el siguiente salto natural es hacer que Codex cree automáticamente un Pull Request con una corrección, manteniendo la revisión humana antes del merge.

📚 Recursos para ir más lejos

• Codex Action oficial — integra Codex directamente en GitHub Actions.
• Seguridad de Codex Action — permisos, secretos, aislamiento y consideraciones de seguridad.
• Codex como plataforma — explica cómo usar Codex para construir workflows.
• Skills + Agents SDK — ejemplos de automatización de tareas recurrentes.