utopia-php/vcs

A simple library to integrate version control systems like GitHub, GitLab etc. to receive webhook events

5.2.4 2026-08-21 13:45 UTC

Requires

• php: >=8.4
• adhocore/jwt: ^1.1
• utopia-php/cache: ^4.0 || ^5.0
• utopia-php/fetch: ^1.1

Requires (Dev)

• utopia-php/system: 0.10.*

MIT

• framework
• php
• vcs
• utopia

Published on Packagist.org on 2026-08-21 13:56 UTC

README

Important

This repository is a read-only mirror of the utopia-php monorepo. Development happens in packages/vcs — please open issues and pull requests there.

Utopia VCS is a simple and lite library for interacting with version control systems (VCS) in Utopia-PHP using adapters for different providers like GitHub, GitLab etc. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Getting started

Install using Composer:

composer require utopia-php/vcs

Init in your application:

<?php

require_once __DIR__ . '/../../vendor/autoload.php';

use Utopia\VCS\Adapter\Git\GitHub;

// Initialise your adapter
$github = new GitHub();

// Your GitHub app private key. You can generate this from your GitHub App settings.
$privateKey = 'your-github-app-private-key';

// Your GitHub App ID. You can find this in the GitHub App dashboard.
$githubAppId = 'your-github-app-id';

// Your GitHub App installation ID. You can find this in the GitHub App installation settings.
$installationId = 'your-github-app-installation-id';

// Initialise variables
$github->initializeVariables($installationId, $privateKey, $githubAppId);

// Perform the actions that you want, ex: create repository
$owner = '<repository-owner>';
$name = '<repository-name>';
$isPrivate = true; // Set to false if you want to create a public repository
$repository = $github->createRepository($owner, $name, $private);

Environment variables

To configure your GitHub App, set the following environment variables in your environment or configuration file. The adapter authenticates with the GitHub API on behalf of your app with them.

1. PRIVATE_KEY: generate this from your GitHub App settings.

PRIVATE_KEY = your-github-app-private-key

1. GITHUB_APP_ID: find this in the GitHub App dashboard.

GITHUB_APP_ID = your-github-app-id

1. INSTALLATION_ID: find this in the GitHub App installation settings after installation.

INSTALLATION_ID = your-github-app-installation-id

Replace the placeholders with the actual values from your GitHub App configuration. Reading them from the environment keeps the credentials out of your codebase.

Supported adapters

Adapter	Status
GitHub	✅
GitLab	✅
Bitbucket	✅
Gitea	✅
Forgejo	✅
Gogs	✅
Origin (Cursor)	✅
Azure DevOps

✅ - supported, 🛠 - work in progress

System requirements

Utopia VCS requires PHP 8.4 or later.

Adding an adapter

See docs/add-new-vcs-adapter.md.

Tests

The unit tier parses webhook deliveries and verifies their signatures, and needs nothing running:

composer test

The e2e tier drives the adapters against real providers. Gitea, Forgejo, Gogs, and GitLab come from docker-compose.yml, each published on an offset host port and bootstrapped with an access token the tests read from tests/.tokens:

docker compose up -d --wait   # GitLab alone takes a few minutes to come up
composer test:e2e
docker compose down -v

bin/monorepo test vcs runs both tiers, stack included. The GitHub and Bitbucket suites talk to the hosted products, so they skip unless their credentials are in the environment: TESTS_GITHUB_PRIVATE_KEY, TESTS_GITHUB_APP_IDENTIFIER, and TESTS_GITHUB_INSTALLATION_ID for GitHub, TESTS_BITBUCKET_ACCESS_TOKEN and TESTS_BITBUCKET_WORKSPACE for Bitbucket.

License

MIT