Archetypical.Software.Configuration.Manager 0.2.2

Archetypical.Software.Configuration

Config service backed by Github.

Getting Started

Instructions to get started with this project.

Usage

How to use your project.

Configuration

This service requires configuration for connecting to the Git repository where configuration files are stored. This configuration is typically placed in appsettings.json or provided through environment variables.

Git Repository Settings (Git section)

The core settings are within the "Git" section of your configuration.

{
  "Git": {
    "RepositoryUrl": "<your-git-repository-url>",
    "AuthenticationType": "<authentication-method>",
    // ... other auth-specific settings
  }
}

• RepositoryUrl: The URL of the Git repository (HTTPS or SSH).
• AuthenticationType: Specifies the method used to authenticate with the Git repository. Valid values are:
  • UsernamePassword
  • Pat (Personal Access Token)
  • Ssh
  • GitHubApp (Requires external token generation, see below)

Authentication Methods

1. Username and Password

Use your Git provider username and password (or an app-specific password if 2FA is enabled).

{
  "Git": {
    "RepositoryUrl": "https://github.com/your-username/your-repo.git",
    "AuthenticationType": "UsernamePassword",
    "Username": "your-github-username",
    "Password": "your-github-password"
  }
}

2. Personal Access Token (PAT)

Use a PAT generated from your Git provider (e.g., GitHub Developer Settings).

{
  "Git": {
    "RepositoryUrl": "https://github.com/your-username/your-repo.git",
    "AuthenticationType": "Pat",
    // Username might be your actual username or a placeholder like "oauth2" depending on the provider
    "Username": "your-github-username", 
    "Password": "your-github-pat" // The PAT itself goes in the Password field
  }
}

3. SSH Key

Use SSH key pair authentication. Ensure the public key is added to your Git provider and the application has access to the private key file.

{
  "Git": {
    // Use the SSH URL format
    "RepositoryUrl": "git@github.com:your-username/your-repo.git", 
    "AuthenticationType": "Ssh",
    "SshUsername": "git", // Usually 'git' for GitHub/GitLab/Bitbucket
    "SshPublicKeyPath": "/path/to/your/.ssh/id_rsa.pub", // Absolute path to public key
    "SshPrivateKeyPath": "/path/to/your/.ssh/id_rsa",    // Absolute path to private key
    "SshPassphrase": null // Or "your-passphrase" if the private key is encrypted
  }
}

Note: Ensure the file paths are correct and the application has read permissions for the key files.

4. GitHub App

This method uses a dedicated service (IGitHubAppTokenProvider) to handle the generation, caching, and refreshing of GitHub App installation tokens.

How it works:

1. The GitHubAppTokenProvider service (registered as a singleton) is responsible for using your App's credentials (App ID, Installation ID, Private Key) to obtain installation tokens from the GitHub API using the Octokit library.
2. This service caches the token and handles refreshing it before it expires.
3. When cloning or fetching, the Git credential handler requests the current cached token from the IGitHubAppTokenProvider service.
4. This token is then used like a PAT for the Git operation.

Configuration:

Set AuthenticationType to GitHubApp and provide the necessary App details.

{
  "Git": {
    "RepositoryUrl": "https://github.com/your-username/your-repo.git",
    "AuthenticationType": "GitHubApp", 
    "GitHubAppId": 12345, // Your GitHub App's ID
    "GitHubAppPrivateKeyPath": "/path/to/your/app.private-key.pem", // Absolute path to the App's private key file
    "GitHubAppInstallationId": 98765 // The ID of the installation of your App on the target repository/organization
    // Username and Password fields are not used for this type
  }
}

Important Implementation Note:

The core logic for generating, caching, and refreshing the token within Services/GitHubAppTokenProvider.cs needs to be fully implemented. The current code provides the structure but contains placeholders for the actual Octokit calls and refresh mechanism.

Security: Treat the GitHub App private key file (.pem) as highly sensitive. Ensure it is stored securely and is not committed to version control.