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: actualizar las señales de recencia de los repositorios en el orden que tú elijas.
Se crean tags temporales que apuntan al HEAD existente y se borran al instante. No se crean commits, ramas ni cambios de archivos.
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.
Estrategia de ordenado
GitPins utiliza una única estrategia predecible y 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 scheduler externo
GitPins no ejecuta cron por sí mismo. GitHub Actions es una opción habitual, pero también puedes usar cron o cualquier scheduler capaz de llamar por HTTP a tu instancia.
¿Qué ocurre en una ejecución programada?
- 1Llama a tu instancia de GitPins (/api/sync) con tu sync secret por usuario
- 2GitPins valida configuración, hora UTC, cooldown y orden actual:
- Calcula el prefijo mínimo que necesita tocar
- Resuelve el SHA actual de la rama por defecto
- Crea y borra una tag ref temporal para ese SHA
- 3Procesa una sola pasada en orden inverso y limita la velocidad de llamadas
- 4Guarda resultados y duración en los logs de GitPins
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 GitPins hace:
- Leer perfil y metadatos de repositorios autorizados
- Resolver HEAD y crear tags temporales
- Borrar cada tag temporal tras aplicar el toque
- Guardar configuración, historial y logs de sync
Lo que GitPins no hace:
- No borra repositorios - No solicita ese permiso
- No crea commits, ramas ni cambios de archivos
- No lee secrets de Actions ni variables privadas
- No cambia settings del repositorio
- No accede a Issues, PRs, Wikis o Discussions
- No invita colaboradores ni cambia permisos
Nota técnica: Contents: write tiene capacidad técnica de escritura, pero el código actual limita su uso a tags temporales. Puedes revisar los permisos instalados 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 scheduler está bajo tu control
Si eliges GitHub Actions, el workflow corre en un repositorio tuyo. También puedes usar cron u otro scheduler.
Puedes desactivarlo cuando quieras
Desactiva auto sync en Settings y pausa el scheduler externo. Tu orden guardado permanece.
Código abierto y auditable
La aplicación, el endpoint y el ejemplo de workflow son públicos y pueden autohospedarse.
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?
La sincronización manual no consume Actions. Si usas GitHub Actions como scheduler, el consumo depende de la frecuencia que configures y de las reglas vigentes de tu plan.
¿Funciona con repositorios privados?
Sí, si autorizas el acceso y la GitHub App está instalada en esos repositorios. Puedes incluirlos o excluirlos en Settings.
¿Qué pasa si hago push a un repo?
La actividad puede cambiar la recencia. Sincroniza manualmente o deja que tu scheduler externo llame de nuevo a GitPins para restaurar el orden.
¿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.