manage-roles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage Roles Skill

Manage Roles 技能

Manage Harness RBAC (Role-Based Access Control) via MCP v2 tools.

通过MCP v2工具管理Harness RBAC（基于角色的访问控制）。

MCP v2 Tools Used

使用的MCP v2工具

Tool	Resource Type	Operations
`harness_list`	`role`	List all roles
`harness_get`	`role`	Get role details
`harness_create`	`role`	Create custom role
`harness_update`	`role`	Update custom role
`harness_delete`	`role`	Delete custom role
`harness_list`	`role_assignment`	List role assignments
`harness_get`	`role_assignment`	Get assignment details
`harness_list`	`permission`	List available permissions
`harness_get`	`permission`	Get permission details
`harness_list`	`resource_group`	List resource groups
`harness_get`	`resource_group`	Get resource group details
`harness_describe`	`role`	Discover role schema
`harness_search`	--	Search across role-related resources

For built-in roles (account/org/project/module), resource groups, common permissions, and role assignment structure, consult references/builtin-roles.md.

工具	资源类型	操作
`harness_list`	`role`	列出所有角色
`harness_get`	`role`	获取角色详情
`harness_create`	`role`	创建自定义角色
`harness_update`	`role`	更新自定义角色
`harness_delete`	`role`	删除自定义角色
`harness_list`	`role_assignment`	列出角色分配
`harness_get`	`role_assignment`	获取分配详情
`harness_list`	`permission`	列出可用权限
`harness_get`	`permission`	获取权限详情
`harness_list`	`resource_group`	列出资源组
`harness_get`	`resource_group`	获取资源组详情
`harness_describe`	`role`	探索角色 schema
`harness_search`	--	跨角色相关资源搜索

关于内置角色（账户/组织/项目/模块）、资源组、通用权限及角色分配结构，请参考 references/builtin-roles.md。

Instructions

操作步骤

Step 1: Understand Requirements

步骤1：明确需求

Determine:

Who needs access (user email, group ID, or service account ID)
What level of access (admin, developer, viewer, executor, custom)
Where (account, org, project scope)
Which resources (all or specific resource group)

确定以下信息：

对象：需要访问权限的主体（用户邮箱、组ID或服务账户ID）
权限级别：所需的访问权限等级（admin、developer、viewer、executor、自定义）
范围：权限生效范围（account、org、project层级）
资源：涉及的资源（全部或特定资源组）

Step 2: List Existing Roles

步骤2：列出现有角色

harness_list(
  resource_type="role",
  org_id="<org>",           # optional
  project_id="<project>",   # optional
  search_term="<keyword>"   # optional
)

harness_list(
  resource_type="role",
  org_id="<org>",           # optional
  project_id="<project>",   # optional
  search_term="<keyword>"   # optional
)

Step 3: Check Current Assignments

步骤3：检查当前分配情况

harness_list(
  resource_type="role_assignment",
  org_id="<org>",
  project_id="<project>"
)

harness_list(
  resource_type="role_assignment",
  org_id="<org>",
  project_id="<project>"
)

Step 4: List Available Permissions (for custom roles)

步骤4：列出可用权限（用于自定义角色）

harness_list(resource_type="permission")

harness_list(resource_type="permission")

Step 5: Create Custom Role (if needed)

步骤5：创建自定义角色（如有需要）

harness_create(
  resource_type="role",
  org_id="<org>",
  project_id="<project>",
  body={
    "identifier": "custom_deployer",
    "name": "Custom Deployer",
    "description": "Can execute pipelines and view services",
    "permissions": [
      "core_pipeline_execute",
      "core_pipeline_view",
      "core_service_view",
      "core_environment_view"
    ]
  }
)

Identifier must match pattern:

^[a-zA-Z_][0-9a-zA-Z_]{0,127}$

harness_create(
  resource_type="role",
  org_id="<org>",
  project_id="<project>",
  body={
    "identifier": "custom_deployer",
    "name": "Custom Deployer",
    "description": "Can execute pipelines and view services",
    "permissions": [
      "core_pipeline_execute",
      "core_pipeline_view",
      "core_service_view",
      "core_environment_view"
    ]
  }
)

标识符必须匹配规则：

^[a-zA-Z_][0-9a-zA-Z_]{0,127}$

Step 6: View Resource Groups

步骤6：查看资源组

harness_list(resource_type="resource_group", org_id="<org>", project_id="<project>")

harness_list(resource_type="resource_group", org_id="<org>", project_id="<project>")

Examples

示例

List all roles in a project

列出项目中的所有角色

/manage-roles
Show me all roles available in the payments project

/manage-roles
Show me all roles available in the payments project

Check who has admin access

检查谁拥有管理员权限

/manage-roles
List all role assignments with admin privileges in the default org

/manage-roles
List all role assignments with admin privileges in the default org

Create a custom read-only deployer role

创建自定义只读部署角色

/manage-roles
Create a custom role called "release-manager" that can execute pipelines,
view services and environments, but cannot edit anything

/manage-roles
Create a custom role called "release-manager" that can execute pipelines,
view services and environments, but cannot edit anything

Audit access for a user

审计用户的访问权限

/manage-roles
What roles does jane.smith@company.com have across all projects?

/manage-roles
What roles does jane.smith@company.com have across all projects?

Review resource groups

查看资源组

/manage-roles
Show me all resource groups and what they include

/manage-roles
Show me all resource groups and what they include

Best Practices

最佳实践

Prefer groups over individual users -- assign roles to USER_GROUP for easier management
Follow least privilege -- start with viewer roles and add permissions as needed
Scope narrowly -- use project-level roles over account-level when possible
Use built-in roles first -- create custom roles only when built-in roles do not fit
Naming convention:
```
{role}_{principal}
```
for identifiers (e.g.,
```
deployer_ops_team
```
)

优先选择群组而非单个用户——将角色分配给USER_GROUP以便于管理
遵循最小权限原则——从查看者角色开始，按需添加权限
缩小范围——尽可能使用项目级角色而非账户级角色
优先使用内置角色——仅当内置角色无法满足需求时才创建自定义角色
命名规范：标识符采用
```
{role}_{principal}
```
格式（例如：
```
deployer_ops_team
```
）

Error Handling

错误处理

Error	Cause	Solution
Role not found	Invalid role identifier	Built-in roles start with `_` -- verify exact identifier
Resource group not found	Invalid resource group	Check `harness_list(resource_type="resource_group")`
Principal not found	User/group/SA does not exist	Verify the principal exists before assigning
Duplicate identifier	Role with same ID exists	Use a unique identifier or update the existing role
Permission denied	Caller lacks RBAC management permissions	Need `core_role_view` / `core_role_edit` permissions

错误	原因	解决方案
角色未找到	角色标识符无效	内置角色以 `_` 开头——验证准确的标识符
资源组未找到	资源组无效	调用 `harness_list(resource_type="resource_group")` 检查
主体未找到	用户/群组/服务账户不存在	分配前先验证主体是否存在
标识符重复	已存在相同ID的角色	使用唯一标识符或更新现有角色
权限被拒绝	调用者缺少RBAC管理权限	需要 `core_role_view` / `core_role_edit` 权限

Performance Notes

性能注意事项

List existing roles and resource groups before creating new ones to avoid duplication.
Verify role permissions match the principle of least privilege.
Confirm user/group identifiers are correct before assigning roles — incorrect assignments may grant unintended access.

创建新角色前先列出现有角色和资源组，避免重复。
验证角色权限符合最小权限原则。
分配角色前确认用户/群组标识符正确——错误的分配可能导致意外的权限授予。

Troubleshooting

故障排查

User Cannot Access Resources

用户无法访问资源

List role assignments for the user to confirm a role is assigned
Check the role has the required permissions (
```
harness_get
```
on the role)
Verify the resource group scope includes the target resources
Check that the assignment is not
```
disabled: true
```

列出该用户的角色分配，确认已分配角色
检查角色是否包含所需权限（对角色调用
```
harness_get
```
）
验证资源组范围是否包含目标资源
检查分配是否未设置为
```
disabled: true
```

Custom Role Not Working

自定义角色无法正常工作

Verify all required permissions are included (e.g.,
```
_view
```
permission is needed alongside
```
_edit
```
)
Check the role is assigned at the correct scope (account/org/project)
Confirm the resource group matches the resources the user needs

验证是否包含所有必要权限（例如：
```
_edit
```
权限需要搭配
```
_view
```
权限）
检查角色是否分配在正确的范围（账户/组织/项目）
确认资源组与用户需要访问的资源匹配

Permission Denied When Managing Roles

管理角色时权限被拒绝

The caller needs
```
core_role_edit
```
to create/update roles
The caller needs
```
core_roleassignment_edit
```
to manage assignments
Account-level operations require account admin or equivalent

调用者需要
```
core_role_edit
```
权限才能创建/更新角色
调用者需要
```
core_roleassignment_edit
```
权限才能管理角色分配
账户级操作需要账户管理员或同等权限