Skip to content

SKILL.md

Latest commit

 

History

History
189 lines (146 loc) · 5.93 KB

SKILL.md

File metadata and controls

189 lines (146 loc) · 5.93 KB
Raw
name manage-roles
description Manage Harness RBAC roles, role assignments, permissions, and resource groups via MCP v2 tools. List, create, update, and delete custom roles. View role assignments and permissions for users, groups, and service accounts. Use when asked to manage access control, assign roles, check permissions, create custom roles, review RBAC configuration, onboard users, or audit access. Trigger phrases: manage roles, RBAC, role assignment, user permissions, access control, custom role, resource group, who has access, grant access, revoke access.
metadata
author version mcp-server
Harness
1.0.0
harness-mcp-v2
license Apache-2.0
compatibility Requires Harness MCP v2 server (harness-mcp-v2)

Manage Roles Skill

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

MCP v2 Tools Used

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.

Instructions

Step 1: Understand Requirements

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)

Step 2: List Existing Roles

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

Step 3: Check Current Assignments

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

Step 4: List Available Permissions (for custom roles)

harness_list(resource_type="permission")

Step 5: Create Custom Role (if needed)

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}$

Step 6: View Resource Groups

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

Check who has admin access

/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

Audit access for a user

/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

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)

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

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

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

Custom Role Not Working

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

Permission Denied When Managing Roles

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