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:

1. ⏱️ Decides if a new Gource video should be generated, based on time since the last successful run.
2. 📽️ Generates a Gource animation and a looping thumbnail GIF.
3. ☁️ Uploads the files to an AWS S3 bucket.
4. 📝 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 like pipeline.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:

1. Checkout the Repo
   Uses actions/checkout with fetch-depth: 0 to ensure full commit history.
2. Generate Gource Video
   Uses nbprojekt/gource-action with configuration for avatars, title, and resolution.
3. Install FFmpeg
   Uses AnimMouse/setup-ffmpeg to enable video and image processing.
4. Create a Thumbnail
   Extracts preview frames and assembles a looping GIF for visual summaries.
5. Upload Artifacts
   Uses actions/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:

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.