π₯ Automating Git Repository Visualizations with GitHub Actions and Gource
In the world of DevOps and continuous integration, automation is essential. One fascinating way to visualize the evolution of a codebase is with Gource, a tool that creates animated tree diagrams of project histories.
Recently, I implemented a GitHub Actions workflow in my ansible-servers repository to automatically generate and deploy Gource visualizations. In this post, I will walk you through how the workflow is set up and what it does.
But first, let us take a quick look backβ¦
π°οΈ Back in 2013: Visualizing Repos with Bash and XVFB
More than a decade ago, I published a blog post about Gource (in Dutch) where I described a manual workflow using Bash scripts. At that time, I ran Gource headlessly using xvfb-run
, piped its output through pv
, and passed it to ffmpeg
to create a video.
It looked something like this:
#!/bin/bash -ex
xvfb-run -a -s "-screen 0 1280x720x24" \
gource \
--seconds-per-day 1 \
--auto-skip-seconds 1 \
--file-idle-time 0 \
--max-file-lag 1 \
--key -1280x720 \
-r 30 \
-o - \
| pv -cW \
| ffmpeg \
-loglevel warning \
-y \
-b:v 3000K \
-r 30 \
-f image2pipe \
-vcodec ppm \
-i - \
-vcodec libx264 \
-preset ultrafast \
-pix_fmt yuv420p \
-crf 1 \
-threads 0 \
-bf 0 \
../gource.mp4
This setup worked well for its time and could even be automated via cron or a Git hook. However, it required a graphical environment workaround and quite a bit of shell-fu.
𧬠From Shell Scripts to GitHub Actions
Fast forward to today, and things are much more elegant. The modern Gource workflow lives in .github/workflows/gource.yml
and is:
- π Reusable through
workflow_call
- π Manually triggerable via
workflow_dispatch
- π¦ Integrated into a larger CI/CD pipeline (
pipeline.yml
) - βοΈ Cloud-native, with video output stored on S3
Instead of bash scripts and virtual framebuffers, I now use a well-structured GitHub Actions workflow with clear job separation, artifact management, and summary reporting.
π What the New Workflow Does
The GitHub Actions workflow handles everything automatically:
- β±οΈ Decides if a new Gource video should be generated, based on time since the last successful run.
- π½οΈ Generates a Gource animation and a looping thumbnail GIF.
- βοΈ Uploads the files to an AWS S3 bucket.
- π Posts a clean summary with links, preview, and commit info.
It supports two triggers:
workflow_dispatch
(manual run from the GitHub UI)workflow_call
(invoked from other workflows likepipeline.yml
)
You can specify how frequently it should run with the skip_interval_hours
input (default is every 24 hours).
π Smart Checks Before Running
To avoid unnecessary work, the workflow first checks:
- If the workflow file itself was changed.
- When the last successful run occurred.
- Whether the defined interval has passed.
Only if those conditions are met does it proceed to the generation step.
π οΈ Building the Visualization
π§Ύ Step-by-step:
- Checkout the Repo
Usesactions/checkout
withfetch-depth: 0
to ensure full commit history. - Generate Gource Video
Usesnbprojekt/gource-action
with configuration for avatars, title, and resolution. - Install FFmpeg
UsesAnimMouse/setup-ffmpeg
to enable video and image processing. - Create a Thumbnail
Extracts preview frames and assembles a looping GIF for visual summaries. - Upload Artifacts
Usesactions/upload-artifact
to store files for downstream use.
βοΈ Uploading to AWS S3
In a second job:
- AWS credentials are securely configured via
aws-actions/configure-aws-credentials
. - Files are uploaded using a commit-specific path.
- Symlinks (
gource-latest.mp4
,gource-latest.gif
) are updated to always point to the latest version.
π A Clean Summary for Humans
At the end, a GitHub Actions summary is generated, which includes:
- A thumbnail preview
- A direct link to the full video
- Video file size
- Commit metadata
This gives collaborators a quick overview, right in the Actions tab.
π Why This Matters
Compared to the 2013 setup:
2013 Bash Script | 2025 GitHub Actions Workflow |
---|---|
Manual setup via shell | Fully automated in CI/CD |
Local only | Cloud-native with AWS S3 |
Xvfb workaround required | Headless and clean execution |
Script needs maintenance | Modular, reusable, and versioned |
No summaries | Markdown summary with links and preview |
Automation has come a long way β and this workflow is a testament to that progress.
β Final Thoughts
This Gource workflow is now a seamless part of my GitHub pipeline. It generates beautiful animations, hosts them reliably, and presents the results with minimal fuss. Whether triggered manually or automatically from a central workflow, it helps tell the story of a repository in a way that is both informative and visually engaging. πβ¨
Would you like help setting this up in your own project? Let me know β I am happy to share.