Self Hosted VCS

Centralized Management of Self Hosted Version Control Services (VCS)

Easily connect your Self Hosted VCS to env0. Once set up, you can effortlessly create self-hosted VCS templates and VCS environments within the system. Manage all VCS connections in a centralized page, allowing you to apply changes across all templates and environments.

🚧

This feature is available exclusively to customers using self-hosted agents

👍

Supported VCS

Using a self-hosted VCS provides you with all the features similar to a cloud-based VCS. including:

Add New VCS Connection

You can create a new connection in two ways; when creating a new template or through centralized management.

Option 1 - Create VCS Connection from Template Creation

  1. When configuring the VCS type, select one of the self-hosted supported VCS options.
  2. Click the Repository dropdown and select "Add VCS Connection".

Option 2 - Create VCS Connection from Agent Settings

  1. Go to "Organization Settings," select the "Agents" tab, and scroll down.
  2. Click "Create Connection"

Create VCS Connection

  1. Choose the VCS type and enter a "Connection Name".
  2. Select the "Agent Key" to which all requests will be forwarded (VCS Agent - Running Proxy).
    1. To create a new agent key, please contact support.
    2. The dropdown is available only to users with the "Edit Organization Settings" permission.
  3. Enter VCS or Repository URL
    1. If you specify a VCS URL, such as http://my-vcs.company.com, all requests not linked to a specific repository URL will be forwarded to this VCS Agent. When creating a template, you will also see all available repositories from this VCS
    2. If you specify a specific repository URL, all requests for that repository will be forwarded to this VCS Agent. Additionally, during template creation, only this specific repository will be listed.
  4. The Authentication section is used to configure the webhook connection for the self-hosted VCS.
  5. Click "Save Connection"

🚧

Forward requests to this VCS Agent

The intention behind forwarding requests refers to all the requests the platform needs to support the features mentioned above. It does not refer to where the deployment actually runs; it will continue to run based on the project to which it is assigned.

Configure VCS agent (Proxy)

Running a proxy can be achieved in two ways; as part of the agent's Kubernetes helm chart deployment or as a standalone Docker instance.

Agent's Kubernetes Helm Chart

  1. The installation is included as part of the agent's Kubernetes Helm chart deployment.
  2. By default, the proxy runs when the agent is installed without any special configuration.
  3. Proxy Configuration: Configure it in the values.yml file
    1. agentProxy:
      	install: true # default true
      	replicas: 1 # how many replicas of the agent proxy to use. Default is 1
      	maxConcurrentRequests: 500 # how many concurrent requests each pod should handle. Default is 500
      	limits: # k8s (cpu and memory) limits. Default is 250m and 500Mi
      		cpu: 250m
      		memory: 500Mi
      bitbucketServerCredentialsEncoded: base64= # Base64 Bitbucket server credentials in the format `username:token (using a Personal Access token)
      gitlabEnterpriseCredentialsEncoded: base64= # Base64 Gitlab Enterprise credentials in the form of an Access token	
      githubEnterpriseAppId: 1 # For more details, check out https://docs.env0.com/docs/github-enterprise-integration
      githubEnterpriseAppClientId: "Iv1.ClientId"
      githubEnterpriseAppInstallationId: 1
      githubEnterpriseAppClientSecretEncoded: "base64=="
      githubEnterpriseAppPrivateKeyEncoded: "base64=="
      
      Refer to the Self Hosted Kubernetes Agent specifications for additional configuration details.

Standalone VCS Agent Docker Instance

  1. Run the VCS agent Docker image with the following command:
    docker run --env-file ~/path/to/env0.env ghcr.io/env0/vcs-agent:latest
    
  2. For more details, see Standalone Docker Agent - Running a VCS Agent.

🚧

env0 communication with VCS Agent

The communication is one-way: the VCS agent connects to the env0 platform. This means that when the env0 platform forwards a request to the VCS agent, we cannot immediately determine if the communication was successful or if the proxy is alive until the timeout period (~25s).

If something isn't working as expected, check the VCS agent logs to see if the requests are being received

Configure Webhook Integration

This section outlines the steps required to configure webhook integration for your VCS. Follow the instructions to set up the webhook and ensure it works seamlessly with your system.

  1. When you Create VCS connection you will find the Authentication section.
  2. At the bottom of the window, you will see this section. From here, you need to obtain the webhook URL and webhook secret.
  3. Configure Webhook Integration per Self-Hosted VCS:
    1. Github Enterprise
    2. Bitbucket Data Center
    3. Offline Gitlab

❗ī¸

Please ensure that only one entry is created for Webhook Integration. Creating multiple entries may result in duplicate events and cause multiple deployments for the same change.