Buildkite Integration

Scimify enables full user and group SCIM provisioning for Buildkite organizations, allowing you to invite members, manage organization roles, sync IdP groups to Buildkite teams, and deprovision access through your identity provider.

Overview

This integration (de)provisions users and teams in your Buildkite organization. Scimify accepts standard SCIM requests from your IdP and translates them into Buildkite API calls.

Key behaviors:

User and team provisioning — sync IdP users and groups to your Buildkite organization
Invite-based user create — new users receive an organization invitation email (they are not active members until they accept)
Team mapping — IdP groups map to Buildkite teams; team membership follows IdP group assignments
Team visibility — integration-level default for new team privacy (visible or secret)
Role management — optional SCIM attributes for organization role and team member role
Deprovisioning — removing access deletes the organization member or revokes a pending invitation

Buildkite native SCIM vs Scimify

Buildkite offers basic SCIM user provisioning on Enterprise plans only. That native integration does not support team/group push.

Scimify enables full user and group SCIM on Buildkite Personal, Pro, and Enterprise plans, including team create, rename, membership sync, and deprovisioning.

Prerequisites

A Buildkite organization where you can manage members and teams
A Buildkite API access token issued for a user with permission to manage organization members and teams
The token must have GraphQL API access enabled (required for user invitations)
Your IdP configured for SCIM provisioning (see Okta SCIM Configuration)

Configuration Steps

1. Create a Buildkite API Access Token

Sign in to Buildkite
Open Personal Settings → API Access Tokens
Create a new token for the target organization
Enable these REST scopes:
- Organizations — read and write (read_organizations, write_organizations)
- Teams — read and write (read_teams, write_teams)
Enable GraphQL API Access on the token (required for inviting users)
Copy the token and store it securely

See Managing API access tokens for details.

2. Configure the Integration in Scimify

Navigate to the Integrations page in your Scimify admin console
Create a new Buildkite integration instance
Set an instance display name (for example, Production Buildkite) to distinguish multiple connections
Enter your API Key (the Buildkite API access token)
Enter your Organization Slug — the URL segment for your org (for example, acme-corp from https://buildkite.com/acme-corp)
Optionally set a Group Description — applied to Buildkite teams created through SCIM group provisioning. Default: Created via Scimify for tenant {tenant_id}
Set Default Team Visibility — controls the Buildkite team privacy value for SCIM-provisioned teams:
- Visible (default) — team is visible to all organization members
- Secret — team is private; only members can see it
Save the configuration and use Test connection to verify API access
Use Refresh users and Refresh groups to confirm the token can list organization members and teams
Enable the integration to generate a SCIM API key for your IdP
Copy the Scimify SCIM endpoint for your IdP

3. Configure Custom SCIM Attributes (Optional)

To manage Buildkite organization roles or team member roles from your IdP, add the custom attributes described in Custom SCIM Attribute Configuration below.

4. Configure IdP SCIM

Follow the Okta SCIM Configuration guide to connect Okta to your Scimify Buildkite instance, then assign users and groups to the SCIM app.

If you use group push, refresh and import teams from Buildkite in your IdP before pushing so Scimify and your IdP have accurate team IDs.

How It Works

User Provisioning

When a user is assigned in your IdP:

Scimify checks whether the email already exists as an organization member
If not, Scimify checks for an existing pending invitation
If neither exists, Scimify sends a new organization invitation with the requested organization role

The invited user must accept the invitation before they appear as an active organization member in Buildkite.

User Updates

Active members — organization role changes (buildkite_org_role) are applied via the Buildkite GraphQL API
Pending invitations — Buildkite does not support updating an invitation in place; Scimify revokes the pending invitation and creates a new one when buildkite_org_role changes
Profile fields — name and email are not updated through this integration; organization role is the primary supported user update

User Deprovisioning

When a user is unassigned or deactivated in your IdP:

Active members are removed from the organization
Pending invitations are revoked

This is a hard remove from the organization (not a soft disable).

Team Provisioning

When groups are pushed from your IdP:

Scimify creates, renames, and deletes Buildkite teams to match IdP group lifecycle events
New teams use the Default Team Visibility from your integration config (visible by default, or secret if you change it)
Team membership is synced to match IdP group assignments
Only accepted organization members can be added to teams — pending invitations are skipped until the user accepts

Team names in Buildkite match the IdP group display name.

See Buildkite Teams for how secret and visible behave in Buildkite.

Custom SCIM Attribute Configuration

Attribute: buildkite_org_role

Setting	Value
Type	String
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`buildkite_org_role`
Description	Buildkite organization role for the invited or provisioned user
Default	`member` (if not sent in SCIM)

Valid values:

Value	Description
`member`	Standard organization member (default)
`admin`	Organization administrator

Scimify accepts buildkite_org_role in any of these common SCIM shapes:

Top-level field: buildkite_org_role
Extension key: urn:ietf:params:scim:schemas:extension:custom:2.0:User:buildkite_org_role
Nested extension object: urn:ietf:params:scim:schemas:extension:custom:2.0:User → { "buildkite_org_role": "admin" }

Attribute: buildkite_team_role

Setting	Value
Type	String
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`buildkite_team_role`
Description	Role assigned when the user is added to a Buildkite team via group membership sync
Default	`member` (if not sent in SCIM)

Valid values:

Value	Description
`member`	Standard team member (default)
`maintainer`	Team maintainer

Suggested Okta profile attributes

In Okta, add user profile attributes for your Buildkite SCIM app:
- Organization role — external name buildkite_org_role, type string, values member or admin
- Team role (optional) — external name buildkite_team_role, type string, values member or maintainer
Map the attributes in the Okta → Scimify provisioning profile so they are included on create and update
Use group rules or entitlements to assign admin or maintainer only where appropriate

Known Limitations and Behavior Notes

Invite-only create — SCIM “create user” sends an organization invitation; users are not fully active until they accept
Team membership requires accepted members — pending invitees cannot be added to teams; retry group push after the user accepts
Pending invitation limit — Buildkite organizations have a limit on pending invitations (default 20 per organization)
Role-only user updates — only buildkite_org_role is synchronized on update; other profile attributes are ignored
New teams use secure defaults — teams created via SCIM default to visible visibility unless you set Default Team Visibility to secret in the integration config; pipeline and registry creation permissions remain restricted unless changed manually in Buildkite
Name/email not updated post-acceptance — Buildkite user accounts are personal accounts tied to the invite email

Troubleshooting

Authentication failed (401)
- Confirm the API token is valid and has access to the configured organization
- Regenerate the token in Buildkite and update the Scimify integration config
User invite fails
- Ensure GraphQL API Access is enabled on the token
- Confirm the token has organization write scopes
User created but not in teams
- The user may still have a pending invitation — team membership requires an accepted organization member
Invalid buildkite_org_role or buildkite_team_role
- Organization role must be member or admin
- Team role must be member or maintainer

Additional Resources

Need Help?

If you encounter issues configuring Buildkite API tokens, SCIM attribute mappings, or team push, contact support@veraproof.io for assistance.