Batch Renderer GitHub Action

Automate AI image generation from markdown prompt files with automatic resuming, incremental commits, and commit squashing.

Features:

• 🔄 Auto-resuming - Continues from where it left off on timeouts/failures
• 💾 Incremental commits - Commits after each image (preserves work immediately)
• 📦 Commit squashing - Optionally squashes all commits into one clean commit
• 📊 Beautiful summaries - Rich GitHub Step Summary output with progress tables
• 🚀 Fast installs - Uses uv by default for 10-100x faster dependency installs
• 🔁 Automatic retries - Configurable retry logic for transient failures
• 📝 Comprehensive logging - Detailed logs stored in repository

---

Quick Start

Basic Usage

name: Generate Images

on:
  push:
    paths:
      - 'prompts.md'
  workflow_dispatch:

jobs:
  render:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Render images
        uses: jlumbroso/batch-renderer-action@v1
        with:
          prompt-file: 'prompts.md'
          output-dir: 'output'

      - name: Push generated images
        run: git push

Advanced Usage with All Options

- name: Render images with custom settings
  uses: jlumbroso/batch-renderer-action@v1
  with:
    # Required
    prompt-file: 'prompts/album-art.md'

    # Optional
    output-dir: 'images'              # Default: output
    logs-dir: 'logs'                  # Default: logs
    commit-each-image: true           # Default: true
    squash-commits: true              # Default: true
    model: 'flux-2-pro'              # Default: (from prompt file)
    max-retries: 5                    # Default: 3
    python-version: '3.12'            # Default: 3.11
    use-uv: true                      # Default: true

---

How It Works

1. State Management

The action maintains a state file (logs/render-state.json) that tracks:

• Completed prompts
• Failed prompts
• Timestamps

This enables automatic resuming: if a workflow times out or fails, the next run continues from where it left off.

2. Incremental Commits

When commit-each-image: true (default):

• Each generated image is committed immediately
• Work is preserved even if the workflow is cancelled
• Progress is visible in real-time

Example commit:

feat: generate image 1-1-coffee-mug-design

Image: output/1-1-coffee-mug-design.png
Generated by: batch-renderer-action
Timestamp: 2026-04-04 12:34:56 UTC

3. Commit Squashing

When squash-commits: true (default):

• After all images are generated, all commits are squashed into one
• Creates a clean git history
• Preserves details in the commit message

Example squashed commit:

feat: batch generate 12 images

This commit contains the results of a complete batch rendering session.

Summary:
- Images generated: 12
- Output directory: output
- Commits squashed: 13
- Timestamp: 2026-04-04 12:45:00 UTC

Generated by: batch-renderer-action (with commit squashing)

---

Inputs

Input	Description	Required	Default
prompt-file	Path to markdown prompt file	✅ Yes	-
output-dir	Directory for generated images	No	output
logs-dir	Directory for logs and state	No	logs
commit-each-image	Commit after each image	No	true
squash-commits	Squash all commits at the end	No	true
model	Model override (ignores prompt file)	No	-
max-retries	Max retries per prompt	No	3
python-version	Python version to use	No	3.11
use-uv	Use uv for faster installs	No	true

---

Outputs

Output	Description
images-generated	Number of images successfully generated
images-failed	Number of images that failed
commit-sha	SHA of the final commit (after squashing)

Example: Using Outputs

- name: Render images
  id: render
  uses: jlumbroso/batch-renderer-action@v1
  with:
    prompt-file: 'prompts.md'

- name: Report results
  run: |
    echo "Generated: ${{ steps.render.outputs.images-generated }} images"
    echo "Failed: ${{ steps.render.outputs.images-failed }} images"
    echo "Commit: ${{ steps.render.outputs.commit-sha }}"

---

Resuming from Failures

If your workflow times out or fails mid-render:

1. Re-run the workflow - The action will:

   • Read logs/render-state.json
   • Skip already-completed prompts
   • Continue rendering remaining prompts

2. No manual intervention needed - State is persisted in the repository

---

GitHub Step Summary

The action generates beautiful step summaries:

🎨 Batch Rendering

Started: 2026-04-04 12:30:00 UTC

Configuration
- Prompt file: prompts.md
- Output directory: output
- Logs directory: logs
- Model: (from prompt file)
- Max retries: 3
- Commit each image: true

---

Results

| Metric | Count |
|--------|-------|
| ✅ Images generated | 12 |
| ❌ Images failed | 0 |
| 📂 Output directory | output |
| 📄 Log file | logs/render-20260404-123000.log |

Completed: 2026-04-04 12:45:00 UTC

🎉 Success!

Generated 12 images successfully.

Generated Images
- 1-1-coffee-mug-design.png
- 1-2-water-bottle-concept.png
...

---

Requirements

Repository Permissions

The workflow needs contents: write permission:

permissions:
  contents: write

Environment Variables

The action expects a POE_API_KEY secret or environment variable. Set it in:

• Repository Settings → Secrets → Actions → New repository secret

env:
  POE_API_KEY: ${{ secrets.POE_API_KEY }}

---

Examples

Trigger on Prompt File Changes

on:
  push:
    paths:
      - 'prompts/**/*.md'

Multiple Prompt Files

jobs:
  render-album-art:
    steps:
      - uses: jlumbroso/batch-renderer-action@v1
        with:
          prompt-file: 'prompts/album-art.md'
          output-dir: 'output/album-art'

  render-storyboards:
    steps:
      - uses: jlumbroso/batch-renderer-action@v1
        with:
          prompt-file: 'prompts/storyboards.md'
          output-dir: 'output/storyboards'

Scheduled Rendering

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

---

License

MIT License - See LICENSE

Author: Jérémie Lumbroso
Built with: batch-renderer Python package