How to Register a Bot with Your CircleCI Organization to Trigger Builds

Overview

When a bot or automation tool triggers a build on CircleCI without having a corresponding CircleCI account, it appears as an Unregistered User. These are typically automated systems like CI bots, scripts, or dependency update tools (e.g., Renovate or Dependabot) that commit or trigger pipelines but aren’t recognized as registered users in CircleCI.

What is an Unregistered User?

An Unregistered User is any entity that triggers a CircleCI build but hasn’t signed up for CircleCI. These users still count as Active Users, even though they don’t have a CircleCI profile.
You can identify unregistered users in your jobs list by:

• Looking for jobs with a blank profile image.

• Checking the committer’s name and truncated commit hash in the job details (top right corner).

• Clicking the commit hash to open the commit in your VCS (GitHub or Bitbucket) and see the actual author.

Why You Need to Register Bots

By default, CircleCI allows unregistered users to trigger builds. However, if your organization enables the Prevent unregistered user spend feature, any bot or service without a registered CircleCI identity will be blocked from triggering pipelines.
This includes:

• Automation tools and CI/CD bots

• Dependency management bots (e.g., Renovate, Dependabot)

• Custom scripts or service accounts that trigger workflows

While this setting is primarily a security measure ensuring only trusted, authenticated systems run pipelines, it can interrupt automated workflows if your bots aren’t properly registered.

How to Register a Bot

Currently, CircleCI does not support native bot registration. To “register” a bot in a way CircleCI recognizes, it must:

1. Have a valid identity — an email address or account that can be linked to your VCS (GitHub or Bitbucket).

2. Sign up for CircleCI using that account.

3. Join your organization so it becomes a registered member.

4. (Optional) Follow the relevant projects to view build history and access pipeline data.

As an Org Admin, you can invite this bot account to your organization directly through CircleCI. Once it’s a member, builds triggered by it will no longer appear as unregistered.

Current Limitations and Feature Request

At this time, CircleCI does not offer an official way to register or whitelist bot accounts automatically. This means any automation tool that isn’t backed by a registered VCS identity may still be blocked by the “Prevent unregistered user spend” setting.

CircleCI is aware of this limitation. A feature request has been submitted to allow organizations to add bots to an allowlist, preventing them from being blocked while maintaining security controls.

You can support this request by voting on the Canny board:
Allow users to add bots to an allowlist to avoid being blocked as unregistered users