The Drone CI Admin API lets you manage users, teams, and permissions programmatically, but its real power lies in how it lets you decouple user management from Drone’s internal state, allowing for external identity providers and fine-grained access control.
Here’s Drone CI in action, creating a new user and assigning them to a team using the Admin API:
# First, get an admin token. This is usually done via the Drone UI,
# but for scripting, you'd typically have a dedicated service account.
# Let's assume we have a token stored in ADMIN_TOKEN.
# Create a new user
curl -X POST \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"login": "jane.doe",
"email": "jane.doe@example.com",
"active": true
}' \
http://drone.example.com/api/users
# Create a new team
curl -X POST \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "developers"
}' \
http://drone.example.com/api/teams
# Add the user to the team
curl -X POST \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user_id": 123, # The ID of the user created above
"team_id": 456, # The ID of the team created above
"role": "member"
}' \
http://drone.example.com/api/teams/123/members # Note: This endpoint is for user-team membership, not team-user
The core problem Drone CI solves is providing a continuous integration and delivery platform that’s deeply integrated with Git repositories. However, managing users and their access across potentially hundreds or thousands of repositories can become a significant operational burden. The Admin API addresses this by exposing endpoints for creating, updating, deleting, and querying users, teams, and their associations. This allows for automation of user lifecycle management, integration with existing identity providers (like LDAP or Active Directory via an external sync process), and centralized control over who can do what within Drone.
Internally, Drone stores user and team information in its database. When you use the Admin API, you’re essentially performing CRUD operations on these database records. The API abstracts away the direct database interaction, providing a consistent interface. Users have a login, email, and an active status. Teams are named entities. The crucial link is the membership, which associates a user_id with a team_id and assigns a role (e.g., member, owner).
The role field on a team membership is particularly important. While the UI often presents a binary "member" or "owner" distinction for teams, the API allows for more granular control if your underlying identity system supports it. For instance, you might have a mapping where a specific group in your LDAP translates to a "developer" role in Drone, while another group maps to an "auditor" role. This enables a "least privilege" approach where users only get the permissions they absolutely need.
When you create a user via the API, Drone generates an internal ID for that user. This ID is then used in subsequent operations, such as adding them to a team or granting repository access. The active flag is critical for disabling user access without deleting their historical data or configurations. A user marked as active: false will no longer be able to log in or trigger builds, but their past contributions and settings remain.
The POST /api/teams/{team_id}/members endpoint is where you establish the relationship between users and teams. You provide the user_id, team_id, and the desired role. Drone then creates a record in its membership table, linking these entities. This is the mechanism by which team-based permissions are enforced. If a user is a member of the developers team, and that team has been granted access to a specific repository, the user inherits that access.
One of the less obvious benefits of using the Admin API for user management is its ability to manage "ghost" users. If you have a CI system that is configured to trigger builds based on events from external systems (like a webhook from a security scanner), you might not want a full interactive user account for that event source. The Admin API allows you to create users with only the necessary permissions for these automated tasks, without needing to provision them with login credentials or an email address. These users are effectively service accounts within Drone, and their active status can be managed just like any other user.
The next step after managing users and teams is often automating repository permissions, which involves using the POST /api/repos/{owner}/{name}/permissions endpoint to grant access to specific repositories based on team membership.