# 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="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-e3698d1306c3500c7d884331ff0a5df77f681fc9%2Fimage.png?alt=media" 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="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-49c7c19f7f64c3181bf5ed081996d88111eab15d%2Fimage.png?alt=media" 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="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-fad83341b75bc821a7a5ca3ebd5b4d495ec89113%2Fimage.png?alt=media" 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](https://docs.valohai.com/git-integration/advanced-topics/submodules).

**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="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-22710eebad72bae19b8981d0bd87376173ad4686%2Fimage.png?alt=media" 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](https://docs.valohai.com/git-integration/manage-commits) 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](https://docs.valohai.com/git-integration/use-vhignore) to exclude large files
* [Manage Commits](https://docs.valohai.com/git-integration/manage-commits) to organize visible commits
* [Git Submodules](https://docs.valohai.com/git-integration/advanced-topics/submodules) for accessing multiple repos