RepoGuardian: Auto-Fix GitHub Repos with Pulumi and Python

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:

1. Built a repo linter using PyGitHub
2. Integrated Pulumi Automation API for programmatic IaC
3. Used github.RepositoryFile to add missing files
4. Skipped empty repositories (no commits)
5. 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.