Git Repositories

Git repository access allows agents to clone, read, and work with Git repositories during task execution. Errand uses SSH keys to authenticate with your Git hosting service.

How it works

When you install Errand, it automatically generates a unique SSH key pair for Git operations. You grant access to repositories by adding Errand’s public key to your Git hosting service.

There are two ways to do this, depending on how many repositories you need to give Errand access to:

• Option A: Deploy keys — best when you only need access to one or two specific repositories.
• Option B: User account SSH key — best when you need access to many repositories or an entire organisation.

Copy the SSH public key

Whichever option you choose, you’ll need Errand’s public key first:

1. Open the Errand UI and go to Settings > Security
2. Find the SSH Public Key field
3. Copy the full public key value

Option A: Deploy keys (per-repository)

Deploy keys grant access to a single repository. This is the simplest approach when you only need agents to work with one or two repos.

GitHub

1. Go to your repository on GitHub
2. Navigate to Settings > Deploy keys
3. Click Add deploy key
4. Enter a title (e.g. “Errand”)
5. Paste the SSH public key
6. Optionally check Allow write access if agents need to push changes
7. Click Add key

GitLab

1. Go to your project on GitLab
2. Navigate to Settings > Repository > Deploy keys
3. Enter a title, paste the SSH public key, and optionally grant write permissions
4. Click Add key

Bitbucket

1. Go to your repository on Bitbucket
2. Navigate to Repository settings > Access keys
3. Click Add key
4. Enter a label and paste the SSH public key
5. Click Add key

Note

Deploy keys are per-repository. You’ll need to repeat this for each repository you want agents to access. If you have more than a handful of repositories, consider Option B instead.

Option B: User account SSH key (multi-repository)

If you need Errand to access many repositories — or all repositories in an organisation — you can add the SSH key to a user account instead. Any repository that user has access to will be available to Errand.

Use a dedicated account

Do not add Errand’s SSH key to your own personal account. This would give agents access to all of your private repositories. Instead, create a dedicated machine user account (e.g. “errand-bot”) and add the SSH key to that account. Then grant the machine user access only to the repositories or organisations that Errand needs.

GitHub

1. Create a new GitHub account to act as your machine user (e.g. “errand-bot”)
2. Log in as the machine user
3. Go to Settings > SSH and GPG keys
4. Click New SSH key
5. Enter a title (e.g. “Errand”) and paste the SSH public key
6. Click Add SSH key
7. Back on your main account, invite the machine user as a collaborator on the repositories it needs access to, or add it as a member of your organisation

GitLab

1. Create a new GitLab account for the machine user
2. Go to Preferences > SSH Keys
3. Paste the SSH public key and click Add key
4. Add the machine user to the projects or groups it needs access to

Bitbucket

1. Create a new Bitbucket account for the machine user
2. Go to Personal settings > SSH keys
3. Click Add key and paste the SSH public key
4. Add the machine user to the relevant repositories or workspaces

Write access

If your tasks require agents to push commits, branches, or tags, make sure the key has write access:

• For deploy keys: check the write access option when adding the key
• For user account keys: ensure the machine user has write permissions on the repository (e.g. “Write” or “Maintainer” role)

Without write access, agents can only clone and read from repositories.

SSH hosts

By default, Errand uses SSH for connections to github.com and bitbucket.org. All other hosts use HTTPS.

If you use a different Git hosting service over SSH (e.g. a self-hosted GitLab instance), you can configure additional SSH hosts via the git_ssh_hosts setting.

What agents can do with Git

During task execution, agents can:

• Clone repositories to a local working directory
• Read files and browse the repository structure
• Make changes to files in the working copy
• Commit and push changes back to the remote (if write access is enabled)

Troubleshooting

Issue	Solution
”Permission denied (publickey)” error	Check that the SSH public key from Settings > Security has been added as a deploy key or to the machine user’s account
Host key verification failed	Ensure the Git host is included in the git_ssh_hosts setting, or use HTTPS instead
Can’t push changes	Verify that write access is enabled on the deploy key, or that the machine user has write permissions
No access to a repository	For deploy keys, check the key is on the correct repo. For user keys, check the machine user has been granted access