All Collections
Getting Started
Setting Up
How do I connect to my on-premise GitHub Enterprise & Cloud Server?
How do I connect to my on-premise GitHub Enterprise & Cloud Server?
Emily Fueger avatar
Written by Emily Fueger
Updated over a week ago

If your server is not accessible from the public internet, and instead requires on-premise installation, please use the following instructions: 



1. Create a GitHub App within your GitHub organization

Go to your GitHub Organization -> Settings -> Developer settings -> Github Apps

Select the following read-only Permission and Event options: 

  • Repository Permissions:

    • Checks

    • Contents

    • Deployments

    • Issues

    • Metadata

    • Pull Requests

    • Projects

    • Commit Statuses

    • Security Alerts

  • Organization Permissions:

    • Members

    • Projects

  • User Permissions:

    • Email addresses

  • Subscribe to Events:

    • Issues

    • Issue comment

    • Pull request

    • Pull request review

    • Pull request review comment

    • Push

    • Repository

    • Status

Select Any account for Where can this GitHub App be installed? 


2. Create a VCS connection in Velocity

Go to Velocity -> Settings -> VCS

a. GitHub oAuth

  • Select "GitHub" as the VCS type

  • Enter the GitHub hostname, for example:

  • Enter the Client ID from the Github application in the 'OAuth client ID' field

b. GitHub App

  • External Id is the App ID of your GitHub app

  • Slug is the name of your GitHub app ****(lowercase, include dashes, visible in the GitHub URL)


3. Create an Agent for the VCS

Option 1: without persistent data

Next we want to setup the Agent which will be communicating with your configured VCS.

You should now see setup instructions for the agent.

Option 2: with persistent data

(uses Github App credentials, so use the flags below)

docker pull codeclimate/velocity-agent:latest-v2 && \
docker volume create velocity_agent_data && \
docker run \
--name velocity-agent \
--env VCS_ID=$VCS_ID \
--detach \
--restart=always \
--volume velocity_agent_data:/data \
--log-driver json-file \
--log-opt max-size=10m \
--log-opt max-file=10 \
--publish 5050:5050 \
--publish 4040:80 \


4. Run the Agent

On your provisioned server where the agent will operate: 

  • Run the provided setup commands.

  • The agent will start and run in the background.

  • Verify that the agent is up and running:

# verify that the container is running
$ docker ps

# follow the agent logs
$ docker ps | grep velocity-agent | cut -d " " -f1 | head -n 1 | xargs docker logs --follow --tail=20



5. Setup your VCS in the Agent

  • Copy the docker command under GitHub/GitHub Enterprise.

  • Replace the VELOCITY_VCS_ID with the ID listed for your VCS in the Available VCS table at the bottom of the agent settings page. Replace the GH_CLIENT_ID, GH_CLIENT_SECRET, GH_APP_ID, and PRIVATE_KEY with the values provided by GitHub.

  • run the command in the agent and you should see the response "Vcs created."


6. Connect your VCS user to Velocity

Authentication details for your VCS are passed securely to running agents via Velocity's API. This allows the Agent to interact with your internal VCS and report back to Velocity with repository information and metrics.

Now that you have your VCS and agent setup, you can connect to your VCS system via the agent.

  • Navigate to Identities

  • Personal > Identities

  • Click "Establish Connection" for your VCS.

7. Install GitHub App

  • If you successfully connected your GitHub Enterprise identity, you will see a link to "Install GitHub App".

  • Select the "Install GitHub App" link.

  • You'll be redirected to GitHub to authorize the application.

  • You'll be redirected back to Velocity where you'll see a Configure GitHub App link, which means your install of the app was successful.

8. Import repositories

  • Navigate to Repositories

  • Click the "Add repositories" button

  • Choose repositories to import into Velocity

Joining a Velocity organization using an Agent

  1. Accept the invitation, but do not authorize the Velocity OAuth to access your organization

  2. Navigate to your Personal Identities section:

  3. Establish a connection with your organization's VCS (this authorization should include organization access)

Did this answer your question?