Project GitHub Repository Binding

Each Helm project can be bound to exactly one GitHub repository. This binding enables code cloning, branch management, and sync features within agent sessions. This article covers how to set up and manage project-to-repo bindings.

Overview

Project-repo binding connects your Helm project to a GitHub repository:

• One-to-one relationship: Each project binds to exactly one repo
• Org-level access: Repos must be authorized via your org's GitHub App
• Session cloning: Agent sessions can clone the bound repo
• Branch management: Sessions create branches for isolated work

Prerequisites

Before binding a project to a repo:

Your organization must have GitHub connected

The target repository must be accessible via the GitHub App

You must have Owner or Admin role in the Helm organization

Binding a Repo During Project Creation

Step 1: Start Creating a Project

Open the Project Selector in the header

Click + New Project

Enter a project name

Step 2: Select a Repository

You have two options:

Option A: Select an Existing Repo

Browse the list of available repositories

Use the search box to filter by name

Click a repository to select it

Option B: Create a New Repo

Click Create new repository

Enter a repository name

Choose visibility (public or private)

Click Create to create the repo in your GitHub org

Step 3: Complete Project Creation

Review your selections

Click Create Project

The project is created with the repo binding in place

Viewing the Current Repo Binding

To see which repo is bound to a project:

Open the project in Helm

Navigate to Project Settings

Select the GitHub tab

View the currently linked repository details:

- Repository name - Owner (organization) - Visibility (public/private) - Binding date

Changing the Repo Binding

Org Owners and Admins can change a project's repo binding:

Step 1: Access Project Settings

Open the project

Click Project Settings (gear icon)

Select the GitHub tab

Step 2: Select a New Repository

Click Change Repository

Browse or search available repositories

Select the new repository

Step 3: Confirm the Change

Review the change summary

Click Confirm to apply the new binding

What Happens When You Change Bindings

• Future sessions clone from the new repository
• Existing sessions continue using their cloned code
• Branch references update to the new repo
• Historical session data retains the original repo reference

Repository Visibility in Helm

The repo selector only shows repositories that:

Are accessible via your org's GitHub App installation

Match the App's configured repository access (all or selected)

If a repository doesn't appear:

Check your org's GitHub App settings

Ensure the repo is included in the App's repository access

Permissions

Role	Can View Binding	Can Change Binding
Owner	✓	✓
Admin	✓	✓
Member	✓	✗
Viewer	✓	✗

Members and Viewers see the repo binding but cannot modify it.

Creating New Repositories

When creating a new repo during project creation:

• The repo is created in your connected GitHub organization
• You specify the repo name and visibility
• The repo starts empty (no initial commit)
• Helm immediately binds the project to the new repo

Repository Naming

Repository names must:

• Be unique within your GitHub organization
• Contain only letters, numbers, hyphens, and underscores
• Not start with a hyphen or underscore

Unbinding a Repository

Currently, projects must always be bound to a repository. To effectively "unbind":

Create a placeholder repository

Bind the project to the placeholder

Delete the original repo from GitHub (if appropriate)

Future versions may support unbound projects.

Troubleshooting

"No repositories available"

• Verify your org has GitHub connected
• Check that the GitHub App has access to at least one repository
• Ensure you're in the correct Helm organization

Repository doesn't appear in the list

• The repo may not be included in your GitHub App's repository access
• Configure the App in GitHub to add the repository

"Unauthorized" error (403) when changing binding

• Only Owners and Admins can change repo bindings
• Contact your org admin for elevated permissions

Project shows "Repository unavailable"

The bound repository may have been:

• Removed from the GitHub App's access
• Deleted from GitHub
• Made private when the App only has public access

Rebind to an available repository to restore functionality.

Best Practices

Name alignment: Consider matching project and repo names for clarity

Private by default: Use private repos for proprietary code

Archive don't delete: Archive old repos rather than deleting to preserve history

Document bindings: Keep a record of which projects map to which repos

Related Topics

• Connecting GitHub to Your Organization - Set up the GitHub connection
• Managing Project Components - Configure your project