Cómo acortar las largas URL de GitHub para optimizar tu flujo de trabajo de desarrollo

Las URL de GitHub concatenan elementos como el nombre del propietario, el nombre del repositorio, el nombre de la rama y la ruta del archivo. Por ejemplo, un permalink que apunta a una línea específica de un archivo alcanza una longitud como esta:

`github.com/organization/repository-name/blob/a1b2c3d4e5f6/src/components/authentication/LoginForm.tsx#L42-L58`

Los enlaces a comentarios en Issues o Pull Requests también incluyen fragmentos como `#issuecomment-1234567890`, que alargan la URL. Los enlaces a diferencias en revisiones de código, al combinar rutas de archivos y hashes, pueden superar los 200 caracteres.

Pegar estas URL largas en hilos de Slack o correos electrónicos hace que la URL ocupe buena parte del mensaje y dificulta su lectura.

GitHub ofrecía anteriormente un servicio oficial de URL acortadas llamado `git.io`. Sin embargo, en 2022 se detuvo la creación de nuevas URL, y las URL acortadas existentes se trasladaron a un servicio de solo lectura y se conservaron. Con este cierre, se perdió el medio oficial para acortar URL de GitHub.

Como alternativas, existen las siguientes opciones:

• Utilizar un servicio de URL acortadas con dominio propio
• Operar URL acortadas con un dominio personalizado
• Crear páginas de redirección combinándolo con GitHub Pages

En proyectos de código abierto, también existe la práctica de usar un subdominio específico del proyecto (por ejemplo: `go.project-name.dev/issue-123`) como URL acortada.

El README de un repositorio de GitHub es el documento que sirve como cara del proyecto. Gestionar los enlaces incluidos en el README con URL acortadas ofrece varias ventajas.

Simplificación de las URL de badges

A veces se colocan al inicio del README badges de estado de CI, cobertura, licencia, etc. Sin embargo, como las URL de imagen y destino de cada badge son largas, el código fuente Markdown se vuelve difícil de leer. Con URL acortadas, el Markdown de los badges queda más conciso y la edición del README se facilita.

Enlace al sitio de documentación

Algunos proyectos de código abierto mantienen un sitio de documentación independiente del repositorio de GitHub. Al enlazar desde el README a las distintas páginas del sitio de documentación, usar URL acortadas permite adaptarse con flexibilidad a cambios en los destinos. Aunque cambie la estructura de URL del sitio de documentación, basta con actualizar el destino de redirección de la URL acortada, sin necesidad de modificar el README.

Cuando un pipeline CI/CD falla, existe la práctica de enviar notificaciones a Slack o Teams. Convertir los enlaces incluidos en estos mensajes de notificación en URL acortadas mejora la legibilidad de las notificaciones.

Patrón de implementación

En un flujo de trabajo de GitHub Actions, se incorpora la generación de URL acortadas en el paso que envía la notificación a Slack cuando falla el build. Concretamente, se envía la URL de ejecución del flujo de trabajo fallido a la API de URL acortadas y se incluye la URL acortada devuelta en el mensaje de Slack.

La ventaja de este método no es solo que el mensaje de notificación quede más compacto, sino que el número de clics ofrece pistas para saber si se abrieron los logs. Si la tasa de revisión de notificaciones es baja, esto sirve como base para mejorar los destinatarios o el contenido de las notificaciones.

Aplicación a notificaciones de despliegue

Las URL acortadas también pueden usarse en las notificaciones de despliegue completado. Si organizas con URL acortadas los múltiples enlaces que contiene un mensaje de notificación (URL del entorno desplegado, enlace al PR con los cambios, enlace a la documentación del procedimiento de rollback), en situaciones de emergencia se facilita encontrar la información necesaria.

URL acortadas en plantillas de Issues

A veces se incluyen en las plantillas de Issues para reportes de bugs o solicitudes de funcionalidades enlaces a la guía de contribución o al código de conducta. Si estos enlaces son URL acortadas, cuando cambie la URL de las directrices no será necesario modificar la plantilla.

Uso en notas de versión

Las notas de versión pueden contener enlaces a Issues y PRs relacionados con los cambios. Usar URL acortadas despeja las notas de versión y facilita a los usuarios seguir los detalles de los cambios que les interesan.

Al operar URL acortadas en un equipo de desarrollo, establecer las siguientes reglas facilita el proceso:

• Unificar las convenciones de nomenclatura de slugs (por ejemplo: `repo-issue-123`, `repo-pr-456`)
• Establecer fecha de expiración para enlaces temporales (solicitudes de revisión, etc.)
• Crear sin expiración los enlaces permanentes (documentación, directrices, etc.)
• Gestionar el listado de URL acortadas en Notion o una wiki accesible para todo el equipo

Incluir estas reglas en `CONTRIBUTING.md` puede ayudar a los nuevos colaboradores a conocer la operativa. Las URL acortadas son una herramienta pequeña, pero hay situaciones en las que pueden reducir el esfuerzo en el flujo de trabajo de desarrollo.