AI Suite UI Integration & Custom Providers

tokomono/git-sync is built to pair directly with tokomono/ai-suite so non-developers and AI engineers can tweak prompts, roles, tones, and visual workflows in a test or staging UI and propose those changes back to the codebase via Pull Requests instead of modifying production files directly.

How AI Suite Detects tokomono/git-sync

In config/ai-suite.php, the overrides.environments setting controls how publishing a version behaves per environment:

'overrides' => [
    'environments' => ['test', 'staging'],
],

1. In local development (APP_ENV=local):
   • When you click Publish on a Workflow or Agent in the AI Suite UI (/ai-suite#/workflows or /ai-suite#/agents), AI Suite directly updates the PHP class file on disk (e.g. app/Ai/Workflows/ClaimHandlerWorkflow.php) and stores the updated file_hash.
2. In test or staging (APP_ENV=staging or APP_ENV=test):
   • When you click Publish in the AI Suite UI, WorkflowController::publish() checks class_exists(\Tokomono\GitSync\Providers\GitSyncServiceProvider::class).
   • Instead of overwriting local disk files on the staging server, AI Suite activates the version in the database and triggers the GitSync PR flow, returning: "Version published. PR creation triggered (GitSync)."

Step-by-Step: Publishing a Workflow or Agent Override via Git Sync in the UI

1. Edit in the AI Suite UI (staging / test):
   • Open /ai-suite#/workflows and click a workflow card to open the Visual Workflow Editor.
   • Adjust nodes, edges, or agent prompts on the canvas and click Save (New Version) in the top toolbar to create a new draft version (e.g. v2).
2. Test the Draft Version:
   • Use the Test Chat drawer on the right side of the canvas to verify the new version's behavior before publishing.
3. Publish & Trigger Git Sync:
   • Click the green Publish button in the top toolbar (or select a historical version from the version dropdown and click Publish vX).
   • Because the environment is listed in ai-suite.overrides.environments and tokomono/git-sync is installed, the publish action triggers the Git Sync Pull Request workflow against your configured repository (GITHUB_REPOSITORY or BITBUCKET_REPOSITORY).
4. Review & Merge on GitHub / Bitbucket:
   • Open the generated pr_url stored in git_sync_pull_requests to review the diff on GitHub or Bitbucket and merge it into your target branch (main, develop, or staging).

Registering a Custom GitProviderInterface (e.g. GitLab or Azure DevOps)

If your team uses GitLab, Gitea, or Azure DevOps, you can implement Tokomono\GitSync\Contracts\GitProviderInterface and bind it in your application's AppServiceProvider::register() method:

namespace App\Services\Git;

use Tokomono\GitSync\Contracts\GitProviderInterface;

class GitLabProvider implements GitProviderInterface
{
    public function createBranch(string $sourceBranch, string $newBranch): void
    {
        // Call GitLab Branches API: POST /projects/:id/repository/branches
    }

    public function commitFile(string $branch, string $filePath, string $content, string $commitMessage): void
    {
        // Call GitLab Commits API: POST /projects/:id/repository/commits
    }

    public function createPullRequest(string $sourceBranch, string $targetBranch, string $title, string $description): string
    {
        // Call GitLab Merge Requests API: POST /projects/:id/merge_requests
        return 'https://gitlab.com/your-org/your-repo/-/merge_requests/1';
    }
}

Then bind the interface in App\Providers\AppServiceProvider:

use App\Services\Git\GitLabProvider;
use Tokomono\GitSync\Contracts\GitProviderInterface;

public function register(): void
{
    $this->app->bind(GitProviderInterface::class, fn () => new GitLabProvider(
        config('services.gitlab')
    ));
}