# 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="/files/vj0SSU0RVg1krocfrsCh" 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="/files/VUm35qNji8XwUNoDQ0O9" 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="/files/qPLO1bx2tFFdSVNPuW10" 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](/automation-overview/triggers/webhooks/examples/github-integration.md)

## 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](/git-integration/manage-commits.md) 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](/git-integration/use-vhignore.md) to exclude large files
* [Manage Commits](/git-integration/manage-commits.md) to organize visible commits
* [Automate with GitHub Webhooks](/automation-overview/triggers/webhooks/examples/github-integration.md)


---

# 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/github.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.