Register Users

CircleCI runs pipelines whenever code is pushed to connected repositories, even if the person doesn't have a CircleCI account. Register users to provide important benefits for your team and organization.

Benefits of Registering Users

For Your Team

• Access the CircleCI web app to view and troubleshoot builds
• Rerun failed pipelines
• See activity linked to their VCS identity and CircleCI account
• Manage personal permissions and settings

For Your Organization

• Avoid duplicate user seats: Unlinked VCS accounts can create extra, unnecessary seats
• Prevent unregistered user spend: Users without accounts still consume plan seats
• Gain better visibility and control over resource usage

Register Unregistered Users

Free and Performance plans have 5 free active users included. You're only charged for active users beyond this allowance who trigger builds each month.

The flow for registering users depends on how your organization is connected to CircleCI.

1. OAuth (GitHub or Bitbucket) Organizations

If your organization uses OAuth and the user already has access in the VCS (GitHub/Bitbucket):

• The user does not need an explicit invitation.
• They can join the CircleCI organization automatically by either:
  1. Logging in via their VCS account (GitHub/Bitbucket)
  2. Logging in with email/password and linking their VCS account

Once they log in and authorize CircleCI, they are automatically placed in the OAuth organization.

2. Standalone / GitHub App / GitLab Organizations

For these organization types, users must be invited. Follow the steps in our documentation to invite users to your organization:

1. In the CircleCI web app, go to Organization Settings > People.
2. Select Invite.
3. Enter the user's email address. Multiple emails can be separated by a space.
4. Select a role from the dropdown menu.
5. Select Send Invite(s).

The invited user will receive an email notification from noreply@circleci.com containing a link to accept the invite. If they do not have a CircleCI account, they will need to sign up.

 Note for GitLab users: After accepting the invite, users must also authorize their GitLab connection to be considered fully registered. To do this:

1. Log in to CircleCI with email and password.
2. Navigate to Project Settings > Pipelines > Add Pipeline > GitLab.
3. Click "Authorize".

Without this step, the user will not be considered a registered user even if they have a CircleCI account. See How to fix the "block-unregistered-user" error for GitLab projects for details.

⚠️ Existing [UNREGISTERED] usage in the current billing cycle cannot be removed retroactively. If a duplicate active CircleCI user appears in Plan > Usage > Users, have them authorize their VCS connection.

Bots and Automation/Machine User Accounts

Machine users are dedicated, non-human VCS accounts created for automation. You can register them by creating a CircleCI account and inviting them to your organization, just like a regular user.

For step-by-step instructions for each VCS type (GitHub OAuth, GitHub App, Bitbucket, and GitLab), see How to Create Machine Users and Register Unregistered Users on CircleCI.

Bots (e.g., github-merge-queue[bot], Dependabot, Renovate) are not standard VCS user accounts and cannot be registered on CircleCI. They may appear as [UNREGISTERED] and could be blocked or counted against your plan.

There is an open feature request to allow organizations to add bots to an allowlist. You can vote for it and track progress here: Allow users to add bots to an allowlist to avoid being blocked as an unregistered user.

Understanding Unregistered Users and Duplicate Seats

Unregistered users are VCS identities that trigger builds without a linked CircleCI account. They appear as [UNREGISTERED] on Plan > Usage > Users.

Unregistered users are those who:

• Push code or open a pull request
• Have not logged into CircleCI or authorized their VCS connection

Important: Even unregistered users consume seats on your plan. Each unique active unregistered user counts toward your monthly active user total.

Duplicate Seat Edge Case

If a user:

1. Pushes changes to a connected repository and
2. Signs up for the CircleCI web app without connecting their VCS identity

…then actions triggered from the CircleCI web app may create a duplicate user record, consuming extra plan seats.

Resolution:

• The user should log in to the CircleCI web app
• Complete the connection to their VCS identity
  • This links their web app account to the VCS identity and prevents duplicate charges

Troubleshooting

User Being Double-Counted / Duplicate Seats

• User signed up without linking their VCS identity → Log in via CircleCI web app and complete VCS connection
• Forgot to click Authorize during OAuth login → Log back in and authorize
• Invitation not accepted → Resend the invite
• GitLab user accepted invite but didn't authorize GitLab connection → Navigate to Project Settings > Pipelines > Add Pipeline > GitLab > Authorize

If issues persist, contact CircleCI Support.

Additional Resources

• How to Create Machine Users and Register Unregistered Users on CircleCI
• What is an Unregistered User?
• What is an Active User?
• Manage Roles and Permissions
• How to set up the "Prevent unregistered user spend" feature
• How to fix the "block-unregistered-user" error for GitLab projects
• Why do I see a "block-unregistered-user" error in my build?
• Feature Request: Bot Allowlist