Y en este artículo quiero dejarte las configuraciones que mostré durante el mismo con su correspondiente explicación para que te sea lo más sencillo posible copiarlas y adaptarlas a tus aplicaciones 😃

Qué es launch.json

launch.json es el archivo donde VS Code guarda las configuraciones de ejecución y depuración de un proyecto. Se encuentra normalmente dentro de la carpeta .vscode en la raíz del repositorio.

Cada entrada dentro de configurations es una receta. Esa receta le dice a VS Code qué debe ejecutar, con qué depurador, desde qué carpeta y con qué comportamiento adicional.

En este ejemplo real, el archivo define cuatro configuraciones principales y un compound:

{
  "configurations": [
    {
      "type": "java",
      "name": "☕ Backend (Spring Boot)",
      "request": "launch"
    },
    {
      "type": "node",
      "name": "🌐 Frontend (Vite Dev Server)",
      "request": "launch"
    },
    {
      "type": "msedge",
      "name": "🔍 Edge: Debug Frontend",
      "request": "launch"
    },
    {
      "type": "editor-browser",
      "name": "🌐 Launch Integrated Browser",
      "request": "launch"
    }
  ],
  "compounds": [
    {
      "name": "🚀 Full Stack (Backend + Frontend)"
    }
  ]
}

Eso ya deja ver algo importante: launch.json no se limita a una sola forma de arrancar cosas. Puede lanzar procesos Java, ejecutar comandos de Node, abrir Edge para depuración o incluso abrir el navegador integrado de VS Code.

La configuración del backend

La primera pieza del ejemplo es el backend en Spring Boot:

{
  "type": "java",
  "name": "☕ Backend (Spring Boot)",
  "request": "launch",
  "mainClass": "com.ideaforge.quickstart.Application",
  "cwd": "${workspaceFolder}/backend",
  "env": {
    "SPRING_PROFILES_ACTIVE": "default"
  },
  "console": "integratedTerminal"
}

Aquí hay varios campos que merece la pena entender:

• type indica que se usará el depurador de Java.
• mainClass señala la clase principal de Spring Boot que se debe lanzar.
• cwd fija la carpeta de trabajo en backend.
• env permite definir variables de entorno, en este caso el perfil activo de Spring.
• console manda la salida al terminal integrado.

Esta configuración sí representa una depuración clásica del backend: VS Code lanza la aplicación Java y puede engancharse al proceso para depurarla.

La configuración del frontend con Vite

La segunda pieza arranca el frontend:

{
  "type": "node",
  "name": "🌐 Frontend (Vite Dev Server)",
  "request": "launch",
  "runtimeExecutable": "npm",
  "runtimeArgs": [
    "run",
    "dev"
  ],
  "cwd": "${workspaceFolder}/frontend",
  "console": "integratedTerminal",
  "skipFiles": [
    "<node_modules>/**"
  ]
}

Aquí el patrón es distinto al de Java. No se está arrancando una clase principal, sino ejecutando npm run dev desde la carpeta frontend. Eso pone en marcha el servidor de desarrollo de Vite.

Este detalle importa porque muchas veces se mezclan dos cosas distintas:

• arrancar el servidor del frontend
• abrir un navegador o una sesión de depuración sobre la aplicación web

En este launch.json esas responsabilidades están separadas, y eso está bien diseñado.

Cómo entra en juego serverReadyAction

La parte más interesante del ejemplo está dentro de la configuración del frontend, donde aparece serverReadyAction:

{
  "type": "node",
  "name": "🌐 Frontend (Vite Dev Server)",
  "request": "launch",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "dev"],
  "cwd": "${workspaceFolder}/frontend",
  "serverReadyAction": {
    "pattern": "Local:.+(https?://\\S+)",
    "uriFormat": "%s",
    "action": "startDebugging",
    "name": "🌐 Launch Integrated Browser"
  }
}

Esto significa que VS Code vigila la salida del proceso de Vite y espera a detectar una línea como la que imprime normalmente el servidor:

Local:   http://localhost:5176/

En cuanto encuentra una URL que encaja con el patrón, dispara otra configuración con action: "startDebugging". En este caso, la configuración que se lanza es 🌐 Launch Integrated Browser.

Aquí sí hay una secuencia real: primero Vite, después el navegador.

La configuración del navegador integrado

La configuración que se dispara cuando Vite está listo es esta:

{
  "name": "🌐 Launch Integrated Browser",
  "request": "launch",
  "type": "editor-browser",
  "url": "http://localhost:5176",
  "webRoot": "${workspaceFolder}"
}

Su función es sencilla: abrir la aplicación dentro del navegador integrado de VS Code, usando la URL local del frontend.

Además del navegador integrado, el archivo también incluye una configuración adicional para Edge:

{
  "type": "msedge",
  "name": "🔍 Edge: Debug Frontend",
  "request": "launch",
  "url": "http://localhost:5176",
  "webRoot": "${workspaceFolder}/frontend/src"
}

Esa configuración está oculta en la presentación habitual y sirve como alternativa cuando interesa depurar en Edge con soporte de source maps, pero no es la que forma parte del flujo automático principal.

Compounds

Si lo que te interesa es ejecutar más de una configuración a la vez, que suele ser lo habitual cuando tienes un backend y un frontend, también te interesará configurar lo que se llaman compounds:

{
  "name": "🚀 Full Stack (Backend + Frontend)",
  "configurations": [
    "☕ Backend (Spring Boot)",
    "🌐 Frontend (Vite Dev Server)"
  ],
  "stopAll": true
}

Esto permite lanzar backend y frontend desde una única entrada. Es cómodo, pero conviene entenderlo bien: el compound no establece dependencia entre ambos procesos. Los dos arranques se lanzan en paralelo.

Eso quiere decir que, en este ejemplo, la secuencia controlada existe entre el frontend y el navegador, pero no entre el backend y el frontend.

Dicho de otra forma:

1. el compound arranca backend y frontend al mismo tiempo
2. Vite termina de levantar su servidor
3. serverReadyAction detecta la URL local
4. VS Code lanza el navegador integrado

Este matiz es importante porque a veces se dice que todo está encadenado cuando en realidad solo una parte del flujo lo está.

Cuándo usar cada pieza

Una forma práctica de pensarlo es esta:

• Usa una configuración normal cuando quieres arrancar una sola pieza, como el backend o el frontend.
• Usa un compound cuando quieres lanzar varias piezas desde una única orden, aunque eso ocurra en paralelo.
• Usa serverReadyAction cuando necesitas reaccionar a una señal real de disponibilidad, como la URL que imprime Vite al arrancar.
• Usa una configuración de navegador separada cuando quieres distinguir claramente entre arrancar un servidor y abrir la interfaz.

Ese reparto de responsabilidades hace que el archivo sea más fácil de mantener y también más fácil de entender por parte de cualquier persona que se incorpore al proyecto.

Si quisieras secuencia completa backend → frontend → navegador

Este ejemplo no hace eso todavía. El backend y el frontend arrancan en paralelo porque así está definido el compound. Si el objetivo fuera esperar a que Spring Boot estuviera listo antes de lanzar Vite, haría falta introducir un encadenado adicional desde la configuración Java o reestructurar el flujo con tareas y dependencias.

Precisamente por eso este archivo es un buen ejemplo didáctico: muestra muy bien la diferencia entre agrupar procesos y secuenciarlos de verdad.

Conclusión

launch.json es mucho más que un archivo para pulsar F5. Bien usado, te permite describir el flujo de arranque real de tu aplicación y reducir bastante la fricción diaria.

La idea más importante es esta: los compounds agrupan, pero no ordenan. El orden real aparece cuando introduces una señal verificable del proceso, como hace aquí serverReadyAction al detectar la URL de Vite y lanzar después el navegador integrado.

Cuando entiendes esa diferencia, launch.json deja de ser un archivo misterioso y se convierte en una herramienta muy potente para automatizar el desarrollo local 🚀

¡Nos vemos 👋🏻!

La entrada Cómo funciona launch.json en VS Code: configuraciones, compounds y arranques secuenciales se publicó primero en return(GiS);.

Cuando Dependabot te abre una pull request de seguridad, lo primero que sabes es esto: una versión concreta de una dependencia está dentro de un rango vulnerable.

Perfecto 👍
Pero… eso no responde a la pregunta importante: ¿esto es realmente explotable en mi código?

Porque una cosa es que exista una advisory…
y otra muy distinta es que tu aplicación esté usando justo ese patrón vulnerable y además se cumplan las condiciones para explotarlo.

Con esa idea en mente he jugado con una prueba de concepto en la que he estado trabajando en el repositorio dependabot-security-analyzer. La idea en este caso es usar un GitHub Agentic Workflow para analizar una PR de Dependabot de forma más profunda: identificar la dependencia afectada, consultar la advisory completa, revisar el repositorio y decidir si el caso merece prioridad alta o si la exposición no está realmente demostrada. En este artículo te muestro cómo lo estoy comprobando gracias a estos nuevos flujos.

Si todavía no has visto qué son los GitHub Agentic Workflows, aquí tienes un vídeo donde te lo explico en 30 minutos:

El problema no es detectar vulnerabilidades (eso ya lo hacemos bien)

Herramientas como Dependabot hacen muy bien la parte de detectar versiones afectadas y proponer actualizaciones. Pero entre “la dependencia es vulnerable” y “mi aplicación es explotable por esa vulnerabilidad” hay bastante distancia. A veces tu código ni siquiera usa la parte afectada. Otras veces sí la usa, pero sin cumplir las condiciones reales del exploit. Y en otros casos sí se da toda la cadena y entonces esa PR merece atención inmediata.

La intención de esta PoC no es discutir si hay que actualizar o no. Las dependencias vulnerables conviene corregirlas igualmente. La cuestión aquí es otra: aportar más contexto para priorizar mejor, reducir ruido y distinguir entre presencia de una advisory y exposición real en el código.

Cómo funciona el workflow

El flujo está definido en lenguaje natural dentro del propio workflow y se activa cuando un usuario de confianza comenta /dependabot-analyze en una pull request. El comando tiene que ser el primer token del comentario. A partir de ahí, el agente solo sigue adelante si el evento está realmente ligado a una PR y si esa PR ha sido abierta por dependabot[bot].

Ese filtro es importante porque el objetivo no es analizar cualquier cambio, sino específicamente pull requests automáticas de seguridad. Si el comentario no está en una PR o la PR no es de Dependabot, el flujo se detiene y deja una explicación breve.

El frontmatter del workflow deja bastante claro cómo está configurado este ejemplo. Aquí se define el trigger, los permisos, las herramientas disponibles, la red permitida y también el engine y el modelo que quiero usar:

---
name: 🛡️ VulnScope PR Guard 🔎

on:
  slash_command:
    name: dependabot-analyze
    events: [pull_request_comment]
  reaction: eyes

permissions:
  contents: read
  pull-requests: read
  security-events: read

tools:
  github:
    toolsets: [context, repos, pull_requests, security_advisories]

network:
  allowed:
    - defaults

engine:
  id: copilot
  model: gpt-4.1

safe-outputs:
  add-labels:
    allowed: ["🔴 vulnerability:in-use", "🟢 vulnerability:not-in-use", "🤔 vulnerability:unclear", "🚨 priority:high", "🕓 priority:low"]
    max: 2
  add-comment:
    max: 1
---

En este ejemplo he usado engine: copilot y el modelo gpt-4.1 por una razón bastante práctica: no consume premium requests y quería comprobar si era capaz de resolver bien un caso como este. La parte interesante es que esto no está cerrado. El workflow se puede adaptar para usar otros modelos e incluso otros agentes de IA si hiciera falta, dependiendo del nivel de razonamiento, del coste o del tipo de repositorio que quieras analizar.

También es importante tener en cuenta que este tipo de flujos no siempre se comportan igual con todos los modelos. A veces el prompt necesita pequeños ajustes en cómo formula las instrucciones, cómo restringe la salida o cómo pide justificar el veredicto. Yo lo voy iterando y afinando con el tiempo, y no me extrañaría que la versión óptima del prompt para un modelo no fuese exactamente la mejor para otro.

También es posible que en lugar de un slash command se lanzara siempre que ocurre una PR ejecutada por Dependabot, pero en este caso quería ser yo quien lo controlara. También por supuesto se puede «complicar más» y que cada vez que se haga push del código si todavía hay alertas de Dependabot pendientes que se ordene la re-ejecución de estos flujos para ver si en una siguiente iteración no solo no se ha arreglado la versión de la dependencia sino que encima ahora se está haciendo uso de la funcionalidad que la hace vulnerable 😅

Una vez validado el contexto, el workflow toma la propia pull request como fuente inicial para identificar qué paquete se actualiza, desde qué versión y hacia cuál. Si en el PR aparecen identificadores como un CVE o un GHSA, los usa como punto de partida; si no aparecen, intenta inferir la advisory a partir del paquete y del rango de versiones.

La parte clave: ir a la advisory completa

Aquí está una de las diferencias importantes respecto a una automatización más superficial. El flujo no se conforma con el resumen del PR de Dependabot. Va a buscar los detalles completos en GitHub Security Advisories para entender qué patrón concreto es vulnerable, qué versiones están afectadas, qué CWE aplica y, sobre todo, qué condiciones hacen falta para que el problema sea explotable.

Eso cambia bastante el tipo de análisis que se puede hacer. No es lo mismo detectar que una librería está instalada que saber que la advisory solo afecta a una función concreta, a cierto modo de invocación o a un caso donde el input del usuario llega sin validación a un punto determinado. El workflow intenta aterrizar precisamente eso.

Si la advisory pública no da suficiente detalle técnico, el planteamiento del flujo contempla ampliar contexto con referencias adicionales y fuentes públicas más detalladas. La idea es que el veredicto no salga de una lectura superficial del PR, sino de entender bien el patrón vulnerable que describe la advisory.

El prompt también forma parte del diseño

Otro punto que me parece muy interesante es que el comportamiento del workflow no está definido solo por el frontmatter. El prompt en sí también es parte central del diseño, porque es donde se obliga al agente a seguir un orden concreto, a no confundir riesgos adyacentes con la advisory analizada y a justificar por qué marca un caso como realmente explotable o no.

Este es un fragmento representativo del prompt actual:

## Trigger

This workflow runs when a trusted user comments `/dependabot-analyze` on a pull request.
The command must be the first token in the comment.

If the command was not used on a pull request, stop immediately and do nothing.

You must then check if the target PR was created by Dependabot (author is `dependabot[bot]`).
If it was NOT created by Dependabot, stop here and leave a short comment explaining that this command only supports Dependabot PRs.

## Your tasks

### 3. Get complete vulnerability details from GitHub Security Advisories
- Extract from the advisory:
  - Vulnerable version range
  - Vulnerable code patterns
  - CWE classification
  - Exploitation conditions
  - References

### 4. Analyze the codebase
- Distinguish clearly between these three questions:
  - Is the vulnerable method/pattern present?
  - Are the advisory's exploitation preconditions actually satisfied in this codebase?
  - Is there a different security issue nearby that is real but outside the scope of this advisory?

### 6. Add labels to the PR
- `🔴 vulnerability:in-use` + `🚨 priority:high`
- `🟢 vulnerability:not-in-use` + `🕓 priority:low`
- `🤔 vulnerability:unclear` when the vulnerable pattern cannot be determined

Me gusta enseñar esta parte porque aquí se ve muy bien que el valor no está solo en “usar IA”, sino en cómo se define el criterio. El prompt no le pide al agente que mire si una librería sale en un fichero, sino que determine si el patrón vulnerable existe de verdad, si las precondiciones del exploit están demostradas y si hay que separar ese análisis de otros problemas de seguridad que puedan aparecer cerca.

Y aquí vuelve a entrar el tema del modelo. Este prompt seguramente seguirá cambiando. Yo lo voy mejorando a medida que pruebo más escenarios y, muy probablemente, algunas decisiones de redacción, granularidad o formato de salida tendrán que ser un poco distintas según el modelo o el agente que quiera usar detrás.

Pero lo que si que es realmente importante aquí es: esta ayuda adicional es más que cero.

Qué devuelve en la PR de Dependabot

El resultado del análisis se deja directamente en la propia PR. El workflow comprueba primero si existen las labels que necesita y, si no están, las crea. Luego aplica una combinación de etiquetas según el veredicto:

• 🔴 vulnerability:in-use y 🚨 priority:high si el patrón vulnerable está en uso y las precondiciones del exploit están demostradas o muy respaldadas por el código.
• 🟢 vulnerability:not-in-use y 🕓 priority:low si el patrón vulnerable no aparece, el uso es seguro o la explotabilidad no está demostrada.
• 🤔 vulnerability:unclear si después de consultar advisories y fuentes públicas no hay suficiente detalle técnico para identificar el patrón vulnerable con confianza.

Algo como esto:

Además deja un comentario estructurado con el resumen de la advisory, severidad, CWE, patrón vulnerable, condiciones de explotación, referencias y una tabla por archivos donde distingue entre uso del patrón, precondiciones cumplidas, riesgos adyacentes y veredicto final.

Ese detalle me parece importante porque convierte la PR en algo bastante más accionable. No es solo una actualización propuesta por Dependabot, sino una revisión con criterio explícito sobre si el riesgo está realmente activado en el código del repositorio.

Lo que me parece interesante de esta PoC

Lo que más me interesa aquí no es solo automatizar pasos, sino introducir mejor criterio de priorización en un problema muy ruidoso. En muchos repositorios acaban acumulándose alertas, PRs automáticas y decisiones rápidas basadas únicamente en la existencia de una advisory. Tener un flujo que intente responder si el patrón vulnerable está de verdad en uso me parece bastante más útil.

También me gusta porque obliga al análisis a no mezclar hallazgos distintos. Puede haber una advisory que no aplique realmente a tu código y, al mismo tiempo, puede existir otro problema de seguridad cerca de ese mismo flujo. El workflow intenta dejar claro cuándo está hablando de la advisory concreta de Dependabot y cuándo se trata de un riesgo adyacente distinto.

Una forma más útil de revisar PRs de seguridad

En definitiva, esta prueba de concepto busca responder una pregunta que Dependabot, y otras herramientas, no resuelven a día de hoy del todo: no solo si una dependencia está afectada por una advisory, sino si tu repositorio está usando realmente el patrón que convierte esa advisory en un problema práctico.

Para mí ese es el punto interesante de combinar GitHub Agentic Workflows con análisis de seguridad de dependencias: usar la automatización no solo para abrir PRs, sino para devolver contexto que ayude a decidir mejor qué corregir primero y por qué.

Si quieres explorar otros escenarios en los que GitHub Agentic Workflows pueden tener sentido aquí te dejo otro vídeo donde te muestro dónde lo estoy usando yo:

¡Nos vemos 👋🏻!

La entrada Dependabot te dice que es vulnerable… ¿pero es explotable de verdad? se publicó primero en return(GiS);.

Si estás evaluando GitHub Advanced Security es posible que cuando revises la parte de Code scanning, que analiza las vulnerabilidades que podemos introducir, sin querer claro está 😅, en nuestro propio código, puede que te preguntes:

👉 “¿Puedo controlar qué analiza CodeQL?”
👉 “¿Puedo limitarlo al OWASP Top 10 e incluso incluir mis propias reglas?”

Y la respuesta es: sí y en este artículo te cuento cómo configurarlo.

Si no conoces muchos de GitHub Advanced Security aquí te dejo un vídeo de mi canal donde hago un repaso de sus funcionalidades principals:

🤔 ¿Por qué limitar las queries de CodeQL?

Por defecto, CodeQL ejecuta cientos de queries de seguridad. Aquí puedes encontrar las CWEs que cubre a día de hoy. Esto está genial… pero en algunos casos algunos el sentimiento es:

❌ Ejecuciones muy largas en repositorios inmensos
❌ Genera ruido
❌ Puede ser difícil priorizar
❌ No siempre encaja con tus políticas de seguridad

Y aquí es donde entra el verdadero valor: 👉 definir tu propio conjunto de queries siguiendo marcos normativos o incluso añadiendo alguna query interna propia que también se quiere tener en consideración.

📦 Repositorio de ejemplo

Así para poder ilustrar esto he creado un repositorio que te dejo en mi cuenta de GitHub, en el cual me he marcado dos objetivos:

1. Ejecutar solo un subconjunto de queries

En lugar de usar:

queries: security-and-quality

Puedes definir exactamente qué quieres ejecutar:

• OWASP Top 10
• solo ciertos CWE
• queries críticas
• etc.

OWASP Top 10 es el estándar más común en AppSec.

Cada categoría (por ejemplo Injection) se corresponde con múltiples CWE y queries.

👉 Ejemplo:

• SQL Injection → CWE-89
• XSS → CWE-79

Y CodeQL ya tiene queries que cubren estos casos.

Incluso puedes crear suites específicas tipo:

name: OWASP-Top-10
queries:
  - codeql/java/queries/security/sql-injection.ql
  - codeql/javascript/queries/security/xss.ql

Este enfoque está bastante extendido en la comunidad (Medium)

2. Añadir custom queries

Aquí es donde la cosa se pone interesante 🔥 CodeQL permite escribir queries propias porque:

👉 trata el código como datos consultables
👉 puedes detectar patrones específicos de tu empresa

Ejemplos reales:

• uso de librerías internas inseguras
• validaciones corporativas obligatorias
• patrones legacy peligrosos

Vale, pues ahora ¿Cómo configuramos esto? Pues vamos a verlo 😃

Configuración del flujo avanzado de GitHub Actions con queries personalizadas para CodeQL

Para que todo esto sea posible tienes que tener configurado CodeQL en su modo avanzado. Esto lo que significa es que necesitamos tener el flujo definido en el repo o al menos tener un flujo reusable en algún sitio donde tener toda esta configuración. Pero antes de nada necesitamos un archivo de configuración con las reglas personalizadas.

1. Crear tu archivo de configuración

En .github/codeql/codeql-config.yml:

Lo que tengo es algo como lo siguiente:

# Configuración de CodeQL para OWASP Top 10
# Este archivo indica a CodeQL que use SOLO la query suite personalizada
# de OWASP Top 10, en lugar de las suites predefinidas (default o security-extended).
#
# Documentación:
# https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning

name: "CodeQL - OWASP Top 10"

# ⚠️ CLAVE: Desactivar las queries predefinidas (default suite)
# Sin esto, CodeQL ejecuta las queries por defecto ADEMÁS de las personalizadas
disable-default-queries: true

# Queries a ejecutar:
# 1. Suite OWASP Top 10 (2025) - queries estándar filtradas por marco normativo
# 2. Queries personalizadas de negocio bancario (custom rules)
queries:
  - uses: ./.github/codeql/owasp-top-10-js.qls
  - uses: ./.github/codeql/custom-queries

# Paths a analizar (solo el código fuente de la aplicación)
paths:
  - src

# Paths a ignorar (tests, fixtures, etc.)
paths-ignore:
  - node_modules
  - "**/*.test.js"
  - "**/*.spec.js"

Este me va a permitir indicar dónde están las queries que quiero lanzar. En el caso del archivo .github/codeql/owasp-top-10-js.qls lo que he hecho es algo como lo siguiente:

# -----------------------------------------------------------
# CodeQL Query Suite: OWASP Top 10 (2025) - JavaScript/TypeScript
# -----------------------------------------------------------
#
# Este archivo define un conjunto personalizado de queries de CodeQL
# que cubren exclusivamente las categorías del OWASP Top 10 (2025).
#
# Al usar esta suite en lugar de "security-extended" o "default",
# solo se ejecutarán las queries relevantes para OWASP Top 10,
# filtrando cualquier otra regla que no aplique a este marco normativo.
#
# Documentación de query suites:
# https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/
#
# Lista completa de CWEs cubiertos por CodeQL:
# https://codeql.github.com/codeql-query-help/full-cwe/
#
# -----------------------------------------------------------
# Para limitar aún más por severidad o precisión, descomenta:
#- include:
#    problem.severity:
#    - medium
#    - high
#    - very-high
#    - critical
#    precision:
#    - high
#    - very-high
# -----------------------------------------------------------

# Importar el pack de queries de JavaScript/TypeScript
# Necesario cuando se usa disable-default-queries: true en la config
- qlpack: codeql/javascript-queries

- include:
    id:

    # =========================================================
    # A01:2025 - Broken Access Control
    # Mantiene #1. Ahora incluye SSRF (antes era A10:2021)
    # CWE-22: Path Traversal
    # CWE-601: URL Redirection to Untrusted Site
    # CWE-918: SSRF (movido desde A10:2021)
    # =========================================================
    - js/path-injection
    - js/ml-powered/path-injection
    - js/server-side-unvalidated-url-redirection
    - js/client-side-unvalidated-url-redirection
    - js/user-controlled-bypass
    - js/exposure-of-private-files
    - js/request-forgery
    - js/client-side-request-forgery
    - js/file-access-to-http
    - js/http-to-file-access
    - js/sensitive-get-query

    # =========================================================
    # A02:2025 - Security Misconfiguration
    # Sube de A05:2021 a A02:2025
    # CWE-16: Configuration
    # CWE-611: XXE
    # =========================================================
    - js/cors-misconfiguration-for-credentials
    - js/disabling-certificate-validation
    - js/disabling-electron-websecurity
    - js/enabling-electron-insecure-content
    - js/functionality-from-untrusted-source
    - js/unsafe-external-link
    - js/double-escaping
    - js/incomplete-hostname-regexp
    - js/incomplete-url-scheme-check
    - js/incomplete-url-substring-sanitization
    - js/incorrect-suffix-check
    - js/incomplete-sanitization
    - js/incomplete-html-attribute-sanitization
    - js/incomplete-multi-character-sanitization
    - js/samesite-none-cookie

    # =========================================================
    # A03:2025 - Software Supply Chain Failures
    # Expandido desde A06:2021 (Vulnerable and Outdated Components)
    # (Dependabot + CodeQL para dependencias inseguras)
    # =========================================================
    - js/insecure-dependency
    - js/insecure-download

    # =========================================================
    # A04:2025 - Cryptographic Failures
    # Baja de A02:2021 a A04:2025
    # CWE-327: Use of Broken/Weak Crypto Algorithm
    # CWE-328: Reversible One-Way Hash
    # CWE-330: Insufficient Randomness
    # =========================================================
    - js/weak-cryptographic-algorithm
    - js/insufficient-key-size
    - js/biased-cryptographic-random
    - js/insecure-randomness
    - js/clear-text-storage-of-sensitive-data
    - js/clear-text-logging
    - js/clear-text-cookie

    # =========================================================
    # A05:2025 - Injection
    # Baja de A03:2021 a A05:2025
    # CWE-79: XSS
    # CWE-78: OS Command Injection
    # CWE-89: SQL Injection
    # CWE-94: Code Injection
    # CWE-917: Expression Language Injection
    # CWE-1321: Prototype Pollution
    # =========================================================
    - js/sql-injection
    - js/ml-powered/sql-injection
    - js/nosql-injection
    - js/ml-powered/nosql-injection
    - js/reflected-xss
    - js/stored-xss
    - js/xss
    - js/xss-through-dom
    - js/xss-through-exception
    - js/ml-powered/xss
    - js/command-line-injection
    - js/indirect-command-line-injection
    - js/shell-command-constructed-from-input
    - js/shell-command-injection-from-environment
    - js/code-injection
    - js/unsafe-code-construction
    - js/bad-code-sanitization
    - js/bad-tag-filter
    - js/html-constructed-from-input
    - js/unsafe-html-expansion
    - js/prototype-pollution
    - js/prototype-polluting-assignment
    - js/prototype-pollution-utility
    - js/tainted-format-string
    - js/template-object-injection
    - js/xpath-injection
    - js/xml-bomb
    - js/xxe
    - js/log-injection
    - js/regex/missing-regexp-anchor

    # =========================================================
    # A06:2025 - Insecure Design
    # Baja de A04:2021 a A06:2025
    # CWE-799: Improper Control of Interaction Frequency
    # =========================================================
    - js/missing-rate-limiting

    # =========================================================
    # A07:2025 - Authentication Failures
    # Mantiene #7 (renombrado de "Identification and Auth Failures")
    # CWE-798: Hardcoded Credentials
    # CWE-259: Hardcoded Password
    # CWE-384: Session Fixation
    # =========================================================
    - js/hardcoded-credentials
    - js/empty-password-in-configuration-file
    - js/password-in-configuration-file
    - js/jwt-missing-verification
    - js/missing-token-validation
    - js/missing-origin-check
    - js/session-fixation
    - js/insufficient-password-hash
    - js/client-exposed-cookie

    # =========================================================
    # A08:2025 - Software or Data Integrity Failures
    # Mantiene #8
    # CWE-502: Deserialization of Untrusted Data
    # =========================================================
    - js/unsafe-deserialization
    - js/unsafe-jquery-plugin
    - js/zipslip
    - js/identity-replacement

    # =========================================================
    # A09:2025 - Security Logging & Alerting Failures
    # Mantiene #9 (renombrado, ahora enfatiza "Alerting")
    # CWE-778: Insufficient Logging
    # (CodeQL tiene cobertura limitada aquí)
    # =========================================================
    - js/stack-trace-exposure
    - js/cross-window-information-leak

    # =========================================================
    # A10:2025 - Mishandling of Exceptional Conditions (NUEVO)
    # Reemplaza SSRF (que se movió a A01)
    # CWE-248: Uncaught Exception
    # CWE-754: Improper Check for Unusual/Exceptional Conditions
    # CWE-391: Unchecked Error Condition
    # =========================================================
    - js/resource-exhaustion

    # =========================================================
    # GitHub Actions (bonus - seguridad en CI/CD)
    # =========================================================
    - js/actions/command-injection
    - js/actions/pull-request-target
    - js/build-artifact-leak
    - js/host-header-forgery-in-email-generation
    - js/remote-property-injection
    - js/unsafe-dynamic-method-access
    - js/useless-regexp-character-escape

Aquí no te voy a engañar, le he pedido ayuda a GitHub Copilot para recopilar todas las reglas que me hacen falta y sería cuestión de probarlo bien para que no se nos olvide nada.

El segundo archivo apunta a una custom query en CodeQL que valida que haya una validación previa a ciertas operaciones que pueden ser críticas, por ejemplo en un banco. En la configuración a lo que se está apuntando en realidad es a una carpeta dentro de la cual hay dos archivos, el qlpack.yml:

# CodeQL Query Pack personalizado para reglas de negocio bancarias
# Este pack contiene queries custom que no están en las suites estándar de CodeQL
name: custom-banking-queries
version: 0.0.1
dependencies:
  codeql/javascript-all: "*"

Y por otro lado uno que he llamado missing-context-validation.ql:

/**
 * @name Operación bancaria sensible sin validación de contexto
 * @description Detecta llamadas a operaciones bancarias sensibles que no están
 *              precedidas por una llamada de validación de contexto en la misma función.
 *              En entornos bancarios, toda operación crítica debe validar el contexto
 *              (sesión, autorización) antes de ejecutarse.
 * @kind problem
 * @problem.severity error
 * @precision high
 * @id custom/missing-context-validation
 * @tags security
 *       banking
 *       compliance
 *       custom
 */

import javascript

/**
 * Nombres de operaciones bancarias sensibles.
 * Cualquier llamada a estas funciones DEBE estar precedida
 * por una validación de contexto en la misma función.
 */
predicate isSensitiveOperationName(string name) {
  name = "executeTransaction" or
  name = "transferFunds" or
  name = "processPayment" or
  name = "approveCredit" or
  name = "withdrawFunds"
}

/**
 * Nombres de funciones de validación de contexto.
 * Al menos una de estas debe aparecer antes de cualquier operación sensible.
 */
predicate isValidationFunctionName(string name) {
  name = "validateContext" or
  name = "validateSession" or
  name = "verifyAuthorization"
}

/**
 * Obtiene el nombre de la función llamada, sea como llamada directa
 * (executeTransaction(...)) o como método (bankService.executeTransaction(...))
 */
string getCallName(CallExpr call) {
  result = call.getCalleeName()
  or
  exists(DotExpr dot |
    dot = call.getCallee() and
    result = dot.getPropertyName()
  )
}

from CallExpr sensitiveCall, Function enclosingFunc, string opName
where
  // Identificar llamadas a operaciones sensibles
  opName = getCallName(sensitiveCall) and
  isSensitiveOperationName(opName) and
  // Obtener la función que contiene la llamada
  enclosingFunc = sensitiveCall.getEnclosingFunction() and
  // Verificar que NO existe una llamada de validación ANTES en la misma función
  not exists(CallExpr validationCall, string valName |
    valName = getCallName(validationCall) and
    isValidationFunctionName(valName) and
    validationCall.getEnclosingFunction() = enclosingFunc and
    validationCall.getLocation().getStartLine() < sensitiveCall.getLocation().getStartLine()
  )
select sensitiveCall,
  "La operación bancaria sensible '" + opName +
  "' se ejecuta sin validación de contexto previa. " +
  "Añade una llamada a validateContext(), validateSession() o verifyAuthorization() antes de esta operación."

Con todo esto ya solo nos queda usarlo como parte de nuestro flujo de GitHub Actions para esa configuración avanzada de CodeQL.

.github/workflows/codeql.yml

💡 Aquí es donde conectas todo:

name: "🛡️ CodeQL - OWASP Top 10"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  # Escaneo programado semanal (lunes a las 8:00 UTC)
  schedule:
    - cron: '0 8 * * 1'

jobs:
  analyze:
    name: Analyze (OWASP Top 10)
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      actions: read

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

    - name: Initialize CodeQL
      uses: github/codeql-action/init@v4
      with:
        languages: javascript-typescript
        # Usar la configuración personalizada que apunta a la suite OWASP
        config-file: ./.github/codeql/codeql-config.yml

    - name: Autobuild
      uses: github/codeql-action/autobuild@v4

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        category: "/language:javascript-typescript"

Aquí lo importante es que en el paso init le pasamos el config file que definí más arriba y con ello ya sabe cuáles son las reglas, preconstruidas y generadas por mi, que tiene que utilizar.

En el caso de las personalizadas, en este ejemplo, verás algo como lo siguiente:

y el detalle se vería así:

🧩 Estrategias que puedes aplicar

Aquí tienes varios patrones reales que puedes usar:

✅ 1. OWASP-only scanning

👉 Ideal para:

• compliance
• auditorías
• equipos empezando con seguridad

⚡ 2. Only critical queries

👉 Reduce ruido
👉 Mejora adopción

🏢 3. Security policies corporativas

👉 Custom queries + suites
👉 Enforcing en PRs

🧪 4. Demo / training environments

👉 Como este repo 😄
👉 Muy útil para workshops o sesiones técnicas

Además, encaja perfectamente con el enfoque shift-left de GitHub Advanced Security, donde detectas vulnerabilidades antes de producción.

¡Nos vemos 👋🏻!

La entrada 🔐 Cómo configurar CodeQL para ejecutar solo las queries que necesitas (OWASP Top 10 + custom queries) se publicó primero en return(GiS);.

El problema es que los agentes trabajan mucho mejor con Markdown que con HTML lleno de clases CSS, menús, sidebars y estructuras de tema. Así que me puse a crear un plugin de WordPress que convierte los posts y las páginas en Markdown limpio para que los agentes puedan consumirlos directamente. El plugin se llama Markdown View for AI Agents y a día de hoy todavía está en revisión por WordPress.org, así que ya os contaré más cuando esté publicado. Aunque si eres curios@ ya lo puedes ver funcionando en este mismo blog 👆🏻😇: en cada artículo verás un botón que pone View as Markdown y voilà, el contenido pasa a ser algo mucho más manejable para nuestros amigos los agentes.

Pero este artículo, más allá de mi plugin, de lo que va es del entorno que he utilizado para desarrollarlo, probarlo y verificar que cumple con todos los requisitos antes de hacer la submission. Y como no podía ser de otra manera, la respuesta fue: Dev Containers.

Si no sabes de qué van los Dev Containers te dejo este vídeo que grabé hace tiempo para mi canal de YouTube:

🎯 El problema

Desarrollar un plugin de WordPress no es como hacer un npm init y a correr. Necesitas:

• Una instancia de WordPress funcionando
• PHP con las extensiones correctas
• MySQL/MariaDb como base de datos
• WP-CLI para gestionar WordPress desde la terminal
• Composer para las dependencias PHP
• PHP_CodeSniffer con los estándares de WordPress

Configurar todo esto en tu máquina local es un dolor. Y si trabajas en más de un proyecto, los conflictos entre versiones son inevitables. Así que lo metí todo en un Dev Container 🎉

📦 La estructura

La configuración vive en la carpeta .devcontainer/ del repositorio:

.devcontainer/
├── devcontainer.json
├── Dockerfile
├── docker-compose.yml
└── setup.sh

Vamos parte por parte.

🐳 Docker Compose

En el docker compose que utilizará mi configuración de Dev Container para levantar los servicios incluí tres contenedores:

services:
  workspace:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspaces/wp-markdown-for-agents:cached
      - composer-cache:/home/vscode/.composer/cache
      - wordpress-data:/srv/wordpress
      - plugins:/home/vscode/.local/share/plugins
      - plugins:/srv/wordpress/wp-content/plugins
      - ..:/srv/wordpress/wp-content/plugins/markdown-view-for-ai-agents:cached
    environment:
      COMPOSER_MEMORY_LIMIT: -1
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    command: sleep infinity
    depends_on:
      - db
      - wordpress

  wordpress:
    image: wordpress:php8.3-apache
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    volumes:
      - wordpress-data:/var/www/html
      - plugins:/var/www/html/wp-content/plugins
      - ..:/var/www/html/wp-content/plugins/markdown-view-for-ai-agents:cached
    depends_on:
      - db

  db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: wordpress
      MARIADB_ROOT_PASSWORD: root
    volumes:
      - mariadb-data:/var/lib/mysql

volumes:
  composer-cache:
  plugins:
  wordpress-data:
  mariadb-data:

El primero de ellos, workspace, es el contenedor principal, en el que estaré desarrollando mi plugin. Los otros dos son los contenedores que me facilitarán una instancia de WordPress, con su correspondiente base de datos, para poder probarlo de forma súper sencilla.

La clave aquí está en el bind mount del plugin. Al montar el directorio del proyecto directamente en wp-content/plugins/, cualquier cambio que hago en el código se refleja inmediatamente en la instancia de WordPress. No hay que copiar archivos, ni reconstruir nada. Edito, guardo, refresco el navegador y listo.

🏗️ El Dockerfile

Para que el contenedor llamado workspace funcione correctamente está esperando poder generar una imagen de Docker, para la que va a usar el Dockerfile que se encuentra en el mismo directorio, .devcontainer:

FROM mcr.microsoft.com/devcontainers/php:3-8.3-trixie

RUN apt-get update \
	&& export DEBIAN_FRONTEND=noninteractive \
	&& apt-get install -y --no-install-recommends default-mysql-client libmariadb-dev librsvg2-bin \
	&& docker-php-ext-install mysqli pdo_mysql \
	&& curl -fsSL -o /usr/local/bin/wp https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar \
	&& chmod +x /usr/local/bin/wp \
	&& mkdir -p /home/vscode/.local/share/plugins \
	&& chown -R vscode:vscode /home/vscode/.local \
	&& apt-get clean \
	&& rm -rf /var/lib/apt/lists/*

Con esto tengo:

• PHP 8.3 en el contenedor donde realmente estoy desarrollando mi plugin
• Cliente de MySQL
• La librería librsvg2-bin, la cual me va a permitir de forma sencilla poder convertir imágenes svg a png.
• WP-CLI para gestionar WordPress desde la terminal (instalar plugins, crear posts de prueba, activar/desactivar el plugin…). Porque no me vale tener el WordPress pelado sino que es mucho más rápido tener ya artículos con los que poder probar el botón/URL en mi caso.

⚙️ El devcontainer.json

Aquí es donde se conecta todo. El devcontainer.json le dice a VS Code qué servicio de Docker Compose usar, qué extensiones instalar, qué puertos reenviar y qué ejecutar después de crear el contenedor:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/php
{
	"name": "🧪 markdown-view-for-ai-agents",
	"dockerComposeFile": "compose.yml",
	"service": "workspace",
	"runServices": [
		"workspace",
		"wordpress",
		"db"
	],
	"workspaceFolder": "/workspaces/wp-markdown-for-agents",
	"shutdownAction": "stopCompose",

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [
		8080
	],
	"portsAttributes": {
		"8080": {
			"label": "📰 WordPress",
			"onAutoForward": "notify"
		}
	},
	"postCreateCommand": "./install-git-hooks.sh",
	"postStartCommand": "bash .devcontainer/post-start.sh",
	"customizations": {
		"vscode": {
			"settings": {
				"php.validate.executablePath": "/usr/local/bin/php",
				"files.associations": {
					"*.inc": "php"
				},
				"[php]": {
					"editor.formatOnSave": false
				},
				"intelephense.environment.phpVersion": "8.3.0",
				"intelephense.files.exclude": [
					"vendor/**"
				],
				"search.exclude": {
					"vendor": true
				}
			},
			"extensions": [
				"GitHub.vscode-github-actions",
				"bmewburn.vscode-intelephense-client",
				"DEVSENSE.composer-php-vscode",
				"xdebug.php-debug"
			]
		}
	},
	"features": {
		"ghcr.io/devcontainers/features/github-cli:1": {}
	}

}

Las extensiones que incluyo son las que uso para desarrollar en PHP con WordPress, pero aquí cada uno puede añadir las suyas. Lo importante es que al abrir el proyecto todo el mundo tiene el mismo entorno con las mismas herramientas.

🚀 El script de setup

Y aquí viene la magia para que el WordPress de pruebas esté configurado tal y como lo necesitas: El postCreateCommand ejecuta un script que se encarga de dejarlo todo listo:

#!/usr/bin/env bash

set -eu

wp_path="/srv/wordpress"
site_url="http://localhost:8080"
sample_seed_option="md_for_agents_sample_content_seeded"
plugin_check_dir="/home/vscode/.local/share/plugins/plugin-check"
plugin_check_main_file="$plugin_check_dir/plugin-check.php"
plugin_check_cli_file="$plugin_check_dir/cli.php"

export XDEBUG_MODE=off

wp_cli() {
	wp --path="$wp_path" "$@"
}

ensure_plugin_check_files() {
	mkdir -p "$plugin_check_dir"

	if [ -f "$plugin_check_main_file" ] && [ -f "$plugin_check_cli_file" ]; then
		return 0
	fi

	tmp_dir="$(mktemp -d)"
	archive="$tmp_dir/plugin-check.zip"
	extracted_dir="$tmp_dir/plugin-check"

	cleanup_plugin_check_tmp() {
		rm -rf "$tmp_dir"
	}

	trap cleanup_plugin_check_tmp RETURN

	curl -fsSL -o "$archive" "https://downloads.wordpress.org/plugin/plugin-check.latest-stable.zip"
	unzip -q "$archive" -d "$tmp_dir"

	find "$plugin_check_dir" -mindepth 1 -maxdepth 1 ! -name '.gitkeep' -exec rm -rf {} +
	cp -R "$extracted_dir"/. "$plugin_check_dir"/

	trap - RETURN
	cleanup_plugin_check_tmp
}

upsert_post() {
	post_type="$1"
	post_slug="$2"
	post_title="$3"
	post_content="$4"

	post_id="$(wp_cli post list --post_type="$post_type" --name="$post_slug" --field=ID 2>/dev/null | head -n 1 || true)"

	if [ -n "$post_id" ]; then
		wp_cli post update "$post_id" \
			--post_title="$post_title" \
			--post_name="$post_slug" \
			--post_content="$post_content" >/dev/null
		echo "$post_id"
		return 0
	fi

	wp_cli post create \
		--post_type="$post_type" \
		--post_status=publish \
		--post_title="$post_title" \
		--post_name="$post_slug" \
		--post_content="$post_content" \
		--porcelain
}

set_post_terms() {
	post_slug="$1"
	taxonomy="$2"
	terms_csv="$3"

	post_id="$(wp_cli post list --post_type=post --name="$post_slug" --field=ID 2>/dev/null | head -n 1 || true)"

	if [ -z "$post_id" ]; then
		return 0
	fi

	wp_cli post term set "$post_id" "$taxonomy" "$terms_csv" >/dev/null
}

seed_sample_content() {
	getting_started_page_id="$(upsert_post \
		page \
		getting-started-markdown-agents \
		'Getting Started with Markdown for Agents' \
		"<!-- wp:paragraph {\"fontSize\":\"large\"} --><p class=\"has-large-font-size\">This local page exists to test the plugin output quickly from a realistic WordPress page.</p><!-- /wp:paragraph --><!-- wp:heading {\"level\":2} --><h2>Checklist</h2><!-- /wp:heading --><!-- wp:list --><ul><li>WordPress installed through WP-CLI</li><li>Plugin activated automatically</li><li>Sample content seeded idempotently</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":2} --><h2>Example prompt</h2><!-- /wp:heading --><!-- wp:paragraph --><p>Summarize this page for an autonomous coding agent.</p><!-- /wp:paragraph -->")"

	upsert_post \
		post \
		release-notes-draft \
		'Release Notes Draft' \
		"<!-- wp:heading {\"level\":1} --><h1>Release Notes Draft</h1><!-- /wp:heading --><!-- wp:heading {\"level\":2} --><h2>Highlights</h2><!-- /wp:heading --><!-- wp:list --><ul><li>Automated WordPress bootstrap</li><li>Local plugin activation</li><li>Repeatable demo content</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":2} --><h2>Pending</h2><!-- /wp:heading --><!-- wp:list {\"ordered\":true} --><ol><li>Verify markdown export output</li><li>Review button placement in the editor</li><li>Package the release zip</li></ol><!-- /wp:list -->" >/dev/null

	upsert_post \
		post \
		agent-qa-scenario \
		'Agent QA Scenario' \
		"<!-- wp:heading {\"level\":2} --><h2>Scenario</h2><!-- /wp:heading --><!-- wp:paragraph --><p>Use this post to test how the plugin exposes headings, lists, and links for agents.</p><!-- /wp:paragraph --><!-- wp:list --><ul><li>Visit the generated markdown endpoint</li><li>Confirm headings remain stable</li><li>Confirm links remain absolute</li></ul><!-- /wp:list --><!-- wp:paragraph --><p>Related page ID: ${getting_started_page_id}</p><!-- /wp:paragraph -->" >/dev/null

	upsert_post \
		post \
		headings-lists-and-frontmatter \
		'Headings, Lists, and Frontmatter' \
		"<!-- wp:paragraph --><p>This post exists to check heading depth, ordered lists, unordered lists, and YAML frontmatter metadata.</p><!-- /wp:paragraph --><!-- wp:heading {\"level\":2} --><h2>Acceptance checklist</h2><!-- /wp:heading --><!-- wp:list --><ul><li>Heading levels remain stable</li><li>Bullet items stay as bullet items</li><li>Categories and tags appear in the frontmatter</li></ul><!-- /wp:list --><!-- wp:heading {\"level\":3} --><h3>Release steps</h3><!-- /wp:heading --><!-- wp:list {\"ordered\":true} --><ol><li>Run linting</li><li>Package the plugin</li><li>Smoke-test the markdown endpoint</li></ol><!-- /wp:list -->" >/dev/null

	upsert_post \
		post \
		links-quotes-and-inline-code \
		'Links, Quotes, and Inline Code' \
		"<!-- wp:paragraph --><p>Use this example to verify how inline links and inline code are represented in the markdown output.</p><!-- /wp:paragraph --><!-- wp:quote --><blockquote class=\"wp-block-quote\"><p>Agents work best when the source content is explicit, stable, and easy to parse.</p><cite>Local demo note</cite></blockquote><!-- /wp:quote --><!-- wp:paragraph --><p>Open the <a href=\"http://localhost:8080/getting-started-markdown-agents/\">getting started page</a> and compare the endpoint output to <code>wp post get</code>.</p><!-- /wp:paragraph -->" >/dev/null

	upsert_post \
		post \
		code-blocks-and-tables \
		'Code Blocks and Tables' \
		"<!-- wp:paragraph --><p>This sample covers fenced code blocks and HTML tables converted into markdown tables.</p><!-- /wp:paragraph --><!-- wp:code --><pre class=\"wp-block-code\"><code lang=\"bash\">wp plugin activate markdown-view-for-ai-agents --path=/srv/wordpress
wp option get siteurl --path=/srv/wordpress</code></pre><!-- /wp:code --><!-- wp:table --><figure class=\"wp-block-table\"><table><thead><tr><th>Check</th><th>Expected result</th></tr></thead><tbody><tr><td>Code fence</td><td>Preserved with bash language</td></tr><tr><td>Table headers</td><td>Rendered as markdown table header row</td></tr></tbody></table></figure><!-- /wp:table -->" >/dev/null

	upsert_post \
		post \
		images-and-mixed-formatting \
		'Images and Mixed Formatting' \
		"<!-- wp:paragraph --><p>This example mixes <strong>bold text</strong>, <em>emphasis</em>, and an image with alt text for markdown conversion checks.</p><!-- /wp:paragraph --><!-- wp:image {\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} --><figure class=\"wp-block-image size-large\"><img src=\"https://wordpress.org/style/images/wp-header-logo.png\" alt=\"WordPress logo\" /></figure><!-- /wp:image --><!-- wp:paragraph --><p>Verify that the generated markdown keeps the image URL and preserves inline emphasis correctly.</p><!-- /wp:paragraph -->" >/dev/null

	set_post_terms headings-lists-and-frontmatter category "Demo Content,Frontmatter"
	set_post_terms headings-lists-and-frontmatter post_tag "headings,lists,metadata"
	set_post_terms links-quotes-and-inline-code category "Demo Content,Links"
	set_post_terms links-quotes-and-inline-code post_tag "quotes,links,inline-code"
	set_post_terms code-blocks-and-tables category "Demo Content,Code"
	set_post_terms code-blocks-and-tables post_tag "code-blocks,tables"
	set_post_terms images-and-mixed-formatting category "Demo Content,Media"
	set_post_terms images-and-mixed-formatting post_tag "images,bold,italic"

	hello_world_id="$(wp_cli post list --post_type=post --name=hello-world --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$hello_world_id" ]; then
		wp_cli post delete "$hello_world_id" --force >/dev/null
	fi

	sample_page_id="$(wp_cli post list --post_type=page --name=sample-page --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$sample_page_id" ]; then
		wp_cli post delete "$sample_page_id" --force >/dev/null
	fi

	privacy_policy_id="$(wp_cli post list --post_type=page --name=privacy-policy --field=ID 2>/dev/null | head -n 1 || true)"
	if [ -n "$privacy_policy_id" ]; then
		wp_cli option delete wp_page_for_privacy_policy >/dev/null 2>&1 || true
		wp_cli post delete "$privacy_policy_id" --force >/dev/null
	fi

	wp_cli option update show_on_front posts >/dev/null
	wp_cli option delete page_on_front >/dev/null 2>&1 || true
	wp_cli option delete page_for_posts >/dev/null 2>&1 || true

	if wp_cli option get "$sample_seed_option" >/dev/null 2>&1; then
		wp_cli option update "$sample_seed_option" 1 >/dev/null
	else
		wp_cli option add "$sample_seed_option" 1 >/dev/null
	fi
}

if [ ! -d "$wp_path" ]; then
	exit 0
fi

attempt=1
max_attempts=30

while [ "$attempt" -le "$max_attempts" ]; do
	if [ -f "$wp_path/wp-config.php" ]; then
		break
	fi
	sleep 2
	attempt=$((attempt + 1))
done

if [ ! -f "$wp_path/wp-config.php" ]; then
	if [ -n "${WORDPRESS_DB_HOST:-}" ] && [ -n "${WORDPRESS_DB_NAME:-}" ] && [ -n "${WORDPRESS_DB_USER:-}" ] && [ -n "${WORDPRESS_DB_PASSWORD:-}" ]; then
		wp config create \
			--path="$wp_path" \
			--dbname="$WORDPRESS_DB_NAME" \
			--dbuser="$WORDPRESS_DB_USER" \
			--dbpass="$WORDPRESS_DB_PASSWORD" \
			--dbhost="$WORDPRESS_DB_HOST" \
			--skip-check \
			--force >/dev/null 2>&1 || true
	fi

	if [ ! -f "$wp_path/wp-config.php" ]; then
		echo "WordPress config is not ready yet; skipping local bootstrap."
		exit 0
	fi
fi

installed=0
attempt=1

while [ "$attempt" -le "$max_attempts" ]; do
	if wp_cli core is-installed >/dev/null 2>&1; then
		installed=1
		break
	fi

	if wp_cli core install \
		--url="$site_url" \
		--title="Markdown View for AI Agents" \
		--admin_user="admin" \
		--admin_password="admin" \
		--admin_email="admin@example.com" \
		--skip-email >/dev/null 2>&1; then
		installed=1
		break
	fi

	sleep 2
	attempt=$((attempt + 1))
done

if [ "$installed" -eq 0 ]; then
	echo "WordPress database bootstrap is not ready yet; skipping local site installation."
	exit 0
fi

ensure_plugin_check_files

wp_cli option update blog_public 0 >/dev/null 2>&1 || true
wp_cli rewrite structure '/%postname%/' >/dev/null 2>&1 || true
wp_cli rewrite flush --hard >/dev/null 2>&1 || true
wp_cli theme activate twentytwentythree >/dev/null 2>&1 || true
wp_cli plugin activate markdown-view-for-ai-agents >/dev/null 2>&1 || true
wp_cli plugin activate plugin-check >/dev/null 2>&1 || true
seed_sample_content

Si, lo sé, es un poco largo y un poco complicado leerlo directamente desde el artículo, pero es básicamente el que me va a permitir que cuando abro el proyecto, en unos segundos tengo un WordPress funcionando con el plugin activado y contenido de prueba para poder probarlo. No tengo que hacer nada manual.

🔍 PHP_CodeSniffer y WordPress Coding Standards

Si quieres subir un plugin al directorio oficial de WordPress.org, el proceso de revisión es bastante estricto. El código tiene que seguir los WordPress Coding Standards. Y para eso, PHP_CodeSniffer es imprescindible.

El proyecto usa Composer para gestionar estas dependencias:

{
  "name": "0gis0/markdown-view-for-agents",
  "description": "Development tooling for the Markdown View for AI Agents WordPress plugin.",
  "type": "project",
  "require": {},
  "require-dev": {
    "dealerdirect/phpcodesniffer-composer-installer": "^1.0",
    "phpcompatibility/phpcompatibility-wp": "^2.1",
    "squizlabs/php_codesniffer": "^3.10",
    "wp-coding-standards/wpcs": "^3.1"
  },
  "config": {
    "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true
    },
    "sort-packages": true
  },
  "scripts": {
    "lint": "phpcs",
    "lint:php": "phpcs --standard=phpcs.xml.dist"
  }
}

Y el archivo phpcs.xml.dist define las reglas que se aplican al proyecto:

<?xml version="1.0"?>
<ruleset name="Markdown View for AI Agents">
  <description>PHP quality and security checks for the plugin.</description>

  <file>markdown-view-for-ai-agents.php</file>
  <file>includes</file>

  <exclude-pattern>vendor/*</exclude-pattern>
  <exclude-pattern>dist/*</exclude-pattern>
  <exclude-pattern>.wordpress-org/*</exclude-pattern>
  <exclude-pattern>.github/*</exclude-pattern>

  <arg name="basepath" value="."/>
  <arg name="extensions" value="php"/>
  <arg value="sp"/>

  <config name="testVersion" value="7.4-"/>

  <rule ref="WordPress-Core"/>
  <rule ref="WordPress-Docs"/>
  <rule ref="WordPress-Extra"/>
  <rule ref="WordPress.Security"/>
  <rule ref="PHPCompatibilityWP"/>

  <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
    <properties>
      <property name="prefixes" type="array">
        <element value="md_for_agents"/>
      </property>
    </properties>
  </rule>

  <rule ref="WordPress.WP.EnqueuedResourceParameters.NotInFooter">
    <exclude name="WordPress.WP.EnqueuedResourceParameters.MissingVersion"/>
  </rule>
</ruleset>

Al principio es frustrante porque te marca cosas que parecen menores (como el formato de los comentarios o los espacios dentro de los paréntesis), pero te fuerza a escribir código limpio y consistente. Y sobre todo, te ahorra que te rechacen el plugin en la revisión 😅.

Todo esto se instala con composer install que forma parte del postCreateCommand del Dev Container. Así que al abrir el proyecto ya tienes el linter configurado y listo para usar.

🎣 Git Hooks

Igual que en el artículo sobre pre-commit hooks en Java, aquí también he configurado un pre-commit hook que ejecuta PHP_CodeSniffer automáticamente antes de cada commit. Si el código no pasa el linter, el commit se bloquea:

#!/usr/bin/env bash

set -euo pipefail

if ! command -v php >/dev/null 2>&1; then
  echo "PHP is not installed. Skipping PHP pre-commit checks."
  exit 0
fi

staged_php_files="$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.php$' || true)"

if [[ -z "$staged_php_files" ]]; then
  echo "No staged PHP files."
  exit 0
fi

echo "Running PHP syntax checks on staged files..."
while IFS= read -r file; do
  [[ -z "$file" ]] && continue
  php -l "$file" >/dev/null
done <<< "$staged_php_files"

if [[ -x "vendor/bin/phpcs" ]]; then
  echo "Running PHPCS on staged files..."
  vendor/bin/phpcs --standard=phpcs.xml.dist $staged_php_files
else
  echo "PHPCS is not installed. Run 'composer install' to enable quality and security checks."
fi

El hook vive en .githooks/ y se instala con el script install-git-hooks.sh, que también se ejecuta como parte del setup del Dev Container. Así, al clonar y abrir el proyecto, los hooks ya están activos. Los desarrolladores no tienen que hacer nada manual.

🔄 GitHub Actions

Pero no se trata solo de validar en local. Para mí es igual de importante que estas mismas reglas se ejecuten en el CI, de forma que todo el código que llegue al repositorio siga exactamente el mismo estilo y formato. Si el lint pasa en tu máquina pero no se valida en el pipeline, al final cada uno acaba formateando como quiere y las reglas se convierten en papel mojado.

Así que el repositorio también tiene un workflow de CI en GitHub Actions que ejecuta PHP_CodeSniffer en cada push y pull request. Las mismas reglas, el mismo resultado.

💡 Lo que aprendí

Algunas cosas que me llevo:

WP-CLI es imprescindible en el Dev Container. Poder instalar WordPress, activar plugins, crear contenido de prueba y configurar permalinks desde un script automatizado hace que el setup sea completamente hands-off.

El bind mount del plugin es la clave. Montar el directorio del proyecto directamente en wp-content/plugins/ elimina cualquier fricción entre el código que editas y lo que WordPress ejecuta.

El readme.txt de WordPress.org no es un README normal. Tiene un formato específico con secciones predefinidas que el directorio parsea para mostrar la información del plugin. Es diferente del README.md de GitHub, así que necesitas mantener los dos.

PHP_CodeSniffer con WordPress Coding Standards es estricto pero necesario. Te fuerza a escribir código limpio y consistente desde el primer momento. Y tenerlo integrado en el Dev Container, en los git hooks y en el CI hace que no haya escapatoria 😄.

🚀 Cómo probarlo

Si quieres usar esta misma configuración para tu propio plugin de WordPress, puedes echar un vistazo a cómo lo tengo montado en el repositorio:

👉 github.com/0GiS0/markdown-view-for-agents

Clona el repo, ábrelo en VS Code y te preguntará si quieres reabrir el proyecto en el contenedor. Acepta y en unos minutos tendrás un WordPress funcionando con el plugin listo para probar. También puedes abrirlo directamente en GitHub Codespaces desde el repositorio, sin necesidad de tener Docker instalado en tu máquina. Si quieres saber más sobre Codespaces aquí tienes otro vídeo de mi canal de YouTube 😊

Y ahora crucemos los dedos a ver si me aceptan el plugin 🤞🏻

¡Nos vemos 👋🏻!

La entrada Mi configuración de Dev Container para desarrollar plugins de WordPress se publicó primero en return(GiS);.

Después de haber estado afinando mis dev containers para Spring Boot y Quarkus, esta vez me dio por investigar otra pieza importante del workflow de desarrollo: los pre-commit hooks.

En muchos proyectos es bastante habitual usar como herramienta pre-commit, el framework escrito en Python que permite ejecutar checks automáticos antes de hacer un commit. Funciona muy bien y es extremadamente popular… pero tiene un pequeño inconveniente en el contexto Java: introduce una dependencia externa que realmente no necesitamos. Y cuando estamos trabajando con Dev Containers, y por extensión con contenedores, cuanto más pequeña sea la imagen mejor que mejor. Si no sabes de qué va esto de los Dev Containers te dejo este vídeo que grabé hace tiempo para mi canal de YouTube:

Por lo que en este caso mi objetivo era claro 🎯: conseguir pre-commit hooks en proyectos Java sin obligar a nadie a instalar Python, o tener que incluirlo en la configuración del Dev Container, solo para ejecutar unas validaciones básicas de formato o estilo de código.

Pero no se trata solo de validar en local. Para mí es igual de importante que estas mismas reglas se ejecuten en el CI, de forma que todo el código que llegue al repositorio siga exactamente el mismo estilo y formato. Si el lint pasa en tu máquina pero no se valida en el pipeline, al final cada uno acaba formateando como quiere y las reglas se convierten en papel mojado.

Así que en este artículo te cuento cómo he configurado pre-commit hooks usando Spotless, Checkstyle y Gradle, de forma que podamos validar automáticamente el código antes de cada commit manteniéndonos completamente dentro del ecosistema Java.

📝 Modificar el archivo build.gradle

Lo primero que he necesitado hacer a sido modificar el archivo build.gradle que ya conoces, para poder instalar un par de plugins: checkstyle y com.diffplug.spotless:

plugins {
    id 'java'
    id 'checkstyle'                              // Plugin nativo de Gradle
    id 'com.diffplug.spotless' version '7.0.2'  // Formateo automático
}

Después en este mismo archivo, necesitas añadir el siguiente bloque:

spotless {
    java {
        target 'src/*/java/**/*.java'
        googleJavaFormat('1.25.2')      // Formateador de Google
        removeUnusedImports()
        importOrder('java', 'javax', 'jakarta', '', 'com.tuempresa')
        trimTrailingWhitespace()
        endWithNewline()
    }

    format 'misc', {
        target '*.md', '*.yml', '*.yaml', '*.properties', '*.gradle', '.gitignore'
        trimTrailingWhitespace()
        endWithNewline()
    }
}

Con este conseguimos:

• Un formato consistente usando Google Java Format
• Eliminación automática de imports no usados
• Un orden homogéneo de imports
• Archivos sin espacios sobrantes
• Aplicar las mismas reglas a ficheros no Java

Y ahora el bloque de Checkstyle:

checkstyle {
    toolVersion = '10.21.4'
    configFile = file("${rootDir}/config/checkstyle/checkstyle.xml")
    ignoreFailures = false
    maxWarnings = 0
}

Esto fuerza a que:

• Las reglas vivan dentro del repositorio
• Se use una versión concreta de Checkstyle
• El build falle ante cualquier warning

💄 Configuración de Checkstyle (config/checkstyle)

Para Checkstyle he creado un directorio específico dentro del proyecto:

config/
└── checkstyle/
    ├── checkstyle.xml
    └── suppressions.xml

Aquí es donde definimos las reglas principales:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">

<!--
    Checkstyle configuration based on Google Java Style Guide (simplified).
    Full guide: https://google.github.io/styleguide/javaguide.html

    Note: Formatting is handled by Spotless (google-java-format).
    This config focuses on naming conventions, best practices, and code quality.
-->
<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="severity" value="error"/>
    <property name="fileExtensions" value="java"/>

    <!-- Suppressions for test files (allow snake_case method names) -->
    <module name="SuppressionFilter">
        <property name="file" value="${config_loc}/suppressions.xml"/>
    </module>

    <!-- Suppress checks on generated sources -->
    <module name="BeforeExecutionExclusionFileFilter">
        <property name="fileNamePattern" value=".*[\\/]build[\\/].*"/>
    </module>

    <!-- File-level checks -->
    <module name="FileTabCharacter">
        <property name="eachLine" value="true"/>
    </module>

    <module name="LineLength">
        <property name="max" value="120"/>
        <property name="ignorePattern" value="^package.*|^import.*|a]* href|href|http://|https://|ftp://"/>
    </module>

    <module name="TreeWalker">
        <!-- ========== Naming Conventions ========== -->
        <module name="PackageName">
            <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
        </module>

        <module name="TypeName">
            <property name="format" value="^[A-Z][a-zA-Z0-9]*$"/>
        </module>

        <module name="MethodName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="MemberName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="ParameterName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="LocalVariableName">
            <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
        </module>

        <module name="ConstantName">
            <property name="format" value="^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
        </module>

        <!-- ========== Imports ========== -->
        <module name="AvoidStarImport"/>
        <module name="RedundantImport"/>
        <module name="UnusedImports"/>

        <!-- ========== Code Quality ========== -->
        <module name="EqualsHashCode"/>
        <module name="SimplifyBooleanExpression"/>
        <module name="SimplifyBooleanReturn"/>
        <module name="StringLiteralEquality"/>
        <module name="NestedTryDepth">
            <property name="max" value="2"/>
        </module>

        <!-- ========== Best Practices ========== -->
        <module name="OneStatementPerLine"/>
        <module name="MultipleVariableDeclarations"/>
        <module name="MissingSwitchDefault"/>
        <module name="DefaultComesLast"/>
        <module name="FallThrough"/>

        <!-- ========== Modifiers ========== -->
        <module name="ModifierOrder"/>
        <module name="RedundantModifier"/>

        <!-- ========== Annotations ========== -->
        <module name="MissingOverride"/>

        <!-- ========== Whitespace (complementary to Spotless) ========== -->
        <module name="NoWhitespaceAfter">
            <property name="tokens" value="AT,INC,DEC,UNARY_MINUS,UNARY_PLUS,BNOT,LNOT,DOT,ARRAY_DECLARATOR,INDEX_OP"/>
        </module>
        <module name="NoWhitespaceBefore"/>
    </module>
</module>

Está basado en la Google Java Style Guide, pero simplificado y con una idea clara:

Checkstyle valida, Spotless formatea. Y sí, es XML y parece sacado de los 90… pero es lo que hay 😄

El fichero incluye:

• Convenciones estrictas de nombres
• Control de imports
• Reglas de calidad de código
• Buenas prácticas
• Exclusión de código generado

Luego por otro lado tengo otro archivo llamado supressions.xml por si hay de alguna cosa de la que no quiero que se queje:

<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
    "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
    "https://checkstyle.org/dtds/suppressions_1_2.dtd">

<!--
    Checkstyle suppressions for test files.
    Allows snake_case method names in tests (common pattern: methodName_shouldDoSomething).
-->
<suppressions>
    <!-- Allow underscores in test method names (e.g., givenX_whenY_thenZ pattern) -->
    <suppress checks="MethodName" files=".*Test\.java$"/>
    <suppress checks="MethodName" files=".*IT\.java$"/>
</suppressions>

🎣 Script del pre-commit hook

Aquí es donde echo un poco de menos herramientas como pre-commit o Husky 🥲, porque en este caso toca crear el hook a mano.

El script vive en gradle/hooks/pre-commit:

#!/bin/bash
# =============================================================================
# Pre-commit hook for Sports Events Service
# Installed automatically by: ./gradlew installGitHooks
# =============================================================================

set -e

echo "🔍 Running pre-commit checks..."

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Get only staged Java files
STAGED_JAVA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.java$' || true)

if [ -z "$STAGED_JAVA_FILES" ]; then
    echo -e "${YELLOW}No Java files staged for commit. Skipping Java checks.${NC}"
else
    # Check formatting with Spotless
    echo "📝 Checking code formatting (Spotless)..."
    if ! ./gradlew spotlessCheck --quiet 2>/dev/null; then
        echo -e "${RED}❌ Code formatting issues found!${NC}"
        echo -e "${YELLOW}Run './gradlew spotlessApply' to fix formatting automatically.${NC}"
        exit 1
    fi
    echo -e "${GREEN}✓ Code formatting OK${NC}"

    # Run Checkstyle
    echo "🔍 Checking code style (Checkstyle)..."
    if ! ./gradlew checkstyleMain checkstyleTest --quiet 2>/dev/null; then
        echo -e "${RED}❌ Checkstyle violations found!${NC}"
        echo "Check the report at: build/reports/checkstyle/"
        exit 1
    fi
    echo -e "${GREEN}✓ Checkstyle OK${NC}"
fi

# =============================================================================
# Agentic Workflows Validation
# Compile .md workflows in .github/workflows/ to ensure they are valid
# =============================================================================

# Get staged workflow markdown files
STAGED_WORKFLOW_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '^\.github/workflows/.*\.md$' || true)

if [ -z "$STAGED_WORKFLOW_FILES" ]; then
    echo -e "${YELLOW}No agentic workflow files staged. Skipping workflow validation.${NC}"
else
    echo "🤖 Validating agentic workflows..."
    
    # Check if gh aw is available
    if ! command -v gh &> /dev/null || ! gh aw --help &> /dev/null; then
        echo -e "${RED}❌ GitHub CLI with Agentic Workflows extension not found!${NC}"
        echo -e "${YELLOW}Install it with: gh extension install github/gh-aw${NC}"
        exit 1
    fi
    
    # Compile each staged workflow file
    for workflow in $STAGED_WORKFLOW_FILES; do
        echo "  Compiling: $workflow"
        if ! gh aw compile "$workflow" > /dev/null 2>&1; then
            echo -e "${RED}❌ Workflow compilation failed: $workflow${NC}"
            echo -e "${YELLOW}Run 'gh aw compile $workflow' to see errors.${NC}"
            exit 1
        fi
    done
    echo -e "${GREEN}✓ Agentic workflows OK${NC}"
fi

echo -e "${GREEN}✅ All pre-commit checks passed!${NC}"
exit 0

Y hace lo siguiente:

• Detecta si hay archivos Java en staging
• Ejecuta spotlessCheck
• Ejecuta checkstyleMain y checkstyleTest
• Bloquea el commit si algo falla

Además de todo esto estoy lanzando la herramienta gh aw para forzar la compilación de mis flujos agenticos de GitHub, que era uno de los motivos principales de querer todo esto 😇

🔄 Instalación automática del pre-commit hook

El último paso es instalar este script automáticamente usando Gradle:

// ============================================================================
// Git Hooks Installation
// ============================================================================

tasks.register('installGitHooks', Copy) {
    description = 'Installs pre-commit hooks into .git/hooks'
    group = 'git hooks'

    from("${rootDir}/gradle/hooks/") {
        include 'pre-commit'
    }
    into "${rootDir}/.git/hooks"
    filePermissions {
        user {
            read = true
            write = true
            execute = true
        }
        group {
            read = true
            execute = true
        }
        other {
            read = true
            execute = true
        }
    }
}

// Auto-install hooks on first build
tasks.named('compileJava') {
    dependsOn 'installGitHooks'
}

¿Qué conseguimos con esto?

• El hook se copia automáticamente a .git/hooks
• Tiene permisos de ejecución (755)
• Se instala en cualquier build
• Los desarrolladores no tienen que hacer nada manual
• Al clonar y compilar, los hooks ya están activos

Instalación manual si hiciera falta:

./gradlew installGitHooks  # Instalar/reinstalar hooks manualmente

y si quieres ver qué tareas tienes disponibles:

./gradlew tasks --group "git hooks"  # Ver tasks de hooks

¡Nos vemos 👋🏻!

La entrada Pre-commit hooks en Java sin Python: Spotless + Checkstyle + Gradle se publicó primero en return(GiS);.

Pero… ¿y si tu framework preferido no es Spring Boot sino Quarkus?
Entonces este artículo es para ti 😉

En esta ocasión quiero compartir la configuración de Dev Container que estoy utilizando para proyectos con Quarkus. 🚨 Aviso: me ha dado un poquito más de guerra que la de Spring Boot, pero después de varios ajustes, esta es la que estoy usando ahora mismo y me funciona perfectamente.

🎥 Antes de entrar en la configuración, si todavía no estás familiarizado con Dev Containers o quieres ver cómo los uso en mi día a día con Visual Studio Code, te dejo por aquí un vídeo donde lo explico paso a paso 👇🏻

📁 .devcontainer/devcontainer.json

Esta es la configuración completa del Dev Container:

{
  "name": "Quarkus Dev Environment",
  "dockerComposeFile": "compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "customizations": {
    "vscode": {
      "extensions": [
        "redhat.java",
        "vscjava.vscode-java-pack",
        "vscjava.vscode-gradle",
        "redhat.vscode-quarkus",
        "redhat.vscode-microprofile",
        "redhat.vscode-yaml",
        "mtxr.sqltools",
        "mtxr.sqltools-driver-pg",
        "ms-azuretools.vscode-docker",
        "humao.rest-client"
      ],
      "settings": {
        "java.configuration.updateBuildConfiguration": "automatic",
        "java.server.launchMode": "Standard",
        "quarkus.tools.starter.api.base": "https://code.quarkus.io",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
          "source.organizeImports": "explicit"
        },
        "[java]": {
          "editor.defaultFormatter": "redhat.java"
        },
        "sqltools.connections": [
          {
            "name": "🐘 Sports DB (PostgreSQL)",
            "driver": "PostgreSQL",
            "server": "localhost",
            "port": 5432,
            "database": "sports_db",
            "username": "sports_user",
            "password": "sports_pass"
          }
        ]
      }
    }
  },
  "forwardPorts": [
    8080,
    5432
  ],
  "portsAttributes": {
    "8080": {
      "label": "🚀 Quarkus App",
      "onAutoForward": "notify"
    },
    "5432": {
      "label": "🐘 PostgreSQL",
      "onAutoForward": "silent"
    }
  },
  "remoteEnv": {
    "JAVA_HOME": "/usr/lib/jvm/msopenjdk-current"
  },
  "remoteUser": "vscode",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {
      "installDirectlyFromGitHubRelease": true,
      "version": "latest"
    },
    "ghcr.io/devcontainers-extra/features/quarkus-sdkman:2": {
      "version": "latest",
      "jdkVersion": "none",
      "jdkDistro": "ms"
    },
    "ghcr.io/devcontainers/features/java:1": {
      "installGradle": true,
      "version": "none",
      "jdkDistro": "ms",
      "gradleVersion": "8.10.2"
    }
  }
}

🐳 Docker Compose: aplicación + base de datos

En este caso estoy utilizando Docker Compose porque mi entorno está formado por dos contenedores:

• 🧩 Aplicación Quarkus
• 🐘 Base de datos PostgreSQL

services:
  app:
    image: mcr.microsoft.com/devcontainers/java:21-bookworm
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
    network_mode: service:db
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: sports_user
      POSTGRES_PASSWORD: sports_pass
      POSTGRES_DB: sports_db
    ports:
      - "5432:5432"
      - "8080:8080"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sports_user -d sports_db"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

De esta forma consigo que todas las dependencias necesarias para el desarrollo formen parte del entorno, sin tener que instalar nada en local. En este ejemplo solo tengo una base de datos, pero el patrón escala muy bien si mañana necesitas Redis, Kafka o cualquier otro servicio.

🧩 Extensiones y settings de VS Code

Como parte del Dev Container incluyo varias extensiones clave:

• Soporte completo para Java y Gradle
• Extensiones específicas de Quarkus y MicroProfile
• SQLTools para conectar directamente a PostgreSQL
• Docker, REST Client y YAML

Además, dejo preconfiguradas algunas settings útiles, como:

• Formateo automático al guardar
• Organización explícita de imports
• Conexión directa a la base de datos desde VS Code

Todo listo para empezar a trabajar nada más abrir el repositorio 🚀

🔌 Puertos y forwarding

También configuro explícitamente los puertos que necesito:

• 8080 → Aplicación Quarkus 🚀
• 5432 → PostgreSQL 🐘

Incluyendo etiquetas y comportamiento al auto-forward para que la experiencia sea más limpia y visual dentro de VS Code.

🧠 Por qué tuve que configurar JAVA_HOME en remoteEnv

En mi caso fue necesario definir explícitamente la variable de entorno JAVA_HOME dentro de la sección remoteEnv del Dev Container.

El motivo es que la feature quarkus-sdkman instala SDKMAN y configura automáticamente JAVA_HOME apuntando a la siguiente ruta:

/usr/local/sdkman/candidates/java/current

Sin embargo, en esta configuración no estoy instalando el JDK vía SDKMAN, ya que el JDK viene ya preinstalado en la imagen base de Microsoft (mcr.microsoft.com/devcontainers/java:21-bookworm).
Esto hace que ese symlink no exista realmente en el contenedor.

👉 Como consecuencia, herramientas como Gradle o Quarkus intentan usar un JAVA_HOME que apunta a una ruta inexistente y la ejecución falla.

La solución es sencilla: forzar JAVA_HOME a la ubicación real del JDK que trae la imagen base:

/usr/lib/jvm/msopenjdk-current

Con este override me aseguro de que todas las herramientas Java utilizan el JDK correcto y el entorno funciona de forma estable y predecible.

⚠️ Muy importante: Quarkus debe escuchar en todas las interfaces

Puede que hayas llegado hasta aquí con tu propia configuración y que, al arrancar la aplicación, te hayas encontrado con un timeout al intentar acceder desde el navegador.

Esto es muy habitual y tiene una causa clara:
👉 Quarkus, por defecto, no escucha en todas las interfaces de red.

La solución es sencilla. Solo tienes que añadir esta línea en tu application.properties:

# HTTP configuration - escuchar en todas las interfaces
quarkus.http.host=0.0.0.0

Con esto, tu aplicación será accesible correctamente desde tu máquina local, sin ensuciar tu entorno ni instalar nada en local 🎉

¡Nos vemos 👋🏻!

La entrada Desarrollando con Quarkus en VS Code usando Dev Containers se publicó primero en return(GiS);.

Uno de los vídeos que más ha gustado de mi canal de YouTube es el que habla sobre Dev Containers y cómo pueden hacernos la vida mucho más sencilla. La idea es clara: contenerizar todo nuestro entorno de desarrollo y olvidarnos, de una vez por todas, del caos de tecnologías, lenguajes, versiones y dependencias con el que convivimos hoy en día.

Si todavía no lo has visto, o no sabes de qué te estoy hablando, puedes acceder al vídeo desde aquí 👇🏻

A raíz de ese contenido —y también por otras vías 🥲— varias personas me han pedido si podía compartir una configuración de Dev Container para Java. Cada vez sois más quienes estáis utilizando VS Code como entorno de desarrollo también para este lenguaje, pero es cierto que al principio puede costar un poco dejar la configuración fina.

Durante estos días he estado trasteando tanto con Spring Boot como con Quarkus y, como no podía ser de otra manera, he terminado creando mis propias configuraciones de Dev Containers para ambos frameworks, cada uno con sus… particularidades 🙃

En este artículo vamos a empezar por Spring Boot, que ha sido la parte más sencilla. En un próximo artículo te contaré la configuración de Quarkus, que me ha dado un poquito más de guerra 😅

🍃 Configuración de Dev Containers para Spring Boot

Vamos a empezar por la fácil. La configuración de Spring Boot no me ha dado demasiados problemas y tiene un aspecto como el siguiente:

{
	"name": "🍃 Spring Boot Dev Environment",
	"dockerComposeFile": "docker-compose.yml",
	"service": "app",
	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",

	"features": {
		"ghcr.io/devcontainers/features/java:1": {
			"version": "none",
			"installMaven": "false",
			"installGradle": "true"
		},
		"ghcr.io/devcontainers/features/github-cli:1": {}
	},

	// 🐘 PostgreSQL is available at localhost:5432
	"forwardPorts": [8080, 5432],
	"portsAttributes": {
		"8080": { "label": "🚀 Spring Boot App" },
		"5432": { "label": "🐘 PostgreSQL" }
	},

	// ✅ Wait for DB to be ready before running commands
	"postCreateCommand": "echo '🐘 PostgreSQL ready at localhost:5432 | 🗄️ DB: sports_db | 👤 User: postgres'",

	"customizations": {
		"vscode": {
			"extensions": [
				"vscjava.vscode-java-pack",
				"vmware.vscode-spring-boot",
				"mtxr.sqltools",
				"mtxr.sqltools-driver-pg",
				"vmware.vscode-boot-dev-pack"
			],
			"settings": {
				"java.compile.nullAnalysis.mode": "automatic",
				"java.jdt.ls.java.home": "/usr/lib/jvm/msopenjdk-current",
				"java.configuration.runtimes": [
					{
						"name": "JavaSE-21",
						"path": "/usr/lib/jvm/msopenjdk-current",
						"default": true
					}
				],
				"java.import.gradle.java.home": "/usr/lib/jvm/msopenjdk-current"
			}
		}
	}
}

Como puedes ver, estoy delegando la creación de los contenedores en Docker Compose, ya que mi entorno está compuesto por dos contenedores:

• Uno para la aplicación en Spring Boot
• Otro para la base de datos PostgreSQL (que podrías cambiar sin problema por cualquier otra)

La configuración de docker-compose.yml es la siguiente:

# 🐳 Docker Compose configuration for local development

services:
  # ☕ Java Development Container
  app:
    image: mcr.microsoft.com/devcontainers/java:1-21-bullseye
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity
    network_mode: service:db
    depends_on:
      db:
        condition: service_healthy

  # 🐘 PostgreSQL Database
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: sports_db
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d sports_db"]
      interval: 5s
      timeout: 5s
      retries: 5

# 💾 Persistent volumes
volumes:
  postgres-data:

La configuración es bastante sencilla, pero si no tienes claro cómo funciona Docker Compose, te recomiendo este otro vídeo que grabé como parte de mi curso de Docker en YouTube 👀

Detalles importantes del Dev Container

Si vuelves a la configuración del devcontainer.json, hay algunos puntos interesantes a destacar.

Features

He añadido dos features principales:

• Java: no reinstalo Java porque la imagen que uso para el contenedor de la app ya viene con Java 21, pero sí aprovecho esta feature para instalar Gradle, que es la herramienta que suelo utilizar siempre que puedo 😅
• GitHub CLI: mis repos están en GitHub, así que tener gh dentro del contenedor me facilita muchísimo la autenticación y la interacción con el repositorio directamente desde el Dev Container.

Port forwarding

Hago forwarding de:

• 8080 → la aplicación Spring Boot
• 5432 → la base de datos PostgreSQL

Además, añado etiquetas descriptivas para que desde la pestaña de Ports de VS Code sea muy fácil identificar qué es cada cosa.

🚨 Importante 🚨 Para poder acceder a tu aplicación debes utilizar http://127.0.0.1:8080 en lugar de localhost. De lo contrario te dará timeout.

Extensiones de VS Code

Por último, incluyo una serie de extensiones que considero básicas para trabajar cómodamente con Spring Boot:

• Extension Pack for Java: Pack esencial con soporte de lenguaje, debugging, testing, gestión de proyectos Maven/Gradle e IntelliSense.
• Spring Boot Tools: Navegación inteligente, validación y autocompletado de application.properties / application.yml, y soporte para Live Application Information.
• Spring Boot Extension Pack: Pack de VMware que agrupa Spring Boot Tools, Spring Initializr y Spring Boot Dashboard para una experiencia completa.
• SQLTools: Cliente SQL integrado en VS Code para conectarse a la base de datos, ejecutar queries y explorar tablas.
• SQLTools PostgreSQL/Cockroach Driver:Driver necesario para conectarse a la base de datos PostgreSQL incluida en el Dev Container.

🔧 Settings adicionales

También he tenido que agregar unas settings adicionales a la configuración, para que las extensiones, especialmente por la de Gradle for Java, apunten a la ruta correcta para Java Home, porque de lo contrario no encontraba correctamente el SDK.

Si eres fan de Spring Boot y quieres empezar a trabajar con Dev Containers, aquí tienes todo lo que necesitas para ponerte en marcha 🚀
Y si echas algo en falta, ¡déjamelo en los comentarios! 👇🏻

En los próximos días te compartiré la configuración de Dev Containers para Quarkus 😉

¡Nos vemos! 👋🏻

La entrada Mi configuración de Dev Container para Spring Boot se publicó primero en return(GiS);.

👉 En cuanto el vídeo esté publicado, lo enlazaré directamente en este artículo.

Y casi al mismo tiempo, ayer se anunció la disponibilidad en technical preview de una nueva iniciativa para crear flujos agénticos automatizados apoyados en GitHub Actions… pero no exactamente de la forma que quizá esperabas.

No, no estamos hablando (todavía 😏) de integrar directamente GitHub Copilot CLI dentro de los workflows —de eso hablaremos en el vídeo de la semana que viene —, sino de algo bastante diferente y, en mi opinión, muy potente:
👉 definir workflows usando Markdown, olvidándote (en gran parte) de escribir YAML a mano como veníamos haciendo hasta ahora.

En este artículo te cuento:

• Qué es esta nueva aproximación
• Qué necesitas instalar
• Cómo crear tu primer flujo agéntico
• Y cómo funciona la “magia” por debajo ✨

🎥 Antes de seguir: cómo funcionaba GitHub Actions hasta ahora

Antes de entrar en este nuevo enfoque, es importante tener claro cómo hemos estado definiendo workflows en GitHub Actions hasta hoy.

Si necesitas refrescar conceptos o entender bien la base sobre la que se construye todo esto, tengo una playlist completa en YouTube sobre GitHub Actions “clásicos” 🤭, definidos en YAML.

👉 En esa playlist explico:

• Cómo funciona GitHub Actions por dentro
• Triggers, jobs y steps
• Cómo se estructura un workflow en YAML
• Patrones habituales y buenas prácticas

📺 Playlist: GitHub Actions desde cero (enfoque tradicional)

💡 Precisamente por eso este artículo es interesante:
todo lo que ves en esa playlist sigue siendo válido, pero ahora aparece una nueva capa que nos permite definir workflows de forma más declarativa y agéntica, sin escribir directamente el YAML.

Y ahora sí, vamos al lío 👇

🧠 ¿Qué es un flujo agéntico en GitHub Actions?

Hasta ahora, cuando queríamos automatizar algo en GitHub Actions, lo normal era definir un workflow en YAML: eventos, jobs, pasos, condiciones, permisos… todo de forma bastante explícita.

Con esta nueva iniciativa en technical preview, la idea cambia ligeramente.

En lugar de describir cómo debe ejecutarse cada paso, pasamos a describir qué queremos que ocurra.

La base es sencilla:

• Creas un archivo Markdown
• En ese archivo defines la intención del flujo
• Describes las tareas que debe realizar
• Y GitHub se encarga de generar el workflow real por debajo

Es decir, el YAML sigue existiendo, pero deja de ser algo que tengas que escribir y mantener a mano.

Este enfoque encaja especialmente bien con flujos más agénticos, donde lo importante no es tanto la secuencia exacta de pasos, sino el objetivo final y las reglas que deben cumplirse.

🧩 Requisitos previos: GitHub CLI + extensión aw

Para crear este tipo de flujos no basta con añadir un .md dentro de .github/workflows.
Antes necesitas preparar tu entorno local.

1️⃣ Instalar GitHub CLI

Si no lo tienes ya, instala GitHub CLI.
En macOS, por ejemplo:

brew install gh

2️⃣ Instalar la extensión aw (Agentic Workflows)

Esta nueva funcionalidad vive en una extensión llamada aw.

gh extension install github/gh-aw

Si este comando falla y ves un error como:

X Could not find extension 'github/gh-aw' on host github.com

puedes instalarla manualmente así:

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Una vez hecho esto, ya estás list@ para crear y compilar workflows agénticos 🎉

🤖 Un flujo agéntico para GitHub Actions (ejemplo práctico)

Vamos a verlo con un ejemplo sencillo y muy realista.

👉 Imagina que alguien crea un Issue “de aquella manera”
👉 Quieres que automáticamente se mejore: formato, idioma, claridad, labels…

Para ello he creado este archivo dentro de mi repositorio: .github/workflows/issue-quality-enhancer.md con el siguiente contenido:

---
on:
  issues:
    types: [opened]

permissions:
  issues: read

safe-outputs:
  update-issue:
    title:
    body:

tools:
  github:
    toolsets: [issues]
---

# Issue Quality Enhancer

Enhance new issues to make them clear, well-structured, and easy to understand.

## Issue to enhance

| Field  | Value          |
| ------ | -------------- |
| Number | #$ISSUE_NUMBER |
| Author | @$ISSUE_AUTHOR |
| Title  | $ISSUE_TITLE   |
| Body   | $ISSUE_BODY    |

## Your tasks

### 1. Get context

- Read the README to understand the project
- List the repository labels (you'll need them later)

### 2. Translate if needed

- If the issue is NOT in English, translate it to English
- Keep all technical details intact

### 3. Improve the title

Add an emoji prefix based on the issue type:

- 🐛 Bug
- ✨ Feature
- 📝 Docs
- 🔧 Refactor
- ⚡ Performance

Example: `🐛 Fix login error when password contains special characters`

### 4. Restructure the body

Use clear sections with emoji headers:

**For bugs:**

```
## 🐛 Description
## 📋 Steps to Reproduce
## ✅ Expected vs ❌ Actual Behavior
```

**For features:**

```
## ✨ Description
## 🎯 Why is this needed?
## 📐 Proposed Solution
```

### 5. Add footer

```
---
> ✍️ *Enhanced by Copilot. Original author: @$ISSUE_AUTHOR*
```

### 6. Apply changes

- **Update** issue #$ISSUE_NUMBER with the new title and body
- **Assign** 1-3 relevant labels
- **Comment** with a brief summary of improvements

## Rules

- Never change the original meaning
- If already well-written, make minimal changes
- Keep it helpful, not verbose

📌 Importante: aquí no estamos escribiendo YAML, estamos describiendo el comportamiento esperado del flujo.

Si lo revisamos detenidamente encontramos:

• Como en cualquier otro flujo, necesito indicarle cuándo se va a ejecutar el mismo a través de la propiedad on. Esto es casi igual que un flujo de GitHub Actions convencional.
• La sección de permissions se combiba con la de safe-outputs para limitar el scope del agente, es decir qué puede hacer.
• Como cualquier otro agente de IA es posible que necesite usar algunas tools. En este ejemplo estamos usando el MCP server de GitHub pero le tengo restringido únicamente al toolset que tiene que ver con los issues.

De esta forma puedes ver que no puede hacer cualquier cosa pero a la vez facilitarnos la vida 😃

⚙️ Compilar el flujo agéntico

El archivo Markdown que acabamos de crear no es todavía un workflow ejecutable por GitHub Actions.

Antes, es necesario un paso intermedio: compilar el flujo.

Al compilarlo, GitHub traduce la intención que hemos definido en Markdown a un workflow real de GitHub Actions, generando automáticamente los archivos necesarios.

Para ello, basta con ejecutar el siguiente comando desde el repositorio:

gh aw compile

Tras ejecutar este comando, verás que ocurren varias cosas:

• Se crea un nuevo directorio .github/aw
• Se genera un archivo .lock.yml dentro de .github/workflows
• Ese .lock.yml contiene el workflow real en YAML, listo para ser ejecutado por GitHub Actions

🔍 Lo importante aquí es que:

• El YAML sigue existiendo
• GitHub Actions sigue funcionando igual
• Pero tú ya no tienes que escribir ni mantener ese YAML a mano

A partir de este momento, cualquier cambio que hagas en el Markdown y vuelvas a compilar actualizará automáticamente el workflow generado.

🔐 Crear un PAT con scope Copilot Requests para tu repositorio

Estos flujos hacen uso de tu suscripción de GitHub Copilot, así que necesitas un Personal Access Token con el permiso adecuado.

Lo único que tienes que hacer es ir a https://github.com/settings/personal-access-tokens/new y crear un token con el scope ✅ Copilot Requests

Puedes configurarlo en tu repositorio con el siguiente comando:

gh aw secrets set COPILOT_GITHUB_TOKEN --value TU_PAT

🧪 Probando el resultado

En mi caso, simplemente creé un Issue con:

• Título: Añadir endpoint para gestionar productos
• Descripción: hacer el CRUD completo

Vamos… bastante justito 😅

En la pestaña Actions puedes ver que el flujo se ejecuta como cualquier otro workflow.

Si te fijas en los pasos, verás que por debajo se apoya en GitHub Copilot CLI, aunque tú no hayas tenido que invocarlo directamente 👀

Y, finalmente…
🎉 el Issue aparece mejorado, estructurado y etiquetado automáticamente.

¡Nos vemos 👋🏻!
(y ojo al vídeo de la semana que viene 😉)

La entrada 🤖🚀 GitHub Agentic Workflows: tu primer workflow sin escribir YAML se publicó primero en return(GiS);.

En este artículo te explico cómo funcionan los subagents, qué papel juegan dentro de los flujos agentic y, sobre todo, cómo puedes sacarles partido en escenarios reales. Veremos cómo usarlos tanto desde Visual Studio Code como junto a Coding Agent, y por qué esta capacidad cambia por completo la forma en la que diseñamos agentes más especializados, reutilizables y escalables.

Cómo funciona

Cada vez que creamos un custom agent este por defecto tiene la propiedad infer a true.

---
name: '📺 YouTube'
description: 'Agente que me ayuda a escribir los READMEs de los repositorio que comparto en mis vídeos de YouTube'
infer: true # ⬅️ Esto por defecto es true
---

[...]

Esto lo que significa es que estamos permitiendo que, aunque no elijamos directamente este custom agent, si el contexto lo permite, usamos explícitamente la tool #agent y no hemos forzado a que este infer sea false podamos beneficiarnos de estos custom agents incluso en conversaciones en las que no lo hayamos seleccionado como parte de nuestro combo del chat o incluso cuando hacemos uso de Coding Agent en el cloud.

Si quieres saber más sobre Custom Agents puedes echarle un vistazo a este vídeo de mi canal de YouTube:

Ejemplo en Visual Studio Code

Para que lo veas con un ejemplo sencillo, tengo un custom agent a nivel global llamado 📺 YouTube que me permite dejar mis READMEs lo más bonitos posible para poder compartir el repo con información relevante.

Ahora bien, para que esta característica funcione desde Visual Studio Code necesitas habilitar un check en la configuración que dice «Custom Agent in Subagent«:

Con ello cada ves que pidas una tarea puedes o bien usar la tool #agent para que el agente principal, sea otro custom agent o no, tome ese otro agente como subagent:

O incluso según el contexto de la conversación también puede ser utilizado de forma transparente para ti sin que tengas que añadir nada adicional:

En este ejemplo, como puedes ver en el pantallazo, estoy usando el modo Agente que viene de caja pero aún así está delegando esta tarea en mi subagent 📺 YouTube.

Ejemplo con Coding Agent

Para este otro ejemplo he creado un issue donde le he pedido a Coding agent que me mejore el README de un proyecto y, como puedes ver en la sesión, se ha dado cuenta de que tengo un custom agent llamado YouTube configurado a nivel de cuenta que me permite hacer lo mismo que en el caso anterior y por lo tanto puede usarlo también del mismo modo.

Y lo chulo de todo esto es que si pido la misma tarea a en otro repositorio:

¡Ahí está de nuevo!

Si quieres saber más sobre dónde puedes configurar tus custom agents puedes echarle un vistazo a este otro vídeo de mi canal 😇

¡Nos vemos 👋🏻!

La entrada Haz que tus custom agents sean subagents de GitHub Copilot se publicó primero en return(GiS);.

En este artículo te voy a enseñar un patrón muy práctico y realista: usar un MCP Server para crear un proxy que permita ejecutar MCP Servers como un servicio HTTP, centralizando además las credenciales (PATs, API Keys, tokens).

Un enfoque especialmente útil para entornos corporativos, Agentic DevOps y agentes compartidos.

🤔 El problema real con muchos MCP Servers

Cuando pasamos de pruebas locales a escenarios reales, suelen aparecer dos grandes frenos.

1️⃣ MCP Servers basados en stdio

Muchos MCP Servers funcionan únicamente vía stdio, lo que implica que:

• ❌ Solo pueden ejecutarse localmente
• ❌ No pueden exponerse directamente como servicios
• ❌ Cada cliente debe lanzar su propio proceso

Esto ya es una limitación importante cuando quieres algo compartido o centralizado. Si tu problema principal no es este, te recomiendo que eches un vistazo a Azure API Management, el cual, como servicio, también permite hacer de proxy de MCP Servers que soporten SSE o Streamable HTTP.

2️⃣ MCP Servers que requieren credenciales (PAT, API Keys, tokens…)

Además, una gran parte de los MCP Servers:

• ❌ Requieren Personal Access Tokens (PAT) u otros secretos
• ❌ Obligan a configurar credenciales en cada cliente
• ❌ Dificultan el uso compartido entre agentes o personas
• ❌ Incrementan el riesgo de fugas de credenciales

Y aquí viene el matiz importante:

👉 Incluso aunque el MCP Server NO use stdio, el simple hecho de requerir credenciales ya complica muchísimo su adopción en equipos y entornos corporativos, especialmente si esas credenciales son diferentes a las corporativas.

Si quieres saber más sobre MCP Servers puedes echarle un vistazo a mi playlist de mi canal de YouTube:

El verdadero problema

El problema real no es solo técnico. Muchos MCP Servers no están pensados para ejecutarse como servicios compartidos, ni desde el punto de vista de ejecución ni de seguridad.

✅ La idea: MCP Server como proxy de otro MCP Server

La solución pasa por desacoplar completamente al cliente MCP del MCP Server real. Ejecutar el MCP Server real en una máquina o contenedor centralizado, y exponerlo vía HTTP, centralizando también las credenciales.

Con este enfoque conseguimos:

• ✅ Ejecutar MCP Servers stdio o no-stdio en un entorno controlado
• ✅ Evitar distribuir PATs, API Keys o tokens a los clientes
• ✅ Acceder desde cualquier cliente MCP vía HTTP
• ✅ Compartir el acceso entre múltiples usuarios o agentes
• ✅ Aplicar políticas de seguridad y autenticación en un único punto
• ✅ Desplegarlo como servicio remoto (VM, contenedor, Kubernetes…)

FastMCP encaja perfectamente como capa de proxy y control, porque además viene integrado como parte del SDK a día de hoy.

🎯 Caso práctico: Azure DevOps MCP Server

En el repositorio uso como ejemplo el Azure DevOps MCP Server, porque concentra los dos problemas más habituales:

1. Usa stdio → no puede exponerse directamente como servicio
2. Requiere un Personal Access Token (PAT) o autenticarse usando Azure CLI.

🏗️ Arquitectura del proxy MCP

El flujo es el siguiente:

• El cliente MCP (Copilot, Claude, VS Code…) habla HTTP
• FastMCP actúa como proxy
• El MCP Server original sigue funcionando como siempre
• Las credenciales viven solo en el servidor, no en los clientes

Esto simplifica muchísimo la arquitectura y mejora la seguridad.

📋 Requisitos

Para ejecutar este ejemplo necesitas:

• Python 3.10+
• Node.js 20+ (en el caso del ejemplo de Azure DevOps)
• Las credenciales necesarias del MCP Server que vayas a hacer de proxy

🚀 Instalación paso a paso

1️⃣ Clonar el repositorio

git clone https://github.com/0GiS0/mcp-server-as-a-proxy.git
cd mcp-server-as-a-proxy

2️⃣ Instalar dependencias

pip install -e .

3️⃣ Configurar variables de entorno

cp .env.example .env

Ejemplo para Azure DevOps:

AZURE_DEVOPS_ORG=tu-organizacion
ADO_MCP_AUTH_TOKEN=tu-personal-access-token

4️⃣ Ejecutar el proxy

python proxy_server.py

El proxy quedará disponible en http://localhost:8080/mcp

🍿 El resultado

⚠️ Importante

Este ejemplo es una PoC para demostrar que técnicamente es posible hacer de proxy de otro MCP Server pero no se ha tenido en cuenta (o si, pero en pensamiento 🥲) la escalabilidad de este escenario. Es decir: en este ejemplo se está lanzado el MCP Server definitivo como un proceso único, lo cual implica que cada petición espera al mismo backend, por lo que sin balanceo de carga no hay distribución de las requests y por lo tanto habría un cuello de botella. Existen varias formas de escalar como ya sabes:

1. Escalar horizontalmente (multiples instancias de esta implemetación)
2. Usar Gunicorn con workers
3. Pool de procesos en backend
4. Kubernetes/container con réplicas

Por otro lado, es importante saber que en general todos los servicios tienen limites en cuanto al número de peticiones que se pueden hacer, normalmente, al minuto usando el mismo PAT por lo que es probable que si estás usando «el mismo para todo» porque no hay alternativa, puedas necesitar múltiples PATs con rotación.

Esta implementación no es la ideal pero en muchos casos a día de hoy es la única medianamente viable.

🔧 Adaptar el proxy a otro MCP Server

Aquí está la clave de todo el patrón.

Usamos StdioTransport (o el transport que necesites) para lanzar el MCP Server real y lo envolvemos con FastMCP.as_proxy:

from fastmcp import FastMCP
from fastmcp.server.proxy import ProxyClient
from fastmcp.client.transports import StdioTransport

transport = StdioTransport(
    command="npx",                    # o python, node, etc.
    args=["-y", "@tu-mcp/server"],
    env={
        "API_KEY": "tu-api-key",
        "OTHER_SECRET": "..."
    }
)

proxy = FastMCP.as_proxy(
    ProxyClient(transport),
    name="MiMCPProxy"
)

if __name__ == "__main__":
    proxy.run(transport="http", host="0.0.0.0", port=8080)

👉 El MCP Server no necesita modificarse.
👉 Las credenciales se quedan en el servidor.
👉 Los clientes solo hablan HTTP.

🔌 Configuración del cliente MCP

VS Code (mcp.json)

{
  "servers": {
    "mi-proxy": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "mi-proxy": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

⚠️ Seguridad: no lo ignores

Este ejemplo no incluye autenticación propia por simplicidad 👉 No lo expongas tal cual en producción.

🔐 Autenticación con Microsoft Entra ID

FastMCP incluye soporte nativo para autenticación con Azure / Entra ID:

from fastmcp.server.auth.providers.azure import AzureProvider

auth_provider = AzureProvider(
    client_id="tu-app-client-id",
    client_secret="tu-client-secret",
    tenant_id="tu-tenant-id",
    base_url="http://localhost:8080",
    required_scopes=["mcp-access"],
)

proxy = FastMCP.as_proxy(
    ProxyClient(transport),
    name="MiProxy",
    auth=auth_provider
)

Ideal para entornos corporativos con control de acceso real.

🧠 Conclusión

Este patrón no va solo de stdio.

Va de algo mucho más importante:

• Centralizar ejecución
• Centralizar credenciales (PATs, API Keys, tokens)
• Evitar configuración local en cada cliente
• Hacer MCP usable de verdad en entornos reales

Con este enfoque puedes:

• Exponer MCP Servers como servicios
• Compartirlos entre agentes
• Proteger secretos
• Integrarlos en infraestructuras corporativas

¡Nos vemos 👋🏻!

La entrada 🔌 MCP Server como Proxy de otro MCP Server se publicó primero en return(GiS);.