Robot Accounts & CI/CD Access
Relevant source files
The following files were used as context for generating this wiki page:
Robot accounts in Harbor Next are specialized identities designed to facilitate automated interactions with the registry, primarily for CI/CD pipelines. Unlike standard user accounts, robot accounts are not associated with external identity providers (like LDAP or OIDC) and use secrets (tokens) rather than passwords for authentication. They allow systems to perform actions such as pulling and pushing images, scanning artifacts, and managing metadata without compromising personal user credentials.
These accounts operate within a Role-Based Access Control (RBAC) framework, ensuring that automation scripts only possess the minimum necessary permissions required for their specific tasks. Robot accounts can be scoped to the entire system or restricted to specific projects, providing granular control over resource access.
Sources: api/v2.0/swagger.yaml, README.md, src/portal/src/i18n/lang/en-us-lang.json
Robot Account Architecture
Harbor distinguishes between two primary levels of robot accounts: System-level and Project-level.
System-Level Robot Accounts
System-level robots are created by system administrators and can be granted permissions across multiple projects or system-wide resources. They are capable of "covering all projects," which applies their permissions to all existing and future projects automatically.
Sources: api/v2.0/swagger.yaml:4570-4595, tests/apitests/python/test_robot_account.py:168-180, src/portal/src/i18n/lang/en-us-lang.json
Project-Level Robot Accounts
Project-level robots are restricted to a single namespace. They are typically used for project-specific automation, such as a CI pipeline for a specific application repository. Their names are often prefixed with the project name to prevent collisions.
Sources: api/v2.0/swagger.yaml:4570-4580, tests/apitests/python/test_robot_account.py:53-70, src/portal/src/app/base/project/robot-account/add-robot/add-robot.component.html
Lifecycle and State
The following diagram illustrates the typical lifecycle of a robot account, including creation, credential management, and revocation.
The lifecycle involves defining the scope, assigning specific access rights (resource/action pairs), and managing the secret which is only shown once during creation.
Sources: api/v2.0/swagger.yaml:4600-4630, tests/apitests/python/test_robot_account.py:228-245, src/portal/src/i18n/lang/en-us-lang.json
Permissions and Access Control
Permissions for robot accounts are structured as an array of RobotPermission objects. Each permission defines a kind (e.g., "project"), a namespace (the specific project name or "*" for all), and an access list.
Access Model
The access model consists of three key components:
- Resource: The target entity (e.g.,
repository,artifact,scan,tag). - Action: The operation allowed (e.g.,
push,pull,create,delete,read,list). - Effect: Whether the action is permitted (typically "allow").
| Component | Description | Example Values |
|---|---|---|
| Resource | The system or project asset being accessed. | repository, artifact, helm-chart, scan, tag |
| Action | The specific operation the robot is authorized for. | push, pull, create, read, delete, operate |
| Level | The scope of the account. | system, project |
Sources: api/v2.0/swagger.yaml:4645-4670, tests/apitests/python/test_robot_account.py:185-200
Permission Mapping
The relationship between a Robot Account and its permissions is shown below:
Sources: api/v2.0/swagger.yaml:4570-4670
Management and Security
Secret Management
Secrets are generated by the system but can also be manually specified during creation or updates. Harbor provides an endpoint to refresh the robot secret, which invalidates the previous token immediately.
Sources: api/v2.0/swagger.yaml:2630-2650, tests/apitests/python/test_robot_account.py:238-245
Expiration and Prefixes
- Expiration: Robots can be set to "Never Expire" (duration = -1) or assigned a specific duration in days.
- Prefixes: To distinguish robot accounts from regular users, a system-wide prefix is used (default is
robot$). For project robots, the project name is usually appended to the prefix (e.g.,robot$myproject+botname).
Sources: api/v2.0/swagger.yaml:4570-4595, src/portal/src/i18n/lang/en-us-lang.json, src/portal/src/app/base/project/robot-account/add-robot/add-robot.component.html:125-140
CI/CD Integration Flow
When a CI/CD system (e.g., GitHub Actions, Jenkins) interacts with Harbor, it follows a standard authentication sequence using the robot account credentials.
API Reference for Robot Accounts
Management of robot accounts is handled through the /robots resource.
Management Endpoints
| Method | Path | Description |
|---|---|---|
GET | /robots | List robot accounts (supports pagination and filtering). |
POST | /robots | Create a new robot account. |
GET | /robots/{robot_id} | Get specific robot account details. |
PUT | /robots/{robot_id} | Update robot details (permissions, description, etc). |
PATCH | /robots/{robot_id} | Refresh/Update the robot secret. |
DELETE | /robots/{robot_id} | Delete a specific robot account. |
Sources: api/v2.0/swagger.yaml:2550-2670
Data Definitions (Summary)
RobotCreate Model
{
"name": "string",
"description": "string",
"secret": "string",
"level": "string",
"disable": false,
"duration": -1,
"permissions": [
{
"kind": "project",
"namespace": "my-project",
"access": [
{"resource": "repository", "action": "push"},
{"resource": "repository", "action": "pull"}
]
}
]
}
Sources: api/v2.0/swagger.yaml:4600-4620
Summary
Robot Accounts serve as the primary mechanism for secure, automated access to Harbor Next resources. By providing a decoupled credential system with fine-grained RBAC and flexible scoping (System vs. Project), they enable robust CI/CD integration while adhering to the principle of least privilege. Key features like secret rotation, configurable expiration, and name-prefixing ensure that these automated identities remain manageable and secure within complex enterprise environments.
Sources: api/v2.0/swagger.yaml, tests/apitests/python/test_robot_account.py, README.md