← Volver al listado de tecnologías ← Índice de Forgejo

Forgejo: Issues - gestion de tareas

28 de febrero de 2026 Por: Artiko

forgejoissueslabelsmilestonestemplatesgestion

Capitulo 9: Issues en Forgejo

El sistema de issues de Forgejo es el centro de coordinacion de un proyecto: desde reportar bugs hasta planificar nuevas funcionalidades. Este capitulo cubre todas sus herramientas.

Crear un issue

Desde la pestana Issues del repositorio, presiona New Issue.

Campos principales

Titulo: describe el problema o la tarea en una linea. Un buen titulo responde “que falla” o “que se necesita”. Ejemplos:

“Error 500 al guardar usuario sin email”
“Agregar soporte para formato CSV en exportacion”

Descripcion: area de texto con soporte completo de Markdown. Incluye:

Pasos para reproducir el problema (en caso de bugs)
Comportamiento esperado vs comportamiento actual
Version del sistema afectado
Capturas de pantalla o logs si aplica

Asignados: uno o mas usuarios responsables de resolver el issue. Solo pueden ser asignados quienes tienen acceso al repositorio.

Labels: etiquetas de clasificacion. Ver la seccion siguiente.

Milestone: agrupa el issue dentro de un conjunto de trabajo con fecha limite.

Labels

Los labels permiten clasificar y filtrar issues rapidamente.

Labels por defecto

Forgejo crea los siguientes labels al inicializar el sistema de issues de un repositorio:

Label	Color	Uso tipico
bug	Rojo	Algo no funciona correctamente
enhancement	Azul	Nueva funcionalidad o mejora
question	Violeta	Pregunta o solicitud de informacion
documentation	Blanco	Mejoras en la documentacion
good first issue	Verde	Apto para nuevos colaboradores
help wanted	Verde claro	Se necesita ayuda de la comunidad
invalid	Gris	Issue incorrecto o fuera de scope
wontfix	Blanco	No se corregira intencionalmente
duplicate	Gris claro	Ya existe otro issue igual

Crear labels personalizados

Ve a Issues > Labels
Presiona Create Label
Ingresa nombre y selecciona un color (con el selector o en formato hexadecimal)
Guarda

Tambien puedes crear labels a nivel de organizacion para reutilizarlos en todos los repositorios.

Gestionar labels desde la linea de comandos (API)

# Listar labels del repositorio
curl -H "Authorization: token MI_TOKEN" \
  https://tu-dominio.com/api/v1/repos/usuario/proyecto/labels

# Crear un label
curl -X POST -H "Authorization: token MI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "prioridad-alta", "color": "#e11d48"}' \
  https://tu-dominio.com/api/v1/repos/usuario/proyecto/labels

Milestones

Un milestone agrupa un conjunto de issues bajo un objetivo comun con fecha de entrega.

Crear un milestone

Ve a Issues > Milestones
Presiona New Milestone
Completa:
- Titulo: nombre del objetivo (“v1.0”, “Sprint 3”, “Q1 2026”)
- Descripcion: contexto adicional (opcional)
- Fecha limite: la fecha objetivo de completitud

Asignar issues a un milestone

Al crear o editar un issue, selecciona el milestone en el panel lateral. Tambien puedes asignar de forma masiva desde la lista de issues usando las casillas de seleccion.

Ver progreso

En la vista de milestones, cada uno muestra una barra de progreso con el porcentaje de issues cerrados vs abiertos. Esto es util para tracking en sprints o planificacion de versiones.

Templates de issue

Los templates definen un formato predefinido para nuevos issues. Son especialmente utiles para repositorios abiertos donde quieres que los reportes de bugs sigan una estructura consistente.

Crear un template

Los templates se ubican en .forgejo/issue_template/ y usan formato YAML:

# .forgejo/issue_template/bug_report.yaml
name: Reporte de bug
about: Usa esta plantilla para reportar un error
title: "[BUG] "
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: |
        Gracias por reportar el bug. Completa la informacion a continuacion.

  - type: input
    id: version
    attributes:
      label: Version afectada
      placeholder: "ej: 1.2.3"
    validations:
      required: true

  - type: textarea
    id: reproduccion
    attributes:
      label: Pasos para reproducir
      description: Describe los pasos que llevan al error
      placeholder: |
        1. Ir a '...'
        2. Hacer click en '...'
        3. Ver el error
    validations:
      required: true

  - type: textarea
    id: comportamiento-esperado
    attributes:
      label: Comportamiento esperado
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: Logs o capturas de pantalla
      description: Pega aqui cualquier log relevante

Cuando un usuario crea un nuevo issue, Forgejo muestra un selector para elegir el template.

Tipos de campo disponibles

Tipo	Descripcion
`markdown`	Texto informativo (no editable por el usuario)
`input`	Campo de texto de una linea
`textarea`	Campo de texto multilínea
`dropdown`	Lista de opciones predefinidas
`checkboxes`	Lista de casillas de verificacion

Referencias cruzadas

Forgejo detecta automaticamente referencias entre issues, PRs y commits.

Referenciar un issue

Dentro del texto de un issue, comentario o descripcion de PR, escribe #N donde N es el numero del issue:

Este problema esta relacionado con #42 y fue introducido en #38.

Forgejo convierte #42 en un enlace clickeable y muestra la referencia en el issue referenciado.

Cerrar issues desde commits

Ciertos prefijos en el mensaje de un commit cierran automaticamente un issue al hacer merge a la rama principal:

git commit -m "fix: corregir validacion de email (closes #15)"
git commit -m "feat: exportar a CSV (fixes #23, resolves #24)"

Palabras clave reconocidas: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.

Referencias entre repositorios

Para referenciar un issue de otro repositorio de la misma instancia:

El bug esta documentado en usuario/otro-repo#7

Busqueda y filtrado

La lista de issues soporta filtros combinables:

Filtros desde la UI

Estado: abiertos / cerrados
Label: uno o mas labels
Milestone: un milestone especifico
Asignado: issues asignados a un usuario
Autor: issues creados por un usuario
Tipo: issues vs pull requests

Busqueda por texto

El campo de busqueda filtra por titulo y contenido. Puedes combinar busqueda de texto con los filtros visuales.

Desde la API

# Issues abiertos con label "bug"
curl -H "Authorization: token MI_TOKEN" \
  "https://tu-dominio.com/api/v1/repos/usuario/proyecto/issues?state=open&labels=bug"

# Issues asignados a un usuario especifico
curl -H "Authorization: token MI_TOKEN" \
  "https://tu-dominio.com/api/v1/repos/usuario/proyecto/issues?assignee=usuario"

Reacciones y comentarios

Los comentarios en issues soportan Markdown completo, incluyendo bloques de codigo con resaltado de sintaxis.

Para agregar una reaccion a un comentario o al issue principal, pasa el cursor sobre el contenido y selecciona el icono de emoji. Las reacciones disponibles son un subconjunto de Unicode: +1, -1, laugh, hooray, confused, heart, rocket, eyes.

Las menciones con @usuario envian una notificacion al usuario referenciado.

Siguiente: Capitulo 10: Pull Requests - flujo de revision —>