Automatic GitHub Repository File Management Utility – Design Plan

Overview

This plan outlines a C# console application that automates updating multiple GitHub repositories based on instructions from a CSV file.

The utility will:

• Parse a CSV configuration file that groups changes by repository (each repo with its list of files to update).
• Authenticate to GitHub using a Personal Access Token (PAT) for non-interactive, secure access.
• Clone repositories (if not already local) or pull the latest changes for existing clones, ensuring the local copy is up-to-date.
• Copy specified files from a source location into each target repository, adding any new files and updating tracked files as listed (ignoring any files not specified).
• Stage and commit the changes in each repository.
• Use commit messages supplied in the CSV or generate them using Azure OpenAI.
• Push commits back to GitHub on the appropriate branch.
• Log all actions and errors to the console.
• Run as a standalone console application suitable for Task Scheduler, cron, or on-demand execution.

---

Architecture and Key Components

The application follows a modular architecture.

Configuration Reader

Responsible for:

• Reading and parsing the CSV file.
• Grouping file changes by repository.
• Producing a collection of repository tasks.

GitHub Client / Git Manager

Responsible for:

• Clone operations.
• Pull operations.
• Staging files.
• Creating commits.
• Pushing changes.

Implementation options:

• LibGit2Sharp
• Git CLI

File Manager

Responsible for:

• Copying source files into repositories.
• Creating required directory structures.
• Detecting new versus existing files.

Commit Message Generator

Responsible for:

• Using commit messages provided by the CSV.
• Generating commit messages via Azure OpenAI when not supplied.
• Falling back to a default message if generation fails.

Logger

Responsible for:

• Console output.
• Error reporting.
• Timestamping.
• Operational tracing.

Control Flow

Program.Main() orchestrates:

1. Load configuration.
2. Process each repository.
3. Clone or pull repository.
4. Copy files.
5. Stage files.
6. Generate commit message.
7. Commit changes.
8. Push changes.
9. Log results.

Repository failures are isolated so processing continues for remaining repositories.

---

CSV Configuration Format and Parsing

The CSV uses one row per repository.

Format

Repository,Branch,CommitMessage,File1,File2,File3,...

Repository

GitHub repository URL or repository identifier.

Example:

https://github.com/Org/RepoName.git

Branch

Optional target branch.

Examples:

main
dev
release

If omitted, the default branch is used.

CommitMessage

Optional commit message.

If empty, Azure OpenAI generates one.

File1, File2, ...

Files to copy into the repository.

Examples:

README.md
docs/CONTRIBUTING.md
src/Lib/Helper.cs

Example CSV

Repository,Branch,CommitMessage,File1,File2,File3
https://github.com/ExampleOrg/RepoA.git,main,"Update project docs",README.md,docs/CONTRIBUTING.md,images/logo.png
https://github.com/ExampleOrg/RepoB.git,,,"src/Lib/Helper.cs","src/Lib/Utils.cs","config/appsettings.json"

Parsed Model

class RepoTask
{
    public string RepoUrl;
    public string Branch;
    public string CommitMsg;
    public List<string> Files;
}

---

GitHub Authentication (Using a Personal Access Token)

The utility uses a GitHub Personal Access Token (PAT).

Token Storage

Recommended:

• Environment variables
• Secret stores
• Secure configuration files

Example:

export GITHUB_TOKEN=<token>

Authentication Approaches

LibGit2Sharp

new UsernamePasswordCredentials
{
    Username = "git",
    Password = token
}

Git CLI

git clone https://USER:TOKEN@github.com/Org/Repo.git

Benefits

• Non-interactive
• Script-friendly
• Fine-grained permissions
• Easily rotated

---

Cloning and Updating Repositories

Working Directory

Example:

working/
├── RepoA
├── RepoB
└── RepoC

Clone Logic

If repository does not exist locally:

git clone

or

Repository.Clone(...)

Branch Support

git clone -b main

or

CloneOptions.BranchName

Pull Logic

If repository already exists:

git pull

or

Commands.Pull(...)

Conflict Handling

Possible actions:

• Retry pull.
• Log conflict.
• Skip repository.
• Continue processing others.

---

Copying Specified Files into Repositories

Source Options

Single Source Root

Example:

C:\RepoUpdates

Explicit Paths

File paths provided directly in CSV.

Copy Process

For each file:

1. Locate source file.
2. Build destination path.
3. Create destination directories.
4. Copy file.
5. Stage file.

Example:

File.Copy(source, destination, true);

Staging

LibGit2Sharp

Commands.Stage(repository, filePath);

Git CLI

git add file.ext

No-Change Detection

If no files changed:

No changes for RepoX; skipping commit.

Error Handling

Examples:

File not found.
Permission denied.
Copy failed.

Repository processing can be skipped if required.

---

Commit Message Generation

The utility supports two approaches.

1. CSV-Supplied Message

Example:

Update project documentation

Used exactly as supplied.

2. Azure OpenAI Generated Message

Required Configuration

AZURE_OPENAI_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_MODEL

Example Prompt

Generate a short commit message for:

- Added README.md
- Updated appsettings.json

Example Response

Add README and update configuration settings

Failure Fallback

Automated update commit

---

Committing Changes

Author Identity

Example:

Automation Bot <bot@example.com>

LibGit2Sharp

repository.Commit(
    commitMessage,
    authorSignature,
    committerSignature);

Git CLI

git commit -m "Update project docs"

Empty Commit Protection

If no changes exist:

No changes to commit.

---

Pushing Changes to GitHub

Push

LibGit2Sharp

repository.Network.Push(...)

Git CLI

git push origin main

Retry Scenarios

Possible retry when:

• Remote branch advanced.
• Pull required before push.

Failure Scenarios

• Invalid PAT
• Permission issues
• Network failures
• Merge conflicts

Success Log

Pushed changes to RepoA

---

Logging and Error Handling

Example Log Output

[2025-03-04 08:00:00] INFO: Cloning repository 'RepoA'
[2025-03-04 08:00:10] INFO: Repository cloned
[2025-03-04 08:00:11] INFO: Copying files
[2025-03-04 08:00:12] INFO: File copied
[2025-03-04 08:00:13] INFO: Commit created
[2025-03-04 08:00:15] SUCCESS: Push complete

Error Examples

ERROR: CSV file not found
ERROR: Authentication failed
ERROR: Missing source file
ERROR: Push rejected

Processing Strategy

Each repository is processed independently:

try
{
    ProcessRepository();
}
catch
{
    LogError();
}

Processing continues even if one repository fails.

Exit Codes

Success

0

Failure

1

---

Deployment and Scheduling

Running the Application

AutoGit.exe "C:\configs\repos.csv"

Scheduling Options

Windows Task Scheduler

Recommended for Windows environments.

Cron

Recommended for Linux environments.

CI/CD Pipelines

Examples:

• GitHub Actions
• Jenkins
• Azure DevOps

Required Environment

GitHub

GITHUB_TOKEN

Azure OpenAI

AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_KEY
AZURE_OPENAI_MODEL

Required Access

• GitHub repository access
• Network connectivity
• Local file system access

---

Summary

The AutoGit utility automates repository maintenance by:

• Reading repository instructions from CSV.
• Cloning or updating repositories.
• Copying managed files.
• Staging changes.
• Generating commit messages.
• Committing updates.
• Pushing changes to GitHub.
• Logging all activity.