# git-ecosystem/git-credential-manager architecture

> Architecture diagram of the GitHub repository git-ecosystem/git-credential-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/git-ecosystem/git-credential-manager
- Repository: https://github.com/git-ecosystem/git-credential-manager

## Overview

##### Project type and purpose
- This is a cross‐platform Git credential helper built on .NET. Its primary purpose is to provide secure, multi‐factor authentication support (via both UI and command line) for various Git repository hosts (such as GitHub, Bitbucket, GitLab, and Azure DevOps) on Windows, macOS, and Linux.
- It is designed to be invoked indirectly by Git operations (for example, during a git push) and then internally manages authentication flows, credential storage, and OS-specific interactions.

##### File structure to extract architectural components
- There are platform-specific directories under src (src/windows, src/osx, src/linux) which indicate that the project has distinct installer and integration logic per operating system.
- The shared folder (src/shared) contains common logic broken out into several modules:
– Core: Implements the common authentication flows, UI, command handlers, credential caching/storing, and abstractions/interfaces.
– Integrations for third-party hosts (e.g., GitHub, GitLab, Atlassian Bitbucket, Microsoft AzureRepos) have their own subdirectories with dedicated functionality.
– UI implementations are visible in different “UI” subfolders (for instance, under GitHub/UI, Core/UI, and GitLab/UI) and are most likely built using Avalonia or similar frameworks.
- Build, documentation (docs/architecture.md, among others), and test directories clearly imply a layered and modular approach.

##### Hints from the README
- The README emphasizes the need for secure, consistent cross-platform authentication.
- The project description and support matrix (detailing installer/uninstaller support, multi-factor authentication, etc.) suggest enforcing separation between platform-specific concerns and core authentication/meta-logic.
- The “How to use” portion implies that GCM is designed to be automatically invoked within the Git workflow.

- Git Client (external component) – Represents how Git calls out to the credential manager.
- Core Application Logic – This central module includes:
▪ Command processing and authentication workflows.
▪ Credential storage abstraction (secure storage interfaces for different OS platforms).
▪ Shared components such as diagnostics, configuration, logging, and UI command bindings.
- Platform-Specific Adapters / Installers:
▪ Windows Installer & Windows-specific interop components,
▪ macOS Installer with codesign, notarization, keychain integration,
▪ Linux packaging scripts and secret service handling.
- Authentication Providers:
▪ Separate modules for GitHub, Bitbucket, GitLab, and Azure DevOps. These can be represented as individual components which the core logic interacts with via defined interfaces (using strategy patterns).
- UI Components:
▪ User authentication dialogs and credential prompts built using Avalonia.
- External Services & Credential Storage:
▪ System-specific secure storage (Windows Credential Manager, macOS Keychain, Linux Secret Service, etc.).
b. Relationships and interactions:
- The core then delegates to the appropriate authentication provider (selecting the right strategy based on the Git remote).
- Once the authentication is complete, the credential is stored or retrieved using the platform adapter.
- The UI components interact with the user when multi-factor or two-factor input is needed.
c. Architectural patterns/design principles:
- Layered Architecture: Clearly separate core logic from OS-specific implementations.
- Adapter/Facade Pattern: Use adapters to allow the same core logic to talk to different platform-specific credential stores.
- Strategy Pattern: For handling various authentication flows for different providers.
- Dependency injection is likely used to allow for modular tests (see the extensive test directories in the shared code).
d. Technologies and frameworks:
- .NET as the underlying framework.
- Avalonia (inferred from the “.axaml” files) for cross-platform UI.
- A mixture of shell scripts and MSBuild targets for building and packaging on different platforms.
- Git integrations and possibly REST APIs for calling out to third-party authentication endpoints.

##### Summary / Practical Steps
- Next, detail the underlying modules within the GCM Core: separate out the common libraries (in src/shared/Core), integration modules (under GitHub, GitLab, Bitbucket, etc.), and the interop layers that interact with the operating system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Git Client"]:::external
    B["GCM Core (Authentication & Credential Management)"]:::core

    subgraph "Authentication Providers"
        B1["GitHub Provider"]:::auth
        B2["Bitbucket Provider"]:::auth
        B3["GitLab Provider"]:::auth
        B4["Azure DevOps Provider"]:::auth
    end

    subgraph "UI Components"
        C1["Core UI"]:::ui
        C2["GitHub UI"]:::ui
        C3["Bitbucket UI"]:::ui
        C4["GitLab UI"]:::ui
    end

    subgraph "Platform-Specific Adapters"
        D1["Windows Adapter"]:::platform
        D2["macOS Adapter"]:::platform
        D3["Linux Adapter"]:::platform
    end

    subgraph "Secure Storage & External Services"
        E1["Windows Credential Manager"]:::storage
        E2["macOS Keychain"]:::storage
        E3["Linux Secret Service"]:::storage
    end

    A -->|"invokes"| B
    B -->|"delegates"| B1
    B -->|"delegates"| B2
    B -->|"delegates"| B3
    B -->|"delegates"| B4

    B -->|"triggers"| C1
    B1 -->|"UI_MFA"| C2
    B2 -->|"UI_MFA"| C3
    B3 -->|"UI_MFA"| C4

    B -->|"stores"| D1
    B -->|"stores"| D2
    B -->|"stores"| D3

    D1 -->|"interop"| E1
    D2 -->|"interop"| E2
    D3 -->|"interop"| E3

    classDef external fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef core fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef auth fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef ui fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef platform fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef storage fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    click B "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Core"
    click D1 "https://github.com/git-ecosystem/git-credential-manager/blob/main/src/windows/Installer.Windows"
    click D2 "https://github.com/git-ecosystem/git-credential-manager/blob/main/src/osx/Installer.Mac"
    click D3 "https://github.com/git-ecosystem/git-credential-manager/blob/main/src/linux/Packaging.Linux"
    click B1 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/GitHub"
    click B2 "https://github.com/git-ecosystem/git-credential-manager/blob/main/src/shared/Atlassian.Bitbucket"
    click B3 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/GitLab"
    click B4 "https://github.com/git-ecosystem/git-credential-manager/blob/main/src/shared/Microsoft.AzureRepos"
    click C1 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Core/UI"
    click C2 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/GitHub/UI"
    click C3 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Atlassian.Bitbucket/UI"
    click C4 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/GitLab/UI"
    click E1 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Core/Interop/Windows"
    click E2 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Core/Interop/MacOS"
    click E3 "https://github.com/git-ecosystem/git-credential-manager/tree/main/src/shared/Core/Interop/Linux"
```
