RepoGuardian: Auto-Fix GitHub Repos with Pulumi and Python

sujay malghan — Sun, 30 Mar 2025 10:19:53 +0000

This is a submission for the Pulumi Deploy and Document Challenge: Get Creative with Pulumi and GitHub

What I Built

I built RepoGuardian, a GitHub repository linter and auto-fixer using Pulumi Automation API and the Pulumi GitHub Provider, fully written in Python.

RepoGuardian scans all repositories under a GitHub account or organization, checks for missing README.md and LICENSE files, and automatically commits those files using Pulumi — ensuring consistent documentation across all repositories.

It runs fully from Python using the Automation API, with no manual Pulumi CLI steps.

Live Demo Link

This project does not have a web-based demo. It is a backend automation tool meant to be run locally.

Project Repo

sujaymalghan / repo-guardian

RepoGuardian – GitHub Repository Linter and Auto-Fixer

RepoGuardian is a Python-based automation tool that audits and fixes common hygiene issues across GitHub repositories. It scans all repositories in a GitHub account or organization, detects missing standard files (like README and LICENSE), and automatically commits them using Pulumi’s GitHub Provider and Automation API.

This project was built for the "Get Creative with Pulumi + GitHub" Hackathon.

Overview

RepoGuardian addresses a common challenge in GitHub repository management: maintaining consistency and proper documentation across multiple repositories.

It uses Pulumi's infrastructure-as-code approach not for cloud resources, but to programmatically manage and correct GitHub repositories.

Features

Scans all repositories in a GitHub account or organization
Detects:
- Missing README.md
- Missing LICENSE
Automatically fixes the issues by committing files using Pulumi
Skips empty repositories with no commits
Fully automated using Pulumi Automation API
Requires no Pulumi CLI usage

Technology Stack

Python 3.x
Pulumi Automation API
Pulumi GitHub…

View on GitHub

The repository includes:

Python source code (main.py, fixer.py, linter.py)
.env.example for environment config
README with detailed usage instructions
MIT License

My Journey

My goal was to explore how Pulumi could be used beyond infrastructure — to automate GitHub itself.

I started by writing a linter using PyGitHub to scan for missing README.md and LICENSE. Then I integrated Pulumi’s Automation API to dynamically generate a Pulumi program per repository and apply the missing files using the GitHub Provider.

Key steps:

Built a repo linter using PyGitHub
Integrated Pulumi Automation API for programmatic IaC
Used github.RepositoryFile to add missing files
Skipped empty repositories (no commits)
Handled default branch detection for each repo

Challenges:

Handling 404 errors from empty repos
Making sure Pulumi runs without CLI
Passing environment configs securely

This project taught me how infrastructure-as-code can apply to GitHub workflows — and how powerful Pulumi becomes when combined with API-based automation.

Using Pulumi with GitHub

Pulumi was central to this project:

Automation API was used to run everything directly from Python
GitHub Provider managed files like README.md and LICENSE inside repos

This approach meant no Pulumi CLI commands, no YAML files — just Python and clean automation logic.

I did not use Pulumi Copilot. All logic was implemented manually based on documentation.

Installation & Usage

Follow these steps to install and run RepoGuardian:

1. Clone the Repository

git clone https://github.com/sujaymalghan/repo-guardian.git
cd repo-guardian

2. Set Up a Virtual Environment

python -m venv venv
source venv/bin/activate           # macOS/Linux
# OR
venv\Scripts\activate              # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file in the root directory with the following content:

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username_or_org
PULUMI_ACCESS_TOKEN=your_pulumi_token
PULUMI_CONFIG_PASSPHRASE=

Note: Make sure the GitHub token has access to your repos, and the Pulumi token is valid.

5. Run the Tool

python main.py

This will:

Scan all repositories under your GitHub account or organization
Detect missing README.md or LICENSE files
Automatically commit those files using Pulumi

Thanks to the Pulumi and DEV teams for hosting this challenge.

This was a great opportunity to explore creative uses of Pulumi and build something meaningful for GitHub workflows.

DEV Community: sujay malghan