Manage Roles

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="",           # optional
  project_id="",   # optional
  search_term=""   # optional
)

Step 3: Check Current Assignments

harness_list(
  resource_type="role_assignment",
  org_id="",
  project_id=""
)

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="",
  project_id="",
  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="", project_id="")

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: harness
• Source: harness/harness-skills
• License: Apache-2.0
• Homepage: https://developer.harness.io/docs/platform/harness-ai/harness-skills/

Install and usage instructions live in the source repository linked above.