¿Qué es una animación snake de contribuciones de GitHub?
Una animación snake de contribuciones de GitHub es un recurso visual generado desde el gráfico de contribuciones que GitHub expone para una cuenta. La serpiente recorre las celdas del calendario y produce un archivo que se puede insertar en un README de perfil. Es una capa de presentación: no crea contribuciones, no arregla actividad ausente y no modifica el historial del repositorio.
El repositorio Platane/snk documenta salidas GIF y SVG y una GitHub Action que recibe un nombre de usuario y rutas de salida. El workflow puede escribir archivos como dist/github-snake.svg y guardarlos en el repositorio que sirve el README. El proyecto también ofrece una acción SVG-only más rápida.
La separación es importante cuando la snake aparece vacía. Comienza con el gráfico oficial del perfil y confirma que la actividad esperada sea visible. GitHub puede omitir commits por el correo de autor, la rama, el fork, el tipo de repositorio, la privacidad o el tiempo de procesamiento. Si el origen está incompleto, regenerar la animación solo produce una vista más clara de datos incompletos.
Para una captura fija, consulta la guía para exportar el gráfico como PNG. Para un README con proyectos, enlaces y secciones alrededor de la animación, usa la guía del README de perfil. La snake tiene un trabajo concreto: hacer que el calendario se mueva en un recurso compacto y fácil de recordar.
Cómo configurar una animación snake de contribuciones de GitHub
La configuración resulta más sencilla si el archivo generado vive en una carpeta predecible y un solo workflow se encarga de actualizarlo. Usa la sintaxis oficial como punto de partida y adapta la ruta al repositorio que publica tu README.
Elige el repositorio que alojará el recurso
Un README de perfil suele publicarse desde el repositorio cuyo nombre coincide con el usuario de GitHub. Confirma ese repositorio y su rama predeterminada antes de añadir el workflow. Así la URL final del recurso queda clara.
Añade un workflow programado de GitHub Actions
Crea un archivo en .github/workflows/ y utiliza la acción documentada Platane/snk@v1. Pasa el nombre mediante github_user_name; el contexto del propietario es un valor práctico cuando el workflow está en el repositorio del perfil.
Decide entre SVG, GIF o ambos
Usa svg_out_path para un recurso ligero y fácil de insertar. Añade gif_out_path solo si el movimiento aporta algo y el tamaño extra es aceptable. El README puede mostrar el SVG y dejar el GIF como demostración opcional.
Guarda el archivo generado en una ruta estable
Mantén la salida en una carpeta como dist/ y revisa los permisos que permiten actualizarla. No escondas el archivo final en un directorio temporal del runner.
Inserta la URL real en README.md
Referencia el SVG o GIF con una URL raw de GitHub o con un enlace relativo cuando ambos archivos se muevan juntos. Abre el perfil publicado para comprobar la imagen fuera de los registros de Actions.
Archivos, salidas y comprobaciones de actualización
Aunque la parte móvil es pequeña, cuatro lugares cumplen funciones diferentes. El workflow decide cuándo se ejecuta la acción; el archivo generado es la salida; README.md es la presentación pública; y el gráfico oficial sigue siendo la comprobación del origen. Nombrar cada capa ayuda a localizar fallos.
Un workflow programado puede refrescar el recurso después de que GitHub procese actividad nueva, pero una ejecución correcta no garantiza que todo commit local deba aparecer. GitHub necesita tiempo y la acción no puede leer actividad privada o no contabilizada. La fecha del archivo generado es una pista de mantenimiento, no una prueba de volumen de trabajo.
Mantén el README accesible. Coloca un enlace o una breve explicación junto a la animación, no dependas solo del movimiento y ofrece una alternativa fija cuando sea necesario. El recurso debe apoyar el perfil sin empujar los proyectos y la documentación fuera de la primera pantalla.
| Capa | Función | Comprobación antes de compartir |
|---|---|---|
| .github/workflows/*.yml | Ejecuta la acción manualmente o con un horario. | Usuario, versión, permisos y evento están claros. |
| dist/github-snake.svg | Guarda la animación vectorial generada. | Existe en la rama que usa el README. |
| dist/github-snake.gif | Alternativa raster animada opcional. | El tamaño y el movimiento justifican el archivo. |
| README.md | Coloca el recurso junto al contexto del perfil. | La URL raw o relativa carga desde una visita limpia. |
| Gráfico del perfil | Verifica la fuente que lee la snake. | Las contribuciones esperadas aparecen tras el procesamiento. |
Snake frente a otras visualizaciones de contribuciones
Estos formatos pueden usar los mismos datos y, sin embargo, resolver trabajos distintos. Elige el recurso más pequeño que responda a la pregunta del lector y enlaza a una guía detallada cuando hagan falta reglas o contexto.
Usa una snake para añadir movimiento al README
Es compacta y juguetona cuando el lector entiende que las celdas representan contribuciones. Añade una explicación y una alternativa estática si el movimiento no es adecuado.
Usa PNG para una instantánea estable
Un PNG encaja mejor en un portfolio, una presentación o un documento impreso. No depende del tiempo de animación y permite indicar un rango de fechas fijo.
Usa Profile 3D Contrib para una imagen 3D automática
Un calendario 3D generado por workflow sirve cuando necesitas un recurso más rico guardado en el repositorio del perfil. Sus requisitos son distintos a los de una snake.
Usa GitHub City para explorar en 3D
GitHub City convierte la actividad visible en una escena urbana interactiva en el navegador. Es otra capa visual, no un sustituto del workflow que publica un recurso en README.
Por qué una snake aparece vacía o antigua
Una snake vacía suele apuntar al gráfico de origen, a la salida del workflow o a la URL del README. Revisa esas tres capas en ese orden. Abre el perfil público y mira el calendario; después abre la ejecución de Actions para confirmar que se escribió el archivo; por último abre directamente la URL guardada en lugar de confiar en una página en caché.
Si al gráfico le falta actividad, revisa el correo asociado al commit, la rama donde llegó, el repositorio o fork, la visibilidad de contribuciones privadas y el retraso de procesamiento. El historial de commits de un repositorio y el gráfico del perfil responden preguntas distintas, por lo que un commit puede existir en una vista y tardar en aparecer en la otra.
Si el gráfico es correcto pero el recurso es antiguo, revisa el disparador, el horario, el registro de la acción, la ruta de salida y la rama que usa el README. Si el archivo existe pero el perfil muestra otro, comprueba la URL raw, elimina duplicados y deja que se actualicen las cachés antes de cambiar de nuevo el workflow.
Orden de depuración
Gráfico del perfil primero, registro de Actions después, archivo guardado tercero y embed del README al final. Cambiar la URL de presentación antes de confirmar los datos puede ocultar la causa real.
Preguntas sobre la animación snake de GitHub
¿Qué es una animación snake de contribuciones de GitHub?
Es un SVG o GIF generado desde el gráfico de contribuciones visible de un usuario. La serpiente recorre las celdas y puede aparecer en el README de perfil; no crea ni repara contribuciones.
¿Qué repositorio debe contener la imagen?
Para un README de perfil, usa el repositorio cuyo nombre coincide con el usuario de GitHub. Guarda allí el archivo en una carpeta estable y referencia esa ruta exacta.
¿Conviene usar SVG o GIF?
SVG suele ser el valor predeterminado más ligero para un README. GIF aporta movimiento como archivo raster, pero debes comprobar el tamaño, la carga y la necesidad de una alternativa fija.
¿Cada cuánto se actualiza la snake?
Se actualiza cuando se ejecuta el workflow y el gráfico de contribuciones está disponible para la acción. El horario y el retraso de GitHub determinan cuándo aparece actividad nueva.
¿Por qué no muestra mis commits recientes?
Comprueba primero el gráfico oficial. Después revisa correo del commit, rama, fork, privacidad, ejecución de Actions, ruta de salida y caché del README. La animación no puede mostrar actividad que el gráfico no expone.
¿Puedo ponerla en el README sin GitHub Actions?
Sí, puedes subir un SVG o GIF manualmente, pero no se actualizará solo. GitHub Actions es la vía documentada para la generación programada; el archivo manual funciona como instantánea fechada.
¿La snake es igual que GitHub City?
No. La snake es un recurso animado para README. GitHub City es una visualización 3D interactiva de la actividad visible en el navegador.
¿Revela los nombres de repositorios privados?
No debe usarse para revelar detalles privados. Revisa la configuración de visibilidad del perfil y el recurso final antes de compartirlo.