By default, Spacelift communicates with your VCS provider directly. This is usually sufficient, but some users may have special requirements regarding infrastructure, security or compliance, and need to host their VCS system in a way that's only accessible internally, where Spacelift can't reach it. This is where VCS Agent Pools come into play.
A single VCS Agent Pool is a way for Spacelift to communicate with a single VCS system on your side. You run VCS Agents inside of your infrastructure and configure them with your internal VCS system endpoint. They will then connect to a gateway on our backend, and we will be able to access your VCS system through them.
On the Agent there are very conservative checks on what requests are let through and which ones are denied, with an explicit allowlist of paths that are necessary for Spacelift to work. All requests will be logged to standard output with a description about what they were used for.
Open the VCS Agent Pools panel, click Add VCS Agent Pool, give it a name and description, and you're done! A configuration token will be downloaded.
You can now run the launcher binary (downloaded from here) by setting three environment variables:
SPACELIFT_VCS_AGENT_POOL_TOKEN - the token you’ve received from Spacelift on worker pool creation
SPACELIFT_VCS_AGENT_TARGET_BASE_ENDPOINT - internal endpoint of your VCS system, including the protocol, as well as port, if applicable. i.e.
SPACELIFT_VCS_AGENT_VENDOR - the vendor of your VCS system, currently available options are gitlab, bitbucket_datacenter and github_enterprise.
Congrats! Your VCS Agent should now connect to the Spacelift backend and start handling connections.
Now whenever you need to specify an endpoint inside of Spacelift which should use your VCS Agent Pool, you should write it this way:
When trying to use this integration, i.e. by opening the Stack creation form, you'll get a detailed log of the requests:
A number of configuration variables is available to customize how your VCS Agent behaves:
SPACELIFT_VCS_AGENT_ALLOWED_PROJECTS - regular expression matching allowed projects for API calls. Projects are in the form: 'group/repository';
SPACELIFT_VCS_AGENT_PARALLELISM- number of streams to create. Each stream can handle one request simultaneously;
When the VCS Agent from a VCS Agent Pool is connecting to the gateway, you can send along some tags that will allow you to uniquely identify the process / machine for the purpose of debugging. Any environment variables using
SPACELIFT_METADATA_ prefix will be passed on. As an example, if you're running Spacelift VCS Agents in EC2, you can do the following just before you execute the VCS Agent binary:
export SPACELIFT_METADATA_instance_id=$(ec2-metadata --instance-id | cut -d ' ' -f2)
Doing so will set your EC2 instance ID as instance_id tag in your VCS Agent connections.