# GitHub

Connect your private GitHub repository to Valohai using SSH authentication. GitHub deploy keys provide secure, read-only access without exposing your account credentials.

## Requirements

* A private GitHub repository
* A Valohai project
* Admin access to the repository (to add deploy keys)

## Overview

You'll complete three steps:

1. Generate an SSH key pair (in Valohai or on your local machine)
2. Add the public key to GitHub 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 GitHub
* `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 GitHub

Navigate to your repository's deploy keys settings:

1. Go to your GitHub repository
2. Click **Settings** → **Deploy keys** → **Add deploy key**

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-8ed0358e1650e1ca34c58b3f8a106ed3c56d11ce%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**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...`
* **Allow write access:** Leave **unchecked** (Valohai only needs read access)

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2Fgit-blob-2b29de8fceef08b849dfbba76ef41b12f8ac9006%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 GitHub:**

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

**In Valohai:**

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

   ```
   git@github.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-caefdb3612de7e38c3986329c768cbd4d63ec21c%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 GitHub, update Valohai:

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

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

* [GitHub Webhook Integration](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/github-integration)

## Troubleshooting

**"Permission denied (publickey)"**

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

**"Repository not found"**

* Check the repository URL format (should be `git@github.com:...`)
* Don't use HTTPS format for private repos
* 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

## Security Best Practices

**Use deploy keys, not personal access tokens**

* Deploy keys are repository-specific
* They provide read-only access
* They don't expose your entire account

**Rotate keys periodically**

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

**Don't share private keys**

* Each environment should have its own key pair
* Never commit keys to your repository
* Store keys securely (password manager, secrets vault)

## 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
* [Automate with GitHub Webhooks](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/github-integration)