PyGithub + GitHub Pages Advanced Guide
======================================
Overview
--------
This guide provides a comprehensive reference for automating GitHub repository creation,
file management, and GitHub Pages deployment using the PyGithub module and the GitHub REST API.
Topics Covered
--------------
1. PyGithub overview and authentication
2. AuthenticatedUser operations (create_repo, get_user, etc.)
3. Managing repository files (create_file, update_file)
4. Token scopes and permissions (classic vs fine-grained tokens)
5. GitHub Pages deployment (REST API & GitHub Actions workflows)
6. Handling rate limits, 403/404 errors, and exceptions
7. Real-world patterns and best practices
1) Getting Started with PyGithub
--------------------------------
PyGithub is a Python wrapper for the GitHub REST API. It allows automation of repository creation,
file management, issues, actions, and more.
Installation:
pip install PyGithub
Authentication example:
from github import Github
g = Github("your_personal_access_token")
user = g.get_user()
Accessing current user (AuthenticatedUser):
print(user.login)
print(user.name)
print(user.html_url)
2) Creating a Repository
------------------------
You can create a new repository under the authenticated user's account:
repo = user.create_repo(
name="my-portfolio-repo",
description="Generated using PyGithub",
private=False,
auto_init=True
)
print("Repository created:", repo.html_url)
Available attributes include:
repo.name, repo.full_name, repo.clone_url, repo.html_url
3) Uploading or Updating Files
------------------------------
To create a file:
repo.create_file("index.html", "Initial commit", "Hello")
To update a file:
contents = repo.get_contents("index.html")
repo.update_file(contents.path, "Update homepage", "Updated", contents.sha)
4) Token Scopes and Permissions
-------------------------------
GitHub tokens come in two main types:
- Classic Personal Access Tokens (PATs)
- Fine-grained Tokens (newer, more secure, repository-specific)
Required scopes for repo creation and management:
- repo (full control of repositories)
- public_repo (only for public repos)
- delete_repo (if deletion is needed)
- workflow (for GitHub Actions/Pages)
For fine-grained tokens:
- Give access to "Repositories" → "Read and write"
- Add "Actions" and "Pages" permissions if using those features
5) Deploying to GitHub Pages
-----------------------------
You can deploy static websites (HTML/CSS/JS) automatically via GitHub Pages.
### Using GitHub Actions Workflow
Create a file: `.github/workflows/deploy.yml`
-------------------------------------------------
name: Deploy static site to GitHub Pages
on:
push:
branches: [ "main" ]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./
- name: Deploy
uses: actions/deploy-pages@v4
-------------------------------------------------
After pushing, GitHub Actions will deploy the site to:
https://.github.io//
6) Handling 403 and 404 Errors
------------------------------
Common causes of 403 (Forbidden):
- Token lacks required scopes.
- Trying to modify another user's repo.
- Hitting API rate limits.
- Organization policies prevent repo creation.
Handling errors safely:
from github import GithubException
try:
repo = user.create_repo("test-repo")
except GithubException as e:
print("Error:", e.status, e.data)
Common causes of 404 (Not Found):
- Trying to access a repo or file that doesn't exist.
- Wrong repository name or file path.
- Token does not have visibility into that repository.
7) Rate Limits and Monitoring
-----------------------------
Each user/token has a limited number of API requests per hour.
You can check remaining limits with:
print(g.get_rate_limit())
If you frequently hit limits:
- Use authenticated requests.
- Cache results locally.
- Avoid unnecessary API calls in loops.
8) Best Practices for Automation
--------------------------------
- Use environment variables for tokens instead of hardcoding them.
- Use GitHub Actions for deployment automation.
- Implement exception handling and logging.
- Always check API responses before performing next actions.
- Use 'try-except' blocks to gracefully handle rate limits or permission issues.
9) Real-World Example — Portfolio Generator
--------------------------------------------
Your app could:
1. Ask the user to authorize GitHub access using OAuth or PAT.
2. Create a repo automatically using PyGithub.
3. Generate HTML/CSS/JS files locally.
4. Upload files via PyGithub.
5. Push a GitHub Actions workflow for Pages deployment.
6. Return the live site URL.
Example pseudo-flow:
user -> logs in via OAuth -> PAT generated
PAT -> used by PyGithub to create repo + upload files
workflow file added -> site deployed via GitHub Actions
return repo.html_url and pages URL
10) References
--------------
- PyGithub Docs: https://pygithub.readthedocs.io/en/latest/
- GitHub REST API Docs: https://docs.github.com/en/rest
- GitHub Pages Workflow Docs: https://docs.github.com/en/pages
- GitHub Actions Marketplace: https://github.com/marketplace?type=actions
- Managing Personal Access Tokens: https://docs.github.com/en/authentication
