Git Driver

Introduction

The Git Driver enables your Kipchak application to interact with remote Git repositories programmatically. It handles cloning, fetching, and checking out specific branches via HTTPS. This is particularly useful for configuration management, content-as-code (CMS) backends, or deployment workflows.

Key features include:

• Multi-Repository Support: Manage multiple repositories simultaneously within a single configuration.
• HTTPS Only: Enforces HTTPS for all connections (SSH is strictly disabled for security compliance).
• Automated Auth: Seamlessly handles username/password or Personal Access Token (PAT) authentication.
• Branch Management: Automatically checks out specific branches upon initialization.

Installation

Install the driver via composer by running:

composer require kipchak/driver-git

Initialise the Driver

Add the following line to your drivers/drivers.php file:

\Mamluk\Kipchak\Driver\Git\Git::iniitalise($container);

Configuration

The configuration in kipchak.s3.php can be used to configure a global storage location and a list of managed repositories.

Global Settings

• settings.clone_dir: The local filesystem path where repositories will be cloned. Ensure the web server user has write permissions to this directory.
  • Default: /tmp/kipchak-git

Repository Configuration

Define your repositories in the repositories array. Each key (e.g., 'default', 'starter') acts as an alias.

• origin: The clone URL. Must be HTTPS. (e.g., github.com/user/repo.git).
• username: The username for authentication.
• password: The password or Personal Access Token (PAT).
• branch: The branch to check out after cloning (e.g., master, main, v1.0).

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    // Global storage location
    'settings' => [
        'clone_dir' => '/tmp/kipchak-git'
    ],

    // Repository definitions
    'repositories' => [
        'default' => [
            'origin'   => '1x.ax/mamluk/kipchak/core.git',
            'username' => env('GIT_USERNAME', ''),
            'password' => env('GIT_PASSWORD', ''),
            'branch'   => 'master' // Branch to check out after cloning
        ],
        'cms_content' => [
            'origin'   => '[github.com/my-org/static-content.git](https://github.com/my-org/static-content.git)',
            'username' => env('GITHUB_USER', ''),
            'password' => env('GITHUB_TOKEN', ''),
            'branch'   => 'production'
        ],
    ]
];

Please see the configuration file in the starter project at https://1x.ax/mamluk/kipchak/starter/~files/master/config/kipchak.git.php for full configuration details.

Usage

Environment Variables

Define your credentials in the .env file to keep them secure.

GIT_USERNAME=my-service-account
GIT_PASSWORD=ghp_MyPersonalAccessToken123

Code Example

The driver allows you to select a repository by its alias and perform operations like syncing (clone/pull) or accessing files.

<?php

use Kipchak\Drivers\Git\Git;

// 1. Initialize the client
$repo = Git::get('default'); // default is the connection name in the config file.

// 3. Sync changes
// Pulls the latest changes from the configured branch
$repo->pull();

// 3. Get branches
$branches = $repo->getBranches();

// ...

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/drivers/git.