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
Homepage URL: https://velocity.codeclimate.com
User authorization callback URL: https://velocity.codeclimate.com/
Webhook URL: https://velocity.codeclimate.com/webhooks
Select the following read-only Permission and Event options:
Subscribe to Events:
Pull request review
Pull request review comment
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 \
--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.
VELOCITY_VCS_IDwith the ID listed for your VCS in the Available VCS table at the bottom of the agent settings page. Replace the
PRIVATE_KEYwith 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)