VCS Proxy

VCS Proxy to connect to customer's VCS in private networks.

The Resourcely VCS Proxy provides secure access to Version Control System (VCS) APIs, such as GitHub and GitLab, within private networks. It establishes a secure ngrok tunnel to the Resourcely infrastructure, enabling seamless communication between Resourcely and your internal VCS without exposing these systems to the public internet. This setup ensures that Resourcely can interact with on-premise VCS environments while maintaining robust security and privacy.

How does it work?

The proxy is a very shallow wrapper around the Ngrok agent. At startup, it connects to a specific Ngrok https edge, listens for incoming requests from the Resourcely backend, and proxies those requests to the VCS (eg GitHub/GiLab) endpoints. Thus, the Proxy does not need to accept ingress traffic.

Security Benefits

This proxy only forwards requests to the environment values of RESOURCELY_VCS_API_SERVER and RESOURCELY_VCS_WEB_SERVER. This allows you to restrict the containers egress traffic to only allow access to your VCS instances.

Additionally, we use a custom egress domain (tunnel.<region>.proxy.resourcely.io) for establishing the tunnel between this container and ngrok. Because of this, instead of your firewall needing to allow egress to a generic ngrok domain, you can use this Resourcely specific domain. Doing this ensures that only Resourcely owned ngrok edges can be accessed from within your firewall.

Authentication?

Authentication is required both ways. The Ngrok edge network will authenticate requests coming from Resourcely before relaying them to this Proxy. Likewise, the edge network requires this proxy to provide a valid auth token to connect and listen for incoming requests.

Setup?

The Proxy is intended to be run in a Docker container that is allowed to reach out and connect to the Ngrok edge network. Thus traffic egress must be allowed, but ingress is not needed.

The Proxy uses the following variables in the environment (can be fed to the Docker container):

Required

• RESOURCELY_VCS_PROVIDER: Which VCS is the proxy destination: eg: gitlab, github

• RESOURCELY_NGROK_EDGE: Label of the ngrok edge to connect to. Same as the edge= value in the ngrok agent tunnel command: ngrok tunnel --label edge=edghts_1 https://github.acme.com

• RESOURCELY_NGROK_TOKEN: Token used by the ngrok agent to authenticate with ngrok edge

• RESOURCELY_VCS_API_SERVER: Origin server at which the VCS API can be accessed including the scheme. eg https://api.github.com

• RESOURCELY_VCS_WEB_SERVER: Origin server at which repositories can be accessed in a browser from the VCS including the scheme. eg https://github.com

Optional

• RESOURCELY_EGRESS_REGION: The region that this container will use to tunnel to ngrok's proxy. Must be one of: [in,us,us-cal-1,eu,au,ap,jp]. Defaults to us

Configure VCS Proxy

To ensure that you onboard smoothly on the proxy, you need to make sure the following is true:

• You can run our VCS-proxy container and allow egress traffic to the Ngrok proxy domain tunnel.<region>.proxy.resourcely.io, and valid values for region are [in,us,us-cal-1,eu,au,ap,jp]on port 443 .
• You have VCS admin permissions as some administrative actions are needed, such as creating a VCS app and webhook.

• Your Self-hosted VCS webhooks can reach our API api.resourcely.io over port 443.

1. Running the Proxy

Option 1: Kubernetes

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  creationTimestamp: null
  labels:
    app: vcs-proxy
  name: vcs-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vcs-proxy
  strategy: {}
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: vcs-proxy
    spec:
      containers:
      - image: ghcr.io/resourcely-inc/vcs-proxy:latest
        name: vcs-proxy
        env:
          - name: RESOURCELY_NGROK_EDGE
            value: <RESOURCELY_NGROK_EDGE>
          - name: RESOURCELY_VCS_API_SERVER
            value: <GITLAB_API_SERVER>
          - name: RESOURCELY_VCS_WEB_SERVER
            value: <GITLAB_WEB_SERVER>
          - name: RESOURCELY_NGROK_TOKEN
            value: <TOKEN>
          - name: RESOURCELY_VCS_PROVIDER
            value: <GITLAB_OR_GITHUB>  # Replace with 'gitlab' or 'github'

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml

Option 2: docker-compose.yml

You can use docker-compose.yml to run the container with the required environment variables and configurations, similar to what’s specified in the Kubernetes deployment.yaml file:

# docker-compose.yml
version: '3.8'

services:
  vcs-proxy:
    image: ghcr.io/resourcely-inc/vcs-proxy:latest
    container_name: vcs-proxy
    environment:
      - RESOURCELY_NGROK_EDGE=<RESOURCELY_NGROK_EDGE>
      - RESOURCELY_VCS_API_SERVER=<GITLAB_API_SERVER>
      - RESOURCELY_VCS_WEB_SERVER=<GITLAB_WEB_SERVER>
      - RESOURCELY_NGROK_TOKEN=<TOKEN>
      - RESOURCELY_VCS_PROVIDER=<GITLAB_OR_GITHUB>  # Replace with 'gitlab' or 'github'
    ports:
      - "8080:8080"  # or whatever port you need.
    restart: unless-stopped

Replace the placeholders in angle brackets (<...>) with your actual values.

Running the Container

To start the container, use the following command in the directory where your docker-compose.yml is located:

docker-compose up -d

Or, if you prefer to run it directly using docker run without docker-compose:

docker run -d \
  --name vcs-proxy \
  -e RESOURCELY_NGROK_EDGE=<RESOURCELY_NGROK_EDGE> \
  -e RESOURCELY_VCS_API_SERVER=<GITLAB_API_SERVER> \
  -e RESOURCELY_VCS_WEB_SERVER=<GITLAB_WEB_SERVER> \
  -e RESOURCELY_NGROK_TOKEN=<TOKEN> \
  -e RESOURCELY_VCS_PROVIDER=<GITLAB_OR_GITHUB> \
  -p 8080:8080 \
  ghcr.io/resourcely-inc/vcs-proxy:latest

2. Create and install Resourcely App

Gitlab Setup

Step 1: GitLab OAuth application

Resourcely needs a GitLab OAuth application so users can authorize us to open PRs and browse repos. The application should be named “Resourcely” and have the settings in the image below

You can create the application quickly using the following cURL command:

curl --request POST --header "PRIVATE-TOKEN: <your-gitlab-access-token>" \
     --data "name=Resourcely&redirect_uri=https://api.resourcely.io/git/v1/gitlab-callback&scopes=api read_user email openid profile" \
     "<your-gitlab-url>/api/v4/applications"

Example Response (Resourcely will need this info):

{
    "id": 2,
    "application_id": "<app-id>",
    "secret": "<secret>",
    "application_name": "Resourcely",
    "callback_url": "https://api.resourcely.io/git/v1/gitlab-callback",
    "confidential": true
}

Please save the response and share it with Resourcely using secret sharing tool.

Resourcely will complete Step 1 onboarding using information above before proceeding

Step 2: Install the App from the UI

1. Go to https://portal.resourcely.io/settings/change-management
2. Connect with Gitlab and follow instructions here https://docs.resourcely.io/resourcely-terms/settings/change-management/gitlab

Github Setup

Step 1: Github application

Resourcly needs a Github application so users can authorize us to open PRs and browse repos.

1. Navigate to this link (please substitute GITHUB_URL and GITHUB_ORG)

https://<GITHUB_URL>/organizations/<GITHUB_ORG>/settings/apps/new?name=resourcelybot&description=A%20Github%20app%20to%20manage%20automated%20pull%20requests%20generated%20by%20Resourcely&callback_urls[]=https://api.resourcely.io/api/v1/change-management/github/registrations/callback&callback_urls[]=https://api.resourcely.io/git/v1/github-callback&url=https://portal.resourcely.io&request_oauth_on_install=true&setup_on_update=false&public=false&webhook_active=false&webhook_url=https://api.resourcely.io/git/v1/github-webhook&checks=write&contents=write&issues=write&members=read&metadata=read&organization_hooks=read&pull_requests=write&repository_hooks=write

1. Choose “Only on this account”

2. Click “Create Github App”

3. On next screen, copy your App ID, Client ID, and Client Secret (click Generate a new client secret)

1. At the bottom of the screen, generate a private key, it will download a .pem file - to get the base64 value of the .pem file, find where the file was downloaded and run

cat <path-to-pem> | base64

Please save the response and share it with Resourcely using secret sharing tool.

Resourcely will complete Step 1 onboarding using information above before proceeding

Step 2: Install the oAuth App via CURL command

1. Get Resourcely Token JWT token from browser https://portal.resourcely.io/

2. Replace token and github_host

curl --location 'https://api.resourcely.io/api/v1/change-management/github/registrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT_TOKEN>' \
--data '{
    "auto_approve_enabled": true,
    "github_host": "<github_host>",
    "next_url": "https://portal.resourcely.io/settings/change-management?version_control=github&step=1&version_control=github"
    }'

1. Navigate to the installation URL in the response of the request above and follow installation flow.

2. Then you will get kicked back to step 2 of the change management onboarding flow where you can create a Webhook.