GitHub Issues: Qué es, para qué sirve y cómo utilizarlo

GitHub Issues permite registrar y organizar tareas, errores, propuestas y mejoras dentro de un repositorio. En esta guía aprenderás qué son, para qué sirven y cómo crear, gestionar, asignar, comentar, cerrar y relacionar Issues con otros elementos de GitHub.

Índice

1. ¿Qué es GitHub Issues?

GitHub Issues es una herramienta integrada en GitHub que permite registrar, organizar y hacer seguimiento de tareas, errores, propuestas de mejora y otras actividades relacionadas con un proyecto.

Cada Issue funciona como un espacio de trabajo donde se puede escribir una descripción, conversar con otros colaboradores, asignar responsables y consultar el progreso de una tarea.

Por ejemplo, si estás desarrollando una página web y descubres que un botón no funciona, puedes crear una Issue para registrar el problema y darle seguimiento hasta solucionarlo.

1.1. ¿Qué información contiene una Issue?

Una Issue puede incluir los siguientes elementos:

Título: describe brevemente el problema o la tarea.
Descripción: explica qué se necesita hacer, qué error se encontró o qué propuesta se quiere realizar.
Comentarios: permiten intercambiar ideas y comunicar avances.
Etiquetas (Labels): sirven para clasificar las Issues.
Responsables (Assignees): indican quién se encargará del trabajo.
Milestones: permiten asociar una Issue con un objetivo o una etapa del proyecto.
Proyectos (Projects): ayudan a organizar y visualizar el trabajo.

2. ¿Para qué sirve GitHub Issues?

GitHub Issues sirve para organizar el trabajo de un proyecto y evitar que las tareas, errores o propuestas queden olvidados. Puede utilizarse tanto en proyectos personales como en equipos de desarrollo.

2.1. Registrar errores en un proyecto

Permite documentar errores que deben corregirse, conocidos como bugs.

Por ejemplo:

El formulario de contacto no se envía cuando el usuario completa todos los campos.

La Issue puede incluir los pasos para reproducir el error, el resultado esperado y el resultado obtenido.

2.2. Crear tareas pendientes

Puedes utilizar Issues para registrar las actividades que necesitas realizar en un proyecto.

Algunos ejemplos son:

Crear la página de inicio.
Agregar un menú de navegación.
Mejorar el diseño para dispositivos móviles.
Configurar un formulario de contacto.

2.3. Proponer nuevas funciones

Una Issue también puede utilizarse para sugerir características que todavía no existen.

Por ejemplo, en una aplicación web podrías crear una Issue titulada:

Agregar modo oscuro a la aplicación.

De esta manera, la propuesta queda registrada y puede ser analizada antes de comenzar su desarrollo.

2.4. Organizar el trabajo en equipo

Cada tarea puede tener un responsable, etiquetas y una etapa dentro del proyecto. Además, los colaboradores pueden comentar en la Issue para compartir información y coordinar el trabajo.

2.5. Relacionar tareas con Pull Requests

GitHub permite vincular Issues con Pull Requests. Por ejemplo, una Pull Request puede incluir Closes #12 para indicar que resuelve la Issue número 12. Cuando la Pull Request se integra en la rama correspondiente, GitHub puede cerrar automáticamente la Issue vinculada.

3. ¿Cuál es la diferencia entre GitHub Issues y Pull Requests?

Aunque ambas herramientas se utilizan dentro de GitHub, tanto GitHub Issues como Pull Request tienen objetivos diferentes.

GitHub Issues	Pull Requests
Registrar errores, tareas, ideas o propuestas.	Proponer cambios en el código del repositorio.
Permitir debatir y organizar el trabajo.	Revisar y analizar modificaciones antes de integrarlas.
No requiere necesariamente modificar código.	Normalmente contiene cambios realizados en una rama.
Puede utilizarse para planificar el trabajo.	Se utiliza para revisar e integrar contribuciones.

Ejemplo práctico: Primero puedes crear una Issue para indicar que necesitas agregar un buscador a una página web. Después, un desarrollador puede implementar esa función y crear una Pull Request para que el equipo revise los cambios.

4. ¿Cómo crear una Issue en GitHub?

Para crear una Issue necesitas un repositorio de GitHub en el que la función Issues esté habilitada. Según los permisos del repositorio, podrás crearla y, si tienes permisos suficientes, asignar responsables, etiquetas y otros elementos de organización.

Paso 1. Entrar al repositorio

Inicia sesión en tu cuenta de GitHub.
Accede al repositorio donde quieres registrar la tarea o el problema.
En la barra de navegación del repositorio, haz clic en Issues.

Paso 2. Crear una nueva Issue

Haz clic en New issue.
Si el repositorio dispone de plantillas, selecciona la que corresponda, como una plantilla para errores o nuevas funcionalidades.
Si no necesitas una plantilla, selecciona Open a blank issue.

Paso 3. Escribir el título

En el campo Title, escribe un título breve y descriptivo.

Por ejemplo:

El botón de envío del formulario no funciona

Es preferible que el título explique directamente qué sucede, en lugar de utilizar uno demasiado general como Error en la página.

Paso 4. Completar la descripción

En el cuerpo de la Issue, explica detalladamente qué ocurre y qué se necesita hacer.

Un ejemplo para un proyecto web sería:

## Descripción

El botón de envío del formulario de contacto no funciona.

## Pasos para reproducir el error

1. Abrir la página de contacto.
2. Completar los campos del formulario.
3. Hacer clic en "Enviar".

## Resultado actual

El formulario no muestra ningún mensaje y los datos no se envían.

## Resultado esperado

El formulario debería enviar los datos y mostrar un mensaje de confirmación.Lenguaje del código: PHP (php)

Una descripción clara facilita que otros colaboradores comprendan el problema y puedan trabajar en su solución.

Paso 5. Agregar etiquetas y responsables

Desde la barra lateral puedes agregar, cuando estén disponibles y tengas los permisos necesarios:

Labels: por ejemplo, bug, documentation o enhancement.
Assignees: la persona responsable de trabajar en la Issue.
Milestone: el objetivo o la etapa a la que pertenece.
Project: el proyecto donde quieres organizarla.

Paso 6. Publicar la Issue

Cuando hayas completado la información:

Revisa el título y la descripción.
Comprueba que las etiquetas y los responsables sean correctos.
Haz clic en Submit new issue.

GitHub creará la Issue y le asignará un número identificador, como #1, #2 o #15. También tendrá una URL propia que puedes compartir con otros colaboradores.

5. ¿Cómo utilizar una Issue en GitHub?

Una vez creada, la Issue se convierte en un espacio donde puedes consultar la tarea, añadir información, recibir comentarios y controlar su evolución.

5.1. ¿Cómo agregar comentarios a una Issue?

Los comentarios permiten conversar con otros colaboradores y aportar información relacionada con el problema o la tarea.

Para agregar un comentario:

Abre el repositorio de GitHub.
Entra en Issues.
Selecciona la Issue que quieres consultar.
Desplázate hasta el área de comentarios.
Escribe tu mensaje.
Haz clic en Comment o Comentar.

Por ejemplo, puedes escribir:

He comprobado el error en Google Chrome y Firefox. El problema continúa apareciendo cuando el formulario se envía sin completar el campo de correo electrónico.

Los comentarios también sirven para informar sobre avances, hacer preguntas o explicar cómo se resolvió un problema.

5.2. ¿Cómo asignar una Issue a un colaborador?

Asignar una Issue permite indicar quién se encargará de trabajar en ella.

Para hacerlo:

Abre la Issue.
Busca la sección Assignees en la barra lateral.
Haz clic en la opción para asignar responsables.
Selecciona uno o varios colaboradores disponibles.
Comprueba que el responsable aparezca asociado a la Issue.

Por ejemplo, si una Issue registra un error en el formulario de contacto, puedes asignársela a la persona que trabaja en el código JavaScript del proyecto.

5.3. ¿Cómo agregar etiquetas (Labels)?

Las etiquetas permiten clasificar las Issues y facilitar su búsqueda.

Algunos ejemplos habituales son:

Etiqueta	Utilidad
`bug`	Identificar un error.
`enhancement`	Proponer una mejora.
`documentation`	Tarea relacionada con la documentación.
`question`	Pregunta o consulta.
`good first issue`	Tarea apropiada para personas que comienzan a colaborar.

Para agregar una etiqueta:

Abre la Issue.
En la barra lateral, busca Labels.
Haz clic en la opción para seleccionar etiquetas.
Elige una etiqueta existente.

Si tienes los permisos necesarios, también puedes crear etiquetas personalizadas para el repositorio.

5.4. ¿Cómo editar una Issue?

Si necesitas corregir el título, modificar la descripción o actualizar la información de una Issue, puedes editarla.

Para modificar el título:

Abre la Issue.
Haz clic en Edit, junto al título.
Escribe el nuevo título.
Guarda los cambios.

Para modificar la descripción:

Abre la Issue.
Busca el menú de opciones de la descripción.
Selecciona Edit.
Modifica el contenido.
Haz clic en Save.

También es posible modificar determinados datos de organización, como etiquetas y tipos de Issue, según los permisos disponibles.

6. ¿Cómo cerrar una Issue en GitHub?

Cerrar una Issue significa indicar que ya no necesita permanecer abierta. Esto puede ocurrir porque el error fue solucionado, la tarea se completó o la propuesta dejó de necesitar trabajo.

Por ejemplo, si creaste una Issue para corregir un botón que no funcionaba y el problema ya fue solucionado, puedes cerrarla.

61. Paso a paso para cerrar una Issue

Accede al repositorio en GitHub.
Haz clic en Issues.
Abre la Issue que quieres cerrar.
Revisa que el problema o la tarea esté resuelto.
Busca el botón Close issue o la opción equivalente para cerrar la Issue.
Confirma el cierre si GitHub lo solicita.

Una vez cerrada, la Issue dejará de formar parte de la lista de Issues abiertas, aunque seguirá disponible para consultar su descripción, comentarios e historial.

6.2. ¿Se puede reabrir una Issue cerrada?

Sí. Si una Issue cerrada necesita volver a trabajarse, puede reabrirse cuando se disponga de los permisos necesarios y la configuración del repositorio lo permita.

Por ejemplo, si el error que se había solucionado vuelve a aparecer, puedes consultar la Issue cerrada y utilizar la opción Reopen issue para continuar con su seguimiento.

7. ¿Cómo borrar una Issue en GitHub?

GitHub permite eliminar determinadas Issues, pero cerrar una Issue y eliminarla son acciones diferentes.

Cerrar: conserva la Issue para consultar su información e historial.
Eliminar: quita la Issue del repositorio, por lo que deja de estar disponible como Issue normal.

Por eso, antes de eliminar una Issue, conviene comprobar si realmente es necesario hacerlo. En muchos casos, cerrarla es suficiente para indicar que la tarea ya no está pendiente.

7.1. ¿Cómo eliminar una Issue?

La disponibilidad de la eliminación depende de los permisos y de las opciones que GitHub muestre para esa Issue. Si aparece la opción correspondiente:

Abre la Issue.
Busca el menú de opciones de la Issue.
Selecciona Delete issue o Eliminar Issue.
Revisa la advertencia que muestra GitHub.
Confirma la eliminación si estás seguro de que deseas realizarla.

Importante: no debes confundir esta acción con cerrar una Issue. Si no aparece la opción de eliminar, puedes conservarla y cerrarla cuando corresponda.

8. ¿Cómo organizar Issues con etiquetas, milestones y Projects?

Cuando un repositorio tiene muchas Issues, puede resultar difícil saber qué tareas están pendientes, cuáles se están realizando y cuáles ya terminaron. GitHub ofrece herramientas para organizar ese trabajo.

8.1. ¿Qué son los Milestones en GitHub?

Los Milestones o hitos permiten agrupar Issues y Pull Requests que forman parte de un objetivo común. También pueden incluir una fecha límite y mostrar el progreso de las tareas asociadas.

Por ejemplo, en un proyecto de una página web podrías crear el siguiente hito:

Milestone: Lanzamiento de la versión 1.0Lenguaje del código: CSS (css)

Dentro de ese hito puedes asociar Issues como:

Crear la página de inicio.
Agregar un formulario de contacto.
Corregir errores de diseño.
Realizar pruebas en dispositivos móviles.

8.2. ¿Qué son los Projects de GitHub?

GitHub Projects es una herramienta de planificación que permite organizar Issues y Pull Requests mediante tablas, tableros y otras vistas.

Puedes utilizarlo para visualizar las tareas según su estado, por ejemplo:

Pendiente	En progreso	Completado
Crear formulario	Diseñar menú	Corregir enlaces
Agregar buscador	—	Crear README

De esta forma, puedes consultar el estado general del trabajo y organizar las actividades del proyecto.

9. ¿Cómo dividir una Issue en subtareas?

Algunas tareas son demasiado grandes para resolverse en una sola actividad. GitHub permite utilizar sub-issues para dividir una Issue principal en tareas más pequeñas y relacionadas.

9.1. Ejemplo práctico

Issue principal:

Crear una página de contacto para el sitio web.

Sub-issues:

Crear la estructura HTML.
Diseñar el formulario con CSS.
Validar los campos con JavaScript.
Configurar el envío de datos.
Probar el formulario en diferentes navegadores.

Cada subtarea puede tener su propio seguimiento, mientras que la Issue principal representa el objetivo general.

10. ¿Cómo relacionar una Issue con una Pull Request?

Una Issue puede estar relacionada con una Pull Request para conectar una tarea pendiente con los cambios de código que intentan resolverla.

Por ejemplo, supongamos que tienes la Issue número 15:

#15 - Corregir el botón de envío del formularioLenguaje del código: CSS (css)

Después de modificar el código, creas una Pull Request y agregas en su descripción:

Closes #15Lenguaje del código: CSS (css)

Cuando GitHub integra esa Pull Request en la rama correspondiente, puede cerrar automáticamente la Issue número 15. Esto ayuda a mantener relacionado el trabajo pendiente con la modificación que lo resuelve.

11. Buenas prácticas para trabajar con GitHub Issues

Para mantener un repositorio ordenado, es recomendable seguir algunas prácticas:

11.1. Escribir títulos claros

Un título como:

El formulario no valida el correo electrónico

es más útil que uno demasiado general como:

Problema

11.2. Explicar el problema con detalles

Incluye información que ayude a comprender la tarea:

Qué sucede.
Qué resultado se esperaba.
Cómo reproducir el error.
Qué información adicional puede ser útil.

11.3. Evitar Issues duplicadas

Antes de crear una nueva Issue, revisa si ya existe otra relacionada con el mismo problema. GitHub puede sugerir Issues existentes mientras escribes el título y la descripción.

11.4. Utilizar etiquetas apropiadas

Las etiquetas permiten identificar rápidamente si una Issue corresponde a un error, una mejora, una pregunta o una tarea de documentación.

11.5. Mantener actualizada la información

Si el problema cambia, agrega comentarios o edita la descripción para que los colaboradores conozcan el estado actual.

11.6. Cerrar las tareas terminadas

Cuando una tarea se completa, cierra la Issue para mantener actualizada la lista de trabajo pendiente.

11.7. Vincular el trabajo con Pull Requests

Cuando una modificación de código resuelve una Issue, relaciona ambas para facilitar el seguimiento del proyecto.

12. Ejemplo práctico: crear y resolver una Issue en un proyecto web

A continuación, veremos un ejemplo sencillo para comprender cómo se utiliza GitHub Issues durante el desarrollo de una página web.

Situación inicial

Tienes un repositorio llamado:

mi-pagina-web

Dentro del proyecto existe un formulario de contacto, pero el botón Enviar no funciona correctamente.

Paso 1. Crear la Issue

En GitHub, accedes al repositorio y creas una Issue con los siguientes datos:

Título:

Corregir el botón de envío del formulario

Descripción:

## Problema

El botón de envío del formulario de contacto
no envía los datos correctamente.

## Resultado esperado

El formulario debería validar los campos
y mostrar un mensaje de confirmación.

## Tareas

- [ ] Revisar el código HTML.
- [ ] Comprobar la validación JavaScript.
- [ ] Corregir el evento de envío.
- [ ] Realizar pruebas.Lenguaje del código: CSS (css)

Paso 2. Organizar la Issue

Puedes agregar la etiqueta bug y asignar la tarea a un colaborador que se encargará de revisar el código.

Paso 3. Realizar los cambios

El colaborador modifica el código en una rama de Git, comprueba que el formulario funcione y sube los cambios al repositorio de GitHub.

Paso 4. Crear una Pull Request

Se crea una Pull Request para que los cambios puedan revisarse. En su descripción se puede incluir:

Closes #1Lenguaje del código: CSS (css)

En este ejemplo, #1 representa el número de la Issue que registra el error.

Paso 5. Cerrar la Issue

Después de revisar e integrar los cambios, GitHub puede cerrar automáticamente la Issue vinculada. Así, el repositorio conserva la relación entre el error original y la solución implementada.

13. Conclusión: ¿por qué utilizar GitHub Issues?

GitHub Issues es una herramienta fundamental para organizar el trabajo dentro de un repositorio. Permite registrar errores, crear tareas, proponer mejoras, asignar responsables y mantener conversaciones relacionadas con el desarrollo de un proyecto.

En un flujo de trabajo con Git y GitHub, las Issues ayudan a definir qué se necesita hacer, mientras que las ramas y las Pull Requests permiten desarrollar, revisar e integrar los cambios necesarios para completar esas tareas.

De esta manera, el proyecto mantiene una mejor organización y los colaboradores pueden conocer qué actividades están pendientes, cuáles se encuentran en progreso y cuáles ya fueron resueltas.