"No funciona." Sin versión, sin pasos, sin logs. Si mantienes un repositorio, conoces ese issue. La solución es que GitHub obligue a dar la información antes de enviar: los issue forms, formularios definidos en YAML que sustituyen al cuadro de texto libre.

Dónde van

Los formularios viven en .github/ISSUE_TEMPLATE/ de la rama por defecto, con extensión .yml. Cada archivo es una opción que aparece al pulsar New issue.

.github/ └── ISSUE_TEMPLATE/ ├── bug_report.yml ├── feature_request.yml └── config.yml

Anatomía de un formulario

Un formulario necesita name, description y body. Opcionalmente, title (prefijo del título) y labels (etiquetas que se aplican solas). Este es el inicio de un reporte de error:

name: 🐛 Reporte de error description: Algo no funciona como debería. title: "[Error]: " labels: ["bug", "por-clasificar"] body: - type: textarea id: pasos attributes: label: Pasos para reproducirlo placeholder: | 1. Ejecuta `...` 2. Abre `...` validations: required: true - type: input id: version attributes: label: Versión placeholder: "1.4.2" validations: required: true

Los tipos de campo disponibles son cinco:

  • markdown: texto informativo que no se envía (ideal para instrucciones).
  • input: una línea (versión, URL).
  • textarea: varias líneas. Con render: shell el contenido se formatea como bloque de código, perfecto para logs.
  • dropdown: lista de opciones, con multiple: true si se pueden marcar varias.
  • checkboxes: casillas; cada una puede ser obligatoria.

validations.required: true impide enviar el formulario sin ese campo. Úsalo en lo imprescindible (pasos, versión, resultado esperado) y deja el resto opcional: un formulario demasiado largo hace que la gente abandone.

Cada id debe ser único dentro del formulario. Las etiquetas de labels deberían existir en el repositorio; créalas antes en Issues → Labels.

Un truco para logs 

 - type: textarea id: logs attributes: label: Logs o mensajes de error description: Revisa que no incluya contraseñas ni tokens. render: shell

La advertencia sobre tokens no es decorativa: mucha gente pega su configuración completa sin pensarlo.

config.yml: ordena la entrada

Este archivo no es un formulario; controla la pantalla de selección:

blank_issues_enabled: false contact_links: - name: ❓ Preguntas y ayuda url: https://github.com/USUARIO/REPO/discussions about: Para dudas de uso, abre una discusión en lugar de un issue. - name: 🔒 Reportar una vulnerabilidad url: https://github.com/USUARIO/REPO/security/advisories/new about: Reporta problemas de seguridad de forma privada.

Con blank_issues_enabled: false se oculta la opción de issue en blanco, y los contact_links desvían preguntas y vulnerabilidades a sus canales. El enlace de seguridad funciona si activas Private vulnerability reporting en Settings → Security.

Validar antes de hacer push

Un error de YAML hace que el formulario no aparezca, sin aviso claro. Revisa la sintaxis en local:

python3 -c "import yaml,sys; [yaml.safe_load(open(f)) for f in sys.argv[1:]]; print('OK')" .github/ISSUE_TEMPLATE/*.yml

Después del push, abre New issue en tu repo y prueba cada formulario. Si alguno falta, GitHub suele mostrar el error al abrir el archivo .yml en la interfaz web.

Con esto, tu próximo "No funciona" llegará con versión, pasos y logs.

¿Te sirvió? Este ejemplo es parte de las Plantillas de Documentación para GitHub en Español: paga lo que quieras, desde 1 USD. Más recursos gratis en GitHub.