How to add a self-hosted GitLab repo to Tugboat.qa

00-tugboat-private-gitlab-howto.md

How to add a self-hosted GitLab repo to Tugboat

By default, Tugboat's GitLab integration uses OAuth to connect to GitLab Cloud. To add a repository to Tugboat that is hosted on a private or self-hosted GitLab instance, you'll need to use the Tugboat API.

Prerequisites

1. You must have administrator permissions on GitLab for the repo you would like to add to Tugboat.
2. You must already have an account on Tugboat and have created a Tugboat project. More on this below.
3. You must be an Admin or Owner on Tugboat for the aforementioned project in #2.

1. Open a command-line shell / terminal on your local computer

We're going to export some environment variables of the bits that we need to make this API call.

First, export the Tugboat Project ID for the Project that you'd like to add this GitLab repo to. To find the project ID, see https://docs.tugboat.qa/faq/find-tugboat-ids. Then run the following command in your shell, replacing [tugboat-project-id] with this ID.

export PROJECT=[tugboat-project-id]

If you don't have a Tugboat project, you'll need to create one by connecting any other repository to Tugboat. You can then remove the repo from the Tugboat Project afterward.

2. Create a Tugboat API access token

Since we'll be using the Tugboat API to add this repository, we need to generate an access token. Follow the instructions at https://docs.tugboat.qa/tugboat-cli/set-an-access-token/ to generate your access token.

Once you have the access token, switch back to your terminal and paste in the following line, replacing [your-tugboat-token] with this access token.

export TUGBOAT_TOKEN=[your-tugboat-token]

3. Create a Personal Access token on the self-hosted GitLab instance

1. Go to https://[your-gitlab.com]/-/profile/personal_access_tokens.
2. Name your token something recognizable, such as "Tugboat for ExampleOrg/ExampleRepo"
3. Under Select scopes check the checkbox next to api.
4. Save the token and switch back to your terminal and export the token as an environment variable, replacing [gitlab-api-token] with your new token.

export GL_TOKEN=[gitlab-api-token]

4. Export some additional environment variables

Export the public URL to your self-hosted GitLab instance, such as https://gitlab.example.com.

export GL_URL=[gitlab-url]

Export the GitLab namespace (the user or organization that owns the repository) for the repository as an environment variable, replacing [gitlab-namespace] with your organization.

export GL_NAMESPACE=[gitlab-namespace]

Export the repository name as an environment variable, replacing [gitlab-project-name] with the name of the repository you want to connect to Tugboat.

export GL_PROJECT=[gitlab-project-name]

Once you've done all the above, you can create an environment variable to integrate a few of these into a JSON payload that will be sent to the Tugboat API. Copy and paste this directly into your shell:

export PAYLOAD=$(printf '{
  "project": "%s",
  "provider": { "name": "gitlab", "address": "%s" },
  "repository": { "name": "%s", "group": "%s" },
  "auth": { "token": "%s" },
  "name": "%s/%s"
}' "$PROJECT" "$GL_URL" "$GL_PROJECT" "$GL_NAMESPACE" "$GL_TOKEN" "$GL_NAMESPACE" "$GL_PROJECT")

5. Make cURL request to the Tugboat API

Once that is complete, you are ready to make the cURL request to the Tugboat API to connect the GitLab Repo to Tugboat. Copy and paste this directly into your shell:

curl -H "Authorization: Bearer $TUGBOAT_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST -d "$PAYLOAD" \
     https://api.tugboat.qa/v3/repos

All the steps are in one place for those that might like it.

#!/bin/bash

PROJECT="xxx"
TUGBOAT_TOKEN="yyy"
GL_TOKEN="glpat-xxxx"
GL_URL="https://gitlab.example.com"
GL_NAMESPACE="org_name"
GL_PROJECT="awesome_repo_name"

PAYLOAD=$(printf '{
  "project": "%s",
  "provider": { "name": "gitlab", "address": "%s" },
  "repository": { "name": "%s", "group": "%s" },
  "auth": { "token": "%s" },
  "name": "%s/%s"
}' "$PROJECT" "$GL_URL" "$GL_PROJECT" "$GL_NAMESPACE" "$GL_TOKEN" "$GL_NAMESPACE" "$GL_PROJECT")


curl -H "Authorization: Bearer $TUGBOAT_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST -d "$PAYLOAD" \
     https://api.tugboat.qa/v3/repos

Thanks for that script @paulsheldrake. Works great for me 👍