Cómo funciona GitPins
Explicación técnica de cómo mantenemos tus repositorios ordenados
El problema
GitHub ordena los repositorios en tu perfil por fecha de última actualización. Esto significa que cada vez que haces push a un repo, este sube al principio de tu lista.
Si tienes proyectos importantes que quieres mostrar primero, pero trabajas en otros repositorios, tus proyectos destacados quedan enterrados.
La solución
GitPins utiliza un mecanismo simple pero efectivo: actualizar la fecha de último commit de tus repositorios en el orden que tú elijas.
Esto se hace con tag refs temporales que se crean y borran al instante. No se modifican archivos versionados y el historial del branch principal queda limpio.
Proceso paso a paso
Configuras tu orden
En el dashboard de GitPins, arrastras y sueltas tus repositorios en el orden que deseas. Puedes elegir ordenar todos tus repos o solo los primeros N.
Instalas la GitHub App
Instala la GitHub App en los repositorios que quieres que GitPins gestione. Esto permite crear/borrar refs temporales (sin cambios de archivos) cuando se ejecuta el sync.
Sincronización programada (opcional)
Si quieres que GitPins mantenga tu orden automáticamente, ejecuta un workflow programado (GitHub Actions u otro scheduler) que llame a tu instancia de GitPins.
Reordena si es necesario
Cuando se ejecuta el sync, GitPins comprueba el orden actual en GitHub y solo toca los repos necesarios para restaurar tu top configurado.
Estrategias de commit
GitPins usa una unica estrategia predecible para mantener el historial auditable:
Toque con ref temporal
Creamos una tag ref temporal que apunta a HEAD y la borramos al instante. La recencia cambia sin ensuciar el historial del branch principal.
El GitHub Action
Somos 100% transparentes. La sincronización programada normalmente la ejecuta un GitHub Action en un repositorio que controlas, para que puedas revisarlo, modificarlo o auditarlo cuando quieras.
¿Qué hace el Action?
- 1Llama a tu instancia de GitPins (/api/sync) con tu sync secret por usuario
- 2Para cada repositorio (en orden inverso para que el primero quede más reciente):
- Detecta el branch principal (main/master)
- Resuelve el SHA actual de HEAD
- Crea y borra una tag ref temporal para ese SHA
- 3Espera 1 segundo entre repos para no saturar la API
- 4Reporta el resultado en los logs del Action
Si usas GitHub Actions para la sincronización programada, el workflow vive en .github/workflows/maintain-order.yml dentro del repositorio que hayas elegido.
Seguridad y permisos
Permisos exactos de nuestra GitHub App
Nuestra aplicación solicita los permisos mínimos necesarios. Esto es exactamente lo que podemos y NO podemos hacer:
Lo que SÍ podemos hacer:
- Leer la lista de tus repositorios (metadata)
- Crear y borrar refs temporales (sin modificar archivos)
- Crear y borrar refs temporales para aplicar el orden
- Opcionalmente reescribir historial para limpieza (solo cuando ejecutas limpieza explícitamente)
Lo que NO podemos hacer:
- JAMÁS borrar repositorios - No tenemos ese permiso
- Modificar tus archivos versionados
- Acceder a tus secrets o variables de entorno
- Cambiar configuración de tus repos (settings)
- Acceder a Issues, PRs, Wikis o Discussions
- Invitar colaboradores o cambiar permisos
Nota técnica: Los permisos de GitHub Apps son granulares y verificables. Puedes revisar exactamente qué permisos tiene GitPins instalada en tu cuenta desde github.com/settings/installations
No almacenamos tu código
Solo guardamos configuración de orden y logs en base de datos. No clonamos repositorios ni almacenamos código.
El Action corre en tu cuenta
El GitHub Action se ejecuta en tu propio repositorio, usando tus minutos de Actions. Tienes control total.
Puedes desactivarlo cuando quieras
Simplemente desactiva el Action o elimina el repositorio de configuración. No hay bloqueos.
Código abierto y auditable
El GitHub Action que se instala en tu cuenta es visible arriba. Puedes revisarlo línea por línea antes de activarlo.
Preguntas frecuentes
¿Afecta esto a mi código?
No. Las refs temporales no modifican archivos versionados y se eliminan automáticamente.
¿Cuántos minutos de Actions consume?
Muy pocos. Cada ejecución tarda menos de 1 minuto. Con la frecuencia por defecto (cada 6 horas), usarás aproximadamente 120 minutos al mes, muy por debajo del límite gratuito de GitHub (2000 min/mes).
¿Funciona con repositorios privados?
Sí. Puedes elegir incluir o excluir repositorios privados en la configuración. Ten en cuenta que los repos privados también consumen minutos de Actions (al doble de tasa en el plan gratuito).
¿Qué pasa si hago push a un repo?
En la próxima ejecución del Action, detectará que el orden cambió y lo restaurará automáticamente al orden que configuraste.
¿Puedo pausar la sincronización?
Sí. En los ajustes puedes desactivar la sincronización automática sin perder tu configuración. También puedes desactivar el workflow directamente en GitHub.