# GitLab

Connect your private GitLab repository to Valohai using SSH authentication. GitLab deploy keys provide secure, read-only access and can be reused across multiple projects.

## Requirements

* A private GitLab repository
* A Valohai project
* Maintainer access to the repository (to add deploy keys)

## Overview

You'll complete three steps:

1. Generate an SSH key pair (in Valohai)
2. Add the public key to GitLab as a deploy key
3. Add the private key to Valohai

## Step 1: Generate SSH Key Pair

The easiest way is to generate the key pair directly in Valohai.

**In Valohai:**

1. Open your project
2. Go to **Settings** → **Repository**
3. Click **Generate SSH Key**
4. Download or copy both keys:
   * `valohai-public_xxx.pub` (public key)
   * `valohai-private_xxx.pem` (private key)

Keep these files handy—you'll need them in the next steps.

### Alternative: Generate Locally

If you prefer, generate keys on your local machine:

```shell
ssh-keygen -t rsa -b 4096 -f valohai-deploy-key
```

This creates:

* `valohai-deploy-key.pub` – Public key for GitLab
* `valohai-deploy-key` – Private key for Valohai

> :bulb: **Don't commit these keys to Git.** Anyone with the private key can access your repository.

## Step 2: Add Public Key to GitLab

Navigate to your repository's deploy keys settings:

1. Go to your GitLab repository
2. Click **Settings** → **Repository** → **Deploy Keys**

<figure><img src="/files/KL66vXUQ0nmkuIXqN4pU" alt=""><figcaption></figcaption></figure>

> **Can't see Deploy Keys?** You may lack permissions. Contact your GitLab admin.

**Configure the deploy key:**

* **Title:** `Valohai` (or any descriptive name)
* **Key:** Paste the entire contents of the `.pub` file
  * Should start with `ssh-rsa AAAA...`
* **Grant write permissions to this key:** Leave **unchecked** (Valohai only needs read access)
* **(Optional) Set an expiration date** for the deploy key

<figure><img src="/files/DFlbnv9vCWchKDhkVQfR" alt=""><figcaption></figcaption></figure>

Click **Add key** to save.

## Step 3: Add Private Key to Valohai

Now connect the repository in Valohai.

**Get your SSH repository URL from GitLab:**

1. Go to your repository on GitLab
2. Click **Clone** → **Clone with SSH**
3. Copy the URL (format: `git@gitlab.com:username/repository.git`)

**In Valohai:**

1. Go to **Settings** → **Repository**
2. Paste the SSH URL into the **URL** field:

   ```
   git@gitlab.com:username/repository.git
   ```
3. Paste the **entire contents** of the private key file into **SSH private key**:
   * Should start with `-----BEGIN RSA PRIVATE KEY-----`
   * Include all lines, including the header and footer
4. Click **Save**

<figure><img src="/files/EmiPZrbdx3JPQcBU8nsQ" alt=""><figcaption></figcaption></figure>

Valohai will immediately attempt to fetch your repository. If successful, you'll see your commits in the execution dialog.

## Verify Connection

Test that everything works:

1. Go to **Executions** → **Create Execution**
2. The **Commit** dropdown should show your commits
3. If not, click **Fetch Repository** in settings

## Keep Code Updated

After pushing new commits to GitLab, update Valohai:

1. Go to **Settings** → **Repository**
2. Click **Fetch Repository**

**Automate with webhooks:** Set up automatic fetching when you push to GitLab.

## Accessing Without SSH Keys

If creating an SSH key isn't possible, you can use HTTPS with credentials:

**Format:**

```
git+https://USERNAME:ACCESS_TOKEN@gitlab.com/username/repository.git
```

**Example:** If your repository is at `gitlab.com/my-project.git`, your username is `datauser`, and your access token is `glpat-abc123`, use:

```
git+https://datauser:glpat-abc123@gitlab.com/my-project.git
```

### Use a Project Access Token (Recommended)

Even better than a personal access token is a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html):

**Format:**

```
git+https://:<PROJECT_TOKEN>@gitlab.com/username/repository.git
```

You can leave the username part empty when using project tokens.

**Create a project access token:**

1. Go to your GitLab project
2. Click **Settings** → **Access Tokens**
3. Create a new token:
   * **Token name:** `Valohai`
   * **Role:** `Reporter` (read-only)
   * **Scopes:** Check `read_repository`
4. Copy the token (starts with `glpat-`)

Use this token in the HTTPS URL instead of your password.

> :bulb: **SSH is still more secure.** HTTPS with tokens is convenient but exposes credentials in URLs. Use SSH keys for production environments.

## Share Deploy Keys Across Projects

GitLab allows deploy keys to be reused across multiple projects—useful if you're using [Git submodules](/git-integration/advanced-topics/submodules.md).

**Enable a deploy key in another project:**

1. Go to the second project
2. Navigate to **Settings** → **Repository** → **Deploy keys**
3. Open the **Privately accessible deploy keys** tab
4. Click **Enable** next to the key you want to reuse

Now the same SSH key works for both repositories.

<figure><img src="/files/21cJjxHBzneKjc7Xd2Sd" alt=""><figcaption></figcaption></figure>

## Troubleshooting

**"Permission denied (publickey)"**

* The public key wasn't added correctly to GitLab
* Make sure you copied the entire `.pub` file contents
* Verify the deploy key shows in GitLab's settings

**"Repository not found"**

* Check the repository URL format (should be `git@gitlab.com:...`)
* Don't use HTTPS format for private repos with SSH
* Ensure the deploy key is added to the correct repository

**"Invalid private key format"**

* Make sure you pasted the private key, not the public key
* Include the header (`-----BEGIN RSA PRIVATE KEY-----`) and footer
* Don't add extra spaces or line breaks

**"My commits don't appear"**

* Click **Fetch Repository** after pushing new commits
* Check if you're on the correct branch
* Use [Manage Commits](/git-integration/manage-commits.md) to unhide old commits

**"Can't see Deploy Keys menu"**

* You need Maintainer or Owner permissions
* Contact your GitLab admin to add the key for you

## Security Best Practices

**Use project access tokens instead of personal tokens**

* Project tokens are scoped to one repository
* They don't expose your entire account
* They're easier to rotate and revoke

**Prefer deploy keys over HTTPS credentials**

* Deploy keys are more secure
* They provide read-only access
* They don't expose passwords or tokens in URLs

**Rotate keys periodically**

* Generate new keys every 6-12 months
* Delete old deploy keys from GitLab

**Use the Reporter role for tokens**

* Don't grant more permissions than needed
* `read_repository` scope is sufficient

## Next Steps

* [Use .vhignore](/git-integration/use-vhignore.md) to exclude large files
* [Manage Commits](/git-integration/manage-commits.md) to organize visible commits
* [Git Submodules](/git-integration/advanced-topics/submodules.md) for accessing multiple repos


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/git-integration/private-repositories/gitlab.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.