Bots and programmatic repository access

Bots enable access to projects without using user credentials. Helix TeamHub can securely grant program access to projects using either a bot's credentials, SSH keys, or API keys.

TeamHub supports the following types of bots:

• Normal bots can be assigned to projects and repositories with guest, developer, or master role.
• Company admin bots have access to all projects and repositories by default, see note below. Company admin bots can also manage users, collaborators, and groups at the company level.
Note
• Bots have read/write access to repository commits but bots have no access to the repository listing or the repository itself.
• Bots can merge Code Reviews and Multi-repo Code Reviews but bots cannot list or access them.

Privilege	Guest	Developer	Master	Company admin
Create and update build events	✓	✓	✓	✓
Read repositories	✓	✓	✓	✓
Write to repositories1 Master or admin role is required for writing to a protected branch.		✓	✓	✓
Merge code reviews2 Master or admin role is required for merging a code review where the destination branch is protected.		✓	✓	✓
Write to protected branches			✓	✓
Merge multi-repo code reviews			✓	✓
Manage users and collaborators3 At the company level only.				✓
Manage groups and members4 At the company level only.				✓

Managing bots

Normal bots can be created by users, assigned to projects by project admins, and assigned to repositories by repository admins. Owners of the bot can manage the bot and its credentials, while members can only access them.

Public bots are visible to everyone. Private bots are only visible to owners and members. Collaborators can only see bots. Company admin bots are only available to company admins.

Creating a new bot

Perform the following steps to create a new bot:

1. To make sure you are at the company scope level, click the company name or logo in the top left corner. Then click Bots.

2. In the Bots view, click the plus icon to the right of the search field to open the Create bot form.

   

3. In the Create bot form, provide the following information:

   • Short name: Username for the bot.
   • Password: Password for the bot. Leaving the field empty will generate a random password. Bot users can view the password in the bot settings form.
   • Company admin bot: Select to create a company admin bot instead of a normal bot. This option is only available for company admins and cannot be changed after creation.
   • Private bot: Select to hide bot from other users.

4. Click Create.

   After creating a bot, you can manage its settings (excluding Company admin bot status) from the bot settings form or the Bot > Users view. To access the settings, click the cogwheel icon next to the bot name in the Bots tab.

   Note

   With Helix authentication, you cannot modify the short name after creating a bot.

   You can also delete the bot using the settings form.

Bot settings

You can manage the username, password, and visibility of the bot (public or private) from the Details section.

Bots can have multiple SSH keys, which you can manage from the SSH Keys section. Helix TeamHub supports ssh-rsa, ssh-ed25519, and ecdsa keys.

The Account Key and Company Key of the bot are located in the API Keys section. These keys are required when you use the bot with integrations and for API access.

Bot users

After creating a bot, you can manage its users from the Bots > Users view. To access this view, click a bot in the Bots tab.

When you add users to bots, they can have one of the following roles:

• Member: Users with this role can always see the bot and its settings (including credentials).
• Owner: Users with this role can also manage the bot's settings and users.