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

Requirements

Requirements for on-premise servers

Setup

1. Create a GitHub App within your GitHub organization

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

Homepage URL: https://velocity.codeclimate.com
User authorization callback URL: https://velocity.codeclimate.com/
Setup URL: https://velocity.codeclimate.com/github/setup-callback
Webhook URL: https://velocity.codeclimate.com/webhooks

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 https://velocity.codeclimate.com/settings/vcs/new

a. GitHub oAuth

Select "GitHub" as the VCS type
Enter the GitHub hostname, for example: github.company-name.net
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.

Navigate to the Agents settings section: https://velocity.codeclimate.com/settings/agents/new
Click "Create agent"

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 AGENT_ID=$AGENT_ID 
    --env AGENT_TOKEN=$AGENT_TOKEN 
    --env VCS_ID=$VCS_ID 
    --env VCS_CLIENT_ID=$VCS_CLIENT_ID 
    --env VCS_CLIENT_SECRET=$VCS_CLIENT_SECRET 
    --env VCS_GITHUB_APP_ID=$VCS_GITHUB_APP_ID 
    --env VCS_PRIVATE_KEY=$VCS_PRIVATE_KEY 
    --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 
    codeclimate/velocity-agent:latest-v2

---

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:

bash
# 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

Accept the invitation, but do not authorize the Velocity OAuth to access your organization
Navigate to your Personal Identities section: https://velocity.codeclimate.com/settings/identities
Establish a connection with your organization's VCS (this authorization should include organization access)