Requirements

Setup

1. Create a GitLab App within your GitLab organization

In GitLab, go to your User Settings -> Applications

  • Add an app name - this can be anything

  • Enter the text below as the ‘Redirect URI’
    https://velocity.codeclimate.com/settings/vcs/auth/callback

Select the following scope options:

  • api (Access the authenticated user's API) We recommend setting up write access to the API so that we can install webhooks, but if you have reasons that prevent you from doing so, please reach out to our support team & we can work with you.

  • read_user (Read the authenticated user's personal information)

  • read_repository (Allows read-only access to the repository)

  • openid (Authenticate using OpenID Connect)

  • profile (Allows read-only access to the user's personal information using OpenID Connect)

  • email (Allows read-only access to the user's primary email address using OpenID Connect)

Click ‘Save application’, and note the ‘Application ID’ and ‘Secret’ fields for use when setting up the VCS in Velocity.

2. Create VCS in Velocity

In Velocity, go to Velocity -> Settings -> VCS -> ‘Add version control system’

  • Select ‘GitLab’ as the VCS type

  • Enter the GitLab host name - for example, ‘gitlab.company-name.net

  • Enter the ‘Application ID’ from the GitLab application in the ‘OAuth client ID’ field

  • Click ‘Create version control system’

3. Create an Agent for the VCS

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

You should now see setup instructions for the agent and a list of the VCS you associated with the agent.

4. Run the Agent

On your provisioned server where the agent will operate:

  • Based on your preference, run the Install with Docker or Install with Kubernetes script that's in the Agent page in Velocity.

  • 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. Connect your VCS user to Velocity

Copy the docker command under GitLab/GitLab Self Managed.

  • Replace the VELOCITY_VCS_ID with the ID listed for your VCS in the Available VCS table at the bottom of the agents settings page. Replace the GL_CLIENT_ID and GL_CLIENT_SECRET with the values provided by GitLab.

  • 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 Settings > Identities

  • Click "Establish Connection" for your VCS.

<a href=https://downloads.intercomcdn.com/i/o/152888671/2118419b582d22033e2fe778/connect_vcs_user.png"/>

Did this answer your question?