Skip to main content

How to Create Machine Users and Register Unregistered Users on CircleCI

Overview

Machine users are dedicated VCS user accounts created for automation rather than tied to an individual. When these accounts trigger builds on CircleCI without ever signing in, they appear as Unregistered in the Active Users table under Plan Settings > Usage Controls.

To register a machine user, create a VCS account with a dedicated email, sign in to CircleCI with that account, and follow the relevant projects. Once registered, the user is treated as a standard seat.

Prerequisites

  • Admin access to your VCS organization (GitHub, Bitbucket, or GitLab)

  • Admin or owner access to your CircleCI organization

  • A unique, dedicated email address for each machine user (e.g., [email protected], [email protected])

Instructions

GitHub OAuth

  1. Create a GitHub account for the machine user.

    • Go to github.com/signup.

    • Use a dedicated email address. Each machine user requires its own unique email.

    • Pick a descriptive username (e.g., yourorg-ci-bot).

  2. Invite the machine user to your GitHub organization.

    • In GitHub, go to your organization's People page and invite the new account.

    • Assign the minimum permissions needed for the repos this user will interact with.

  3. Sign in to CircleCI as the machine user.

    • Open an incognito/private browser window to avoid session conflicts.

    • Go to https://circleci.com/vcs-authorize and click Login with GitHub with the recently created machine user's GitHub credentials.

    • When GitHub prompts, select Authorize application.

    • The machine user is now a registered CircleCI user linked to your organization.

  4. Follow the relevant projects.

    • Navigate to the Projects page in the CircleCI web app.

    • Click Follow next to each project the machine user needs access to.

  5. Verify registration.

    • Go to Plan Settings > Usage Controls (/settings/plan/github/<orgName>/usage-controls).

    • In the Active Users table, confirm the machine user no longer shows the Unregistered badge.

Bitbucket Organizations

  1. Create a Bitbucket account for the machine user at bitbucket.org using a dedicated email.

  2. Add the machine user to your Bitbucket workspace with appropriate permissions.

  3. Sign in to CircleCI

    • In an incognito window using the machine user's Bitbucket credentials.

    • Go to https://circleci.com/vcs-authorize and click Login with Bitbucket Cloud with the recently created machine user's credentials.

  4. Follow the relevant projects from the CircleCI Projects page by clicking Follow next to each project.

  5. Verify registration in the Active Users table under Plan Settings > Usage Controls (/settings/plan/bitbucket/<orgName>/usage-controls)..

GitHub App integration Organizations

  1. Create a CircleCI account for the machine user at circleci.com using email + password signup with a dedicated email.

  2. Invite the machine user to your CircleCI organization.

    • Go to Organization Settings > People (/settings/organization/circleci/<org-uuid>/people).

    • Click Invite.

    • In the modal, enter the machine user's email address and select a role from the Select a role dropdown.

    • Click Send Invite(s).

  3. Accept the invite by signing in as the machine user and following the invitation link.

  4. Link with GitHub Go to user settings page https://app.circleci.com/settings/user and when you scroll down you should see "to authorize a GitHub Auth app?" in the bottom of the page and click it and follow and when GitHub prompts, select Authorize application to link it.

  5. Follow the relevant projects from the Projects page.

  6. Verify registration in the Active Users table under Plan Settings > Usage Controls.

GitLab Organizations

CircleCI's GitLab integration uses circleci type organizations, so the machine user flow follows the same pattern as GitHub App organizations.

  1. Create a GitLab account for the machine user at gitlab.com (or your self-managed instance) using a dedicated email.

  2. Add the machine user to your GitLab group or project with appropriate permissions.

  3. Create a CircleCI account for the machine user at circleci.com using email + password signup with the machine user's dedicated email.

  4. Invite the machine user to your CircleCI organization.

    • Go to Organization Settings > People (/settings/organization/circleci/<org-uuid>/people).

    • Click Invite.

    • Enter the machine user's email address, select a role, and click Send Invite(s).

  5. Accept the invite by signing in as the machine user and following the invitation link.

  6. Connect to GitLab.

    • For GitLab.com (SaaS): GitLab SaaS installation is set up when creating a new project (Projects > Create project) or a new pipeline (Project Settings > Pipelines). Select Connect to GitLab Cloud and authorize with the machine user's GitLab account. No personal access token is required — the OAuth authorization handles authentication. See the CircleCI GitLab integration docs for details.

    • For GitLab Self-Managed: Go to Organization Settings > VCS Connections and select Set Up Integration next to GitLab Self-Managed. Enter your instance URL, generate a GitLab personal access token for the machine user with the api scope, and enter the known_hosts value (retrieve by running ssh-keyscan your-instance-url.com). This token is also required when setting up pipeline triggers. See the Manage organization integrations section for details.

  7. Follow the relevant projects from the Projects page.

  8. Verify registration in the Active Users table under Plan Settings > Usage Controls.

Using the Prevent Unregistered User Spend Toggle

If you want to block all unregistered users from consuming credits while you register machine users:

  1. Go to Plan Settings > Usage Controls (/settings/plan/<vcsType>/<orgName>/usage-controls).

  2. Enable the Prevent unregistered user spend toggle.

    • When enabled, unregistered users will not be able to perform actions that use credits.

  3. Identify which machine users are now blocked by reviewing failed pipeline triggers.

  4. Register each needed machine user using the steps above, then verify they no longer appear as Unregistered in the Active Users table.

About Bots (Dependabot, Renovate)

Bots like Dependabot, Renovate, and github-merge-queue[bot] are not standard GitHub user accounts. They cannot sign in to CircleCI directly, so they will always appear as Unregistered Users.

Currently, the only way to prevent these bots from being blocked by the Prevent unregistered user spend toggle is to leave the toggle disabled.

CircleCI's product team is actively working on a bot allowlist feature that would let you specify which bots can trigger builds without being blocked. You can track and vote for it here: Allow users to add bots to an allowlist to avoid being blocked as an unregistered user.

Additional Resources

Related Articles
How to push a commit back to the same repository as part of the CircleCI job
VCS Default Branch Isn't Reflected on CircleCI
How to Register an Unregistered User
How to Register a Bot with Your CircleCI Organization to Trigger Builds
How to Manage Your VCS Connections with CircleCI and delete your user identity
Did this answer your question?