Connect to Private VCS Providers

This article describes the steps required to configure connect HCP Terraform to your private VCS provider using a self-hosted HCP Terraform agent.

Background

You can use HCP Terraform agents to connect HCP Terraform to your private VCS providers. The following are examples of private VCS providers that you can manage locally on your private network:

• GitHub Enterprise
• GitLab Enterprise
• BitBucket Data Center

For more information about HCP Terraform agents, refer to the HCP Terraform agent documentation.

Requirements

You must meet the following requirements to configure a connection to your private VCS provider:

• HCP Terraform agent v1.15.0 or newer.
• Network connectivity between the HCP Terraform agent and private VCS provider.
• Outbound network connectivity from the HCP Terraform agent to HCP Terraform. Refer to networking requirements for more information.

Configure the agent pool and agent

Before you start your HCP Terraform agent, you must create an agent pool and token. Refer to Create an Agent Pool for a list of steps to create an agent pool.

To configure your HCP Terraform agent with private VCS support, you must set the following environment variables in the environment you run the agent. You can also set these environment variables with optional command-line flags.

Below is an example command to start the HCP Terraform agent:

$ export TFC_AGENT_TOKEN=<...>

$ _TFC_AGENT_REQUEST_FORWARDING_ENABLED=true \
  tfc-agent \
  -name private-vcs-test-01 \
  -request-forwarding=true \
  -accept "ingress" \
  -log-level "debug"

Configure the private VCS connection

To create a private VCS connection, complete the following steps:

1. In HCP Terraform, navigate your organization's Settings page.
2. Under Version Control, click Providers.
3. Click Add a VCS provider.
4. Select your VCS Provider.This must be a self-managed provider, such as GitHub Enterprise.
5. Under VCS Access, select “Private”.
6. Select the agent pool that you created for private VCS.
7. The remainder of the setup follows the standard VCS setup workflow. Refer to the standard VCS setup instructions for provider specific instructions.

Troubleshooting

There are two sources of information to help diagnose issues with Private VCS and the HCP Terraform agent:

1. HCP Terraform agent logs

• These display events as seen by the HCP Terraform agent.
• They can aid in diagnosing errors between the HCP Terraform agent and the VCS provider during VCS ingestion, as well as any issues occurring during request forwarding.

1. VCS events in HCP Terraform (Organization Settings > Version Control > Events)

• VCS events include errors that have resulted from making requests for private VCS during setup of the VCS Connection, and during normal operation.
• This will not include messages during normal operations of private VCS.

To aid in troubleshooting, you can increase the verbosity of the HCP Terraform agent's log messages to debug and trace and retry the attempted action. Refer to Install and Run Agents for more information.