👁 Image
Archetypical.Software.Github 1.0.0

Archetypical.Software.Github

👁 archetypical-logo

A lightweight .NET library for interacting with Git repositories via LibGit2Sharp, primarily designed for GitHub repositories.

Features

• Clone and manage Git repositories
• Checkout specific branches
• Read file contents from repositories
• List and download GitHub releases and release assets
• Multiple authentication methods (username/password, personal access token, SSH key)
• Flexible configuration options
• JSON file content merging (for configuration files)
• Automatic periodic updates from remote repository
• Easy integration with .NET Dependency Injection

Installation

dotnet add package Archetypical.Software.Github

Getting Started

Basic Setup with Dependency Injection

The library now supports a configuration-based approach for GitHub services registration:

using Archetypical.Software.Github;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;

// Setup configuration
var configuration = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json")
 .AddUserSecrets<Program>() // For storing sensitive data
 .Build();

// Setup services
var services = new ServiceCollection();

// Add logging (required)
services.AddLogging();

// Add GitHub services from configuration
services.AddGithubServices(
 configuration,
 configSection: "Github", // Default section name
 addReleaseSupport: true // Enable GitHub Releases API support
);

var serviceProvider = services.BuildServiceProvider();

Sample Configuration Examples

You can configure your GitHub services in appsettings.json or using other configuration sources. Here are examples for different authentication methods:

GitHub App Authentication

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "App": {
 "Id": "123456",
 "InstallationId": "7890123",
 "PrivateKeyPath": "/path/to/private-key.pem"
 }
 }
}

SSH Key Authentication

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "SSH": {
 "PublicKeyPath": "/path/to/id_rsa.pub",
 "PrivateKeyPath": "/path/to/id_rsa",
 "Passphrase": "optional-passphrase"
 },
 "Token": "github-token-for-api-access" // Only required if addReleaseSupport is true
 }
}

Username/Password Authentication

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "Basic": {
 "Username": "yourusername",
 "Password": "your-personal-access-token"
 }
 }
}

Configuring Repository Options

You can still customize repository options with the configuration-based approach:

services.AddGithubServices(
 configuration,
 configSection: "Github",
 configure: options => {
 // Customize repository options
 options.LocalPath = "custom/repo/path"; // Default: "repo"
 options.DefaultBranch = "develop"; // Default: "main"
 options.AutoPullIntervalMinutes = 10; // Default: 5
 options.PullOnInit = false; // Default: true
 });

Usage

// Resolve the Git repository manager
var gitManager = serviceProvider.GetRequiredService<IGitRepositoryManager>();

// Initialize the repository (clones it if not already present)
gitManager.Init();

// Get content from a specific path
var content = await gitManager.GetContent("path/to/file.txt");

// Get content from a specific branch
var branchContent = await gitManager.GetContent("path/to/file.txt", "development");

// Reading the content
using var reader = new StreamReader(content.Content);
var contentText = await reader.ReadToEndAsync();

Working with JSON Configuration Files

The library has special handling for JSON files with automatic merging of common configuration files:

// Getting a JSON file (config.json)
var config = await gitManager.GetContent("config"); // Note: .json extension is optional

// The library will automatically:
// 1. Look for config.json
// 2. Look for config.common*.json files in the same directory
// 3. Merge them all in alphabetical order, with the specific file taking precedence

Working with GitHub Releases

The library provides functionality to list and download GitHub releases and their assets. To use this feature, you need to register GitHub services with release support by setting the addReleaseSupport parameter to true:

// Add GitHub services with release support
services.AddGithubServices(
 configuration,
 configSection: "Github",
 addReleaseSupport: true
);

When using SSH key authentication with releases support, make sure to include a Token in your configuration:

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "SSH": {
 "PublicKeyPath": "/path/to/id_rsa.pub",
 "PrivateKeyPath": "/path/to/id_rsa"
 },
 "Token": "github-personal-access-token-with-repo-scope"
 }
}

Listing Releases

// Get all releases
var releases = await gitManager.GetReleasesAsync();
foreach (var release in releases)
{
 Console.WriteLine($"{release.Name} ({release.TagName}) - {release.Assets.Count} assets");
}

// Get a specific release by tag
var release = await gitManager.GetReleaseByTagAsync("v1.0.0");
if (release != null)
{
 Console.WriteLine($"Found release: {release.Name}");
}

// Get a release by ID
var releaseById = await gitManager.GetReleaseByIdAsync(12345678);

Downloading Release Assets

// Download an asset by ID
using (var stream = await gitManager.DownloadReleaseAssetAsync(assetId))
using (var fileStream = File.Create("path/to/save/asset.zip"))
{
 await stream.CopyToAsync(fileStream);
}

// Download an asset by name from a specific release
using (var stream = await gitManager.DownloadReleaseAssetByNameAsync(releaseId, "asset-name.zip"))
using (var fileStream = File.Create("path/to/save/asset.zip"))
{
 await stream.CopyToAsync(fileStream);
}

// For example, with these files: // - config.common.json // - config.common.development.json // - config.json // The library will merge them in that order, with config.json values overriding any duplicates

## Authentication

The library supports multiple authentication methods through a unified configuration-based approach:

### Configuration-Based Authentication

The new `AddGithubServices` method automatically detects the authentication method based on the provided configuration:

```csharp
services.AddGithubServices(configuration, configSection: "Github");

The method will check for the following configuration patterns and choose the appropriate authentication method:

1. GitHub App Authentication: If App:Id, App:InstallationId, and App:PrivateKeyPath are present
2. SSH Key Authentication: If SSH:PublicKeyPath and SSH:PrivateKeyPath are present
3. Username/Password Authentication: If Basic:Username and Basic:Password are present

Configuration Examples

appsettings.json

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "Basic": {
 "Username": "yourusername",
 "Password": "your-personal-access-token" 
 }
 }
}

user-secrets.json (for sensitive information)

{
 "Github": {
 "RepositoryUrl": "https://github.com/owner/repo.git",
 "App": {
 "Id": "123456",
 "InstallationId": "7890123",
 "PrivateKeyPath": "/path/to/private-key.pem"
 }
 }
}

Custom Authentication

You can implement your own credential provider by implementing the IGitCredentialProvider interface:

public class MyCustomCredentialProvider : IGitCredentialProvider
{
 public CredentialsHandler GetCredentialsHandler()
 {
 // Custom credential handling logic
 return (url, user, cred) => new UsernamePasswordCredentials { ... };
 }
}

// Register with DI
services.AddGithubServicesWithCustomCredentials(
 new MyCustomCredentialProvider(),
 "https://github.com/user/repo.git");

Automatic Updates

The library includes an automatic update mechanism that periodically pulls the latest changes from the remote repository. The frequency is configurable through the GitRepositoryOptions:

services.AddGithubServices(
 "username", 
 "password", 
 "https://github.com/user/repo.git",
 options => {
 options.AutoPullIntervalMinutes = 15; // Pull every 15 minutes
 options.PullOnInit = true; // Pull immediately after initialization
 });