GitHub - Key is already in use

When connecting a GitHub repository that uses submodules, you may encounter errors if the SSH keys are configured on a GitHub user account rather than as deploy keys on individual repositories. This guide explains how to use GitHub machine users with DeployHQ to resolve these issues.

The problem

GitHub restricts deploy keys to a single repository. When you connect a repository to DeployHQ using the GitHub OAuth integration, DeployHQ automatically attempts to add the project's public key as a deploy key directly to the repository.

This creates a conflict when:

• Your repository contains submodules (each submodule is a separate repository that needs access)
• You have multiple DeployHQ projects that need access to the same repository
• Your organisation requires SSH keys to be managed at the user level rather than per-repository

You may see errors such as:

Key is already in use

Or experience connection failures when DeployHQ tries to access submodule repositories.

What is a machine user?

A machine user is a dedicated GitHub account created specifically for automation and CI/CD purposes, rather than for a human developer. Think of it as a "bot" account that acts on behalf of your organisation's automated systems.

Key characteristics of machine users

• Dedicated purpose: The account exists solely for automated tasks like deployments, not for human use
• Shared access: Unlike deploy keys (which are locked to one repository), SSH keys added to a machine user can authenticate across all repositories that user can access
• Organisation membership: The machine user is added as a member of your GitHub organisation with appropriate permissions
• Auditable: All actions performed by the machine user are logged under its account, making it easy to track automated activity separately from human developers

Why use a machine user instead of deploy keys?

Common use cases

• Repositories with submodules: One SSH key authenticates access to the main repository and all submodule repositories
• Monorepo setups: Multiple DeployHQ projects can deploy from the same repository
• Shared libraries: When multiple projects depend on private packages hosted in separate repositories
• Organisation policies: When your security team requires centralised key management at the user level

Step-by-step setup

1. Create a machine user account

Create a new GitHub account specifically for deployment purposes:

1. Sign out of GitHub (or use an incognito window)
2. Create a new account with a dedicated email address
3. Use a name that clearly indicates its purpose, such as yourcompany-deploy, deploy-bot, or ci-deployhq

Important considerations:

• Use a shared or team-managed email address so the account isn't tied to an individual employee
• Enable two-factor authentication for security
• Document the account credentials securely in your organisation's password manager
• This account counts towards your GitHub plan's seat allocation on paid organisation plans

2. Grant repository access

Add the machine user to your GitHub organisation and grant appropriate access:

1. Go to your GitHub organisation's People settings
2. Click Invite member and invite your machine user account
3. Accept the invitation while logged in as the machine user
4. Grant the machine user read access to:
   • The main repository you want to deploy
   • All submodule repositories referenced in your project

Tip: Consider creating a GitHub Team (e.g., "Deploy Bots") for easier permission management. Add all repositories the machine user needs to access to this team.

3. Connect to DeployHQ using manual configuration

Instead of using the Connect to GitHub button (which uses OAuth and automatically adds deploy keys), configure your repository manually:

1. Go to your DeployHQ project settings
2. Under Repository, select Enter repository URL manually
3. Enter your repository URL in SSH format: git@github.com:your-org/your-repo.git
4. Copy the project's public key shown in DeployHQ

4. Add the public key to your machine user

1. Log in to GitHub as your machine user
2. Go to Settings > SSH and GPG keys
3. Click New SSH key
4. Paste the DeployHQ project's public key
5. Give it a descriptive title (e.g., "DeployHQ - Project Name")
6. Click Add SSH key

Because this key is attached to the machine user (not a specific repository), it will authenticate access to any repository the machine user can access.

5. Configure submodules

Ensure your .gitmodules file uses SSH URLs rather than HTTPS URLs:

[submodule "lib/external"]
  path = lib/external
  url = git@github.com:your-org/external-lib.git

If your submodules use HTTPS URLs, update them and run:

git submodule sync

Then commit and push the changes.

Troubleshooting

Connection still fails

Verify that:

• The machine user has been added to your organisation and accepted the invitation
• The machine user has read access to all repositories (main and submodules)
• The SSH key is added to the machine user's SSH keys (not as a deploy key on a repository)
• Your .gitmodules file uses SSH URLs, not HTTPS

Submodule errors during deployment

If you see errors like Could not read from remote repository for submodules, check that the machine user has access to each submodule repository listed in your .gitmodules file.

"Key is already in use" error

This error means the same SSH key has already been added elsewhere on GitHub. Each SSH key can only be used once across all of GitHub. Generate a new key pair in DeployHQ by resetting the project's SSH key, then add the new public key to your machine user.

Security best practices

• Minimal permissions: Grant the machine user only the access it needs (typically read-only)
• Regular audits: Periodically review which repositories the machine user can access
• Secure credentials: Store the machine user's login credentials in your organisation's password manager
• Enable 2FA: Protect the machine user account with two-factor authentication
• Monitor activity: Review the machine user's activity in GitHub's audit log

Further reading

• GitHub documentation on machine users
• Using submodules in DeployHQ
• Submodule authentication errors
• GitHub - Key is already in use