Custom VCS

Custom VCS integrations let you connect any Git or Mercurial version control system to Pulumi Deployments, including self-hosted and third-party servers. You configure webhooks on your VCS server to notify Pulumi Cloud when commits are pushed, and Pulumi automatically triggers deployments for matching stacks.

Unlike the first-party GitHub, GitLab, and Azure DevOps integrations, Custom VCS uses ESC environments for credential management and requires manual webhook configuration. It supports push-to-deploy but does not support pull request comments, commit status checks, or review stacks.

Neo, Pulumi’s AI assistant, can clone and push to Git and Mercurial repositories registered with a Custom VCS integration using the credentials from the integration’s ESC environment. Neo cannot open pull requests or create new repositories on Custom VCS servers at this time. Those operations require VCS-specific APIs only available through native integrations.

Prerequisites

• A Pulumi Cloud organization
• A Git or Mercurial VCS server accessible from Pulumi Cloud (for cloning)
• Org admin access in Pulumi Cloud
• An ESC environment containing your VCS credentials (see Configure credentials in ESC)

Configure the integration

1. Sign in to your Pulumi account.
2. Navigate to Management > Version control.
3. Select Add integration and choose Custom VCS.
4. Enter a Name for the integration (e.g., “My Git Server”). Names must be unique within your organization.
5. Enter a Base URL — the URL prefix for your repositories (e.g., https://git.example.com/myorg). Repository names are appended to this URL to form clone URLs.
6. Select the ESC environment containing your VCS credentials, in project/envName format (e.g., vcs-creds/git-prod).
7. Select Save.

By default, Custom VCS integrations are created with a VCS type of git. To configure a Mercurial integration, create the integration via the Pulumi Cloud REST API with vcsType set to hg.

After saving, Pulumi displays a webhook URL and webhook secret.

Configure credentials in ESC

Custom VCS integrations use an ESC environment to store VCS credentials. The same credential structure works for both Git and Mercurial integrations. Create an environment with one of the following authentication methods:

Personal access token

values:
  personalAccessToken:
    fn::secret: "your-token-here"

SSH key

values:
  sshPrivateKey:
    fn::secret: |
      -----BEGIN OPENSSH PRIVATE KEY-----
      ...
      -----END OPENSSH PRIVATE KEY-----
  sshPassword:
    fn::secret: "optional-passphrase"

Basic auth

values:
  username: "deploy-bot"
  password:
    fn::secret: "your-password"

Credentials are resolved at deployment time using the access permissions of the user who configured the integration. If that user loses access to the ESC environment, deployments will fail with an authentication error.

Add repositories

Custom VCS integrations do not auto-discover repositories from your VCS server. You must add each repository manually.

1. Navigate to Management > Version control and select your Custom VCS integration.
2. Select Add repository.
3. Enter the repository name or path (e.g., infra-prod or team/infra-prod).
4. Optionally enter a display name for the repository.

The repository name is joined with the integration’s base URL to form the clone URL. For example, a base URL of https://git.example.com/myorg and a repository name of infra-prod produces the clone URL https://git.example.com/myorg/infra-prod.

To remove a repository, select the repository from the integration detail page and choose Remove.

Configure webhooks

After creating the integration and adding repositories, configure your VCS server to send webhook notifications to Pulumi Cloud.

Webhook URL

Configure your VCS server to send POST requests to:

https://api.pulumi.com/workflow/generic-vcs

Required headers

Your webhook requests must include the following headers:

Payload format

The request body must be a JSON object with the following fields:

{
  "event": "push",
  "commit": "abc123def456789...",
  "branch": "main",
  "repoUrl": "https://git.example.com/myorg/infra-prod",
  "sender": "deploy-bot",
  "changedFiles": ["infra/main.go", "Pulumi.yaml"]
}

HMAC signing

Pulumi verifies webhook authenticity using HMAC-SHA256 signatures. To sign a request:

1. Compute HMAC-SHA256(webhook_secret, raw_request_body) using the webhook secret provided during integration setup.
2. Hex-encode the result.
3. Set the header: X-Generic-VCS-Signature: v1=<hex-encoded-hmac>.

The v1 prefix identifies the signing algorithm version.

Deployment settings

Configure deployment behavior for Custom VCS-backed stacks under Stack > Settings > Deploy.

Selecting a repository and branch

1. Choose the Custom VCS integration (if multiple are configured).
2. Select a repository from the dropdown. This list shows the repositories you have manually configured on the integration.
3. Enter the target branch name.

Comparison with native integrations

Custom VCS provides webhook-driven push-to-deploy but does not include the deeper VCS platform features available with native integrations.

Troubleshooting