Skip to content
gdlc

Assign an organization role to a team

Use assign_team_role to grant an existing organization role to an existing team. This is a write that mutates permissions across every repo the role’s definition covers — read the confirm-echo contract before your first call if you haven’t used one of this plugin’s write tools before.

Prerequisites

Section titled “Prerequisites”
  • github-org-identity installed.
  • A GitHub token resolvable via GITHUB_TOKEN or gh auth token, with the org’s admin:org scope or App-installation members/ organization_administration permission. This is a mutation — the identity needs write access to organization-roles, not just read.
  • The numeric roleId (from list_organization_roles) and the target team’s slug (not its display name).
  • This tool only assigns a role to a team that already exists. It does not create teams.

Steps

Section titled “Steps”

  1. Ask for the tool, passing the role id twice — once as roleId, once as confirmRoleId — plus the team’s slug:

    Use assign_team_role for org my-org, roleId 8132, confirmRoleId 8132, teamSlug my-team.

    The two role-id fields must be identical. If they aren’t, the call throws confirmation_mismatch before any GitHub API request is made — this is a deliberate guard, not a bug; retry with matching values once you’ve confirmed the roleId you meant to use.

  2. On success you get back { "org": "my-org", "roleId": 8132, "teamSlug": "my-team" }.

  3. Confirm the assignment took effect with list_role_teams — the team should now appear in that role’s team list.

If the call fails

Section titled “If the call fails”
  • confirmation_mismatch — roleId and confirmRoleId didn’t match; no API call was made. Retry with the same value in both fields.
  • missing_scope — no resolvable token.
  • github_api_error — the roleId or teamSlug doesn’t exist, or the identity lacks org-roles write access.

Next

Section titled “Next”

Remove the role again if you were experimenting, or assign the same role to a user.