GitLab

Connect a private GitLab repository to Valohai using SSH deploy keys

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:

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

💡 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

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

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: [email protected]:username/repository.git)

In Valohai:

1. Go to Settings → Repository

2. Paste the SSH URL into the URL field:

   [email protected]: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

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:[email protected]/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:[email protected]/my-project.git

Use a Project Access Token (Recommended)

Even better than a personal access token is a project access token:

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.

💡 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.

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.

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 [email protected]:...)

• 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 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 to exclude large files

• Manage Commits to organize visible commits

• Git Submodules for accessing multiple repos