Building a GitHub Actions Workflow to Use Jekyll Picture Tag Automatically

GitHub Pages offers a powerful and free way to host your static blog, but it comes with one major limitation — only a handful of Jekyll plugins are officially supported. If you want to use advanced plugins like jekyll-picture-tag for responsive image automation, you need to take control of the build process. This guide explains how to configure GitHub Actions to build your site automatically with any Jekyll plugin, including those that GitHub Pages normally rejects.

Automating Advanced Jekyll Builds with GitHub Actions

• Why Use GitHub Actions for Jekyll
• Preparing Your Repository for Actions
• Creating the Workflow File
• Installing Jekyll Picture Tag in the Workflow
• Automated Build and Deploy to gh-pages Branch
• Troubleshooting and Best Practices
• Benefits of This Setup

Why Use GitHub Actions for Jekyll

By default, GitHub Pages builds your Jekyll site with strict plugin restrictions to ensure security and simplicity. However, this means any custom plugin such as jekyll-picture-tag, jekyll-sitemap (older versions), or jekyll-seo-tag beyond the whitelist cannot be executed.

With GitHub Actions, you gain full control over the build process. You can run any Ruby gem, preprocess images, and deploy the static output to the gh-pages branch — the branch GitHub Pages serves publicly. Essentially, Actions act as your personal automated build server in the cloud.

Preparing Your Repository for Actions

Before creating the workflow, make sure your repository structure is clean. You’ll need two branches:

• main — contains your source code (Markdown, Jekyll layouts, plugins).
• gh-pages — will hold the built static site generated by Jekyll.

You can create the gh-pages branch manually or let the workflow create it automatically during the first run.

Next, ensure your _config.yml includes the plugin you want to use:

plugins:
  - jekyll-picture-tag
  - jekyll-feed
  - jekyll-seo-tag

Commit this configuration to your main branch. Now you’re ready to automate the build.

Creating the Workflow File

In your repository, create a directory .github/workflows/ if it doesn’t exist yet. Inside it, create a new file named build-and-deploy.yml. This file defines your automation pipeline.

name: Build and Deploy Jekyll with Picture Tag

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1

      - name: Install dependencies
        run: |
          gem install bundler
          bundle install

      - name: Build Jekyll site
        run: bundle exec jekyll build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site
          publish_branch: gh-pages

This workflow tells GitHub to:

1. Run whenever you push changes to the main branch.
2. Install Ruby and dependencies, including your chosen plugins.
3. Build the site using jekyll build.
4. Deploy the static result from _site into gh-pages.

Installing Jekyll Picture Tag in the Workflow

To make jekyll-picture-tag work, add it to your Gemfile before pushing your repository. This ensures the plugin is installed during the build process.

source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "jekyll-picture-tag"
gem "jekyll-seo-tag"
gem "jekyll-feed"

After committing this file, GitHub Actions will automatically install all declared gems during the build stage. If you ever update plugin versions, simply push the new Gemfile and Actions will rebuild accordingly.

Automated Build and Deploy to gh-pages Branch

Once this workflow runs successfully, GitHub Actions will automatically deploy your built site to the gh-pages branch. To make it live, go to:

1. Open your repository settings.
2. Navigate to Pages.
3. Under “Build and deployment”, select “Deploy from branch”.
4. Set the branch to gh-pages and folder to root.

From now on, every time you push changes to main, the site will rebuild automatically — including responsive thumbnails generated by jekyll-picture-tag. You no longer depend on GitHub’s limited built-in Jekyll compiler.

Troubleshooting and Best Practices

Here are common issues and how to resolve them:

To keep your workflow secure and efficient, use GitHub’s built-in GITHUB_TOKEN instead of personal access tokens. Also, consider caching dependencies using actions/cache to speed up subsequent builds.

Benefits of This Setup

Switching to a GitHub Actions-based build gives you the freedom to use any Jekyll plugin, custom scripts, and pre-processing tools without sacrificing the simplicity of GitHub Pages hosting. Here are the major advantages:

• ✅ Full plugin compatibility (including jekyll-picture-tag).
• ⚡ Faster and automated builds every time you push updates.
• 🖼️ Seamless integration of responsive thumbnails and optimized images.
• 🔒 Secure builds using official GitHub tokens.
• 📦 Option to include linting, minification, or testing steps in the workflow.

Once configured, the workflow runs silently in the background — turning your repository into a fully automated static site generator. With this setup, your blog benefits from all the visual and performance improvements of jekyll-picture-tag while staying hosted entirely for free on GitHub Pages.

This method bridges the gap between GitHub Pages’ restrictions and the flexibility of modern Jekyll development, ensuring your blog stays future-proof, optimized, and visually polished without requiring manual builds.