peribolos: add org roles feature

[hoxhaeris]

Add Organization Roles Support to Peribolos

This PR adds support for managing GitHub organization custom roles in Peribolos, enabling declarative configuration of role assignments to teams and users.

Changes

1. Configuration Schema (pkg/config/org/org.go)

• Added Roles field to Config struct for declaring role assignments
• Implemented ValidateRoles() for pre-flight validation with case-insensitive team/user matching
• Uses github.NormLogin() for consistent username normalization

2. GitHub API Client (pkg/github/client.go)

Added methods for organization role management:

• ListOrganizationRoles(), ListTeamsWithRole(), ListUsersWithRole()
• AssignOrganizationRoleToTeam(), RemoveOrganizationRoleFromTeam()
• AssignOrganizationRoleToUser(), RemoveOrganizationRoleFromUser()

All mutating operations respect dry-run mode.

3. Main Implementation (cmd/peribolos/main.go)

• Added --fix-org-roles flag to enable role management (gatekeeper)
• Implemented configureOrgRoles()
• Team name -> slug resolution for correct API calls
• Slug -> team name mapping in dump mode for idempotent configurations
• Roles configured after teams are fully populated

4. Test Coverage (pkg/config/org/org_test.go, cmd/peribolos/main_test.go)

• 12 validation test cases (nested teams, case-insensitivity, duplicates)
• 6 team assignment test cases
• 8 user assignment test cases

Example Configuration

orgs:
  my-org:
    teams:
      security-team:
        members: [user1, user2]
      compliance-team:
        members: [user3, user4]

    admins:
      - admin-user

    roles:
      security-manager:
        teams: [security-team]
        users: [admin-user]

      billing-manager:
        teams: [compliance-team]
        users: [admin-user]

Usage

# Validate configuration only
peribolos --config-path=org.yaml

# Apply with dry-run
peribolos --config-path=org.yaml --fix-org-roles --confirm=false

# Apply changes
peribolos --config-path=org.yaml --fix-org-roles --confirm=true

# Dump current organization state
peribolos --dump my-org --github-token-path=token

[netlify]

✅ Deploy Preview for k8s-prow ready!

Name	Link
🔨 Latest commit	7c94f88
🔍 Latest deploy log	https://app.netlify.com/projects/k8s-prow/deploys/692edf9a86f9440007774121
😎 Deploy Preview	https://deploy-preview-555--k8s-prow.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[k8s-ci-robot]

Hi @hoxhaeris. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[hoxhaeris]

/hold
Holding while I finish a set of manual tests using a test GitHub org
/cc @petr-muller
/cc @bradmwilliams

[k8s-ci-robot]

@hoxhaeris: GitHub didn't allow me to request PR reviews from the following users: bradmwilliams.

Note that only kubernetes-sigs members and repo collaborators can review this PR, and authors cannot review their own PRs.

In response to this:

/hold
Hold while I finish a set of manual tests using a test GitHub org
/cc @petr-muller
/cc @bradmwilliams

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[petr-muller]

/ok-to-test

[hoxhaeris]

/test pull-prow-unit-test

[hoxhaeris]

/test pull-prow-unit-test

[hoxhaeris]

/test pull-prow-unit-test

[hoxhaeris]

Tests summary:

What Was Tested

Basic Operations

• Assign role to team
• Assign role to user
• Assign role to both team and user simultaneously
• Remove role from team
• Remove role from user

Cleanup Scenarios

• Role removed from config -> all assignments cleaned up
• Empty roles: {} -> orphaned assignments removed
• Omitted roles key -> assignments cleaned up

Case Sensitivity

• Role names matched case-insensitively (Security_Manager -> security_manager)
• Team references matched case-insensitively
• User references matched case-insensitively

Idempotency

• Running Peribolos twice produces no mutations on second run

Flag Gating

• Without --fix-org-roles flag -> no role changes made
• Dry-run mode (--confirm=false) -> no actual API mutations
• --fix-org-roles requires --fix-teams -> fails with clear error if missing

Dump Functionality

• --dump output includes roles: section
• Dump uses team names (not slugs) for idempotent round-trip

Validation

• Error for role not defined in GitHub
• Error for team not in config
• Error for user not an org member
• Validation runs before any API mutations (fail-fast)

Multiple/Complex Assignments

• Team AND different user assigned to same role
• Partial update: add team + remove user in single run
• Admin users can be assigned roles (not just members)

Pending Invitations

• Users with pending org invitations gracefully skipped with log message

Indirect Assignments (Team Membership)

• Users who have role via team membership are NOT removed when users: []
• Only direct assignments are managed; indirect ones preserved

---

Indirect Assignment Handling

GitHub's API returns users who have roles through team membership with "assignment": "indirect". Peribolos will:

• Filters out indirect assignments when comparing to config
• Only manages direct user assignments
• Team members keep their role through the team even with users: []

This prevents accidental removal of team members who inherit roles.

---

[hoxhaeris]

/test pull-prow-verify-lint

[k8s-ci-robot]

@hoxhaeris: Those labels are not set on the issue: area/prow/tide, area/prow/hook, area/prow/plank, area/prow/deck, area/prow/crier, area/prow/horologium, area/prow/sinker, area/prow/spyglass, area/prow/status-reconciler

In response to this:

/remove-area prow/tide
/remove-area prow/hook
/remove-area prow/plank
/remove-area prow/deck
/remove-area prow/crier
/remove-area prow/horologium
/remove-area prow/sinker
/remove-area prow/spyglass
/remove-area prow/status-reconciler

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

@hoxhaeris: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-prow-verify-lint	7c94f88	link	true	/test pull-prow-verify-lint

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[hoxhaeris]

/remove-area pubsub
/remove-area crier
/remove-area gangway
/remove-area podutils/initupload
/remove-area plugins
/remove-area tide
/remove-area gerrit
/remove-area prowcm
/remove-area hook
/remove-area status-reconciler
/remove-area pod-utilities
/remove-area deck
/remove-area branchprotector
/remove-area podutils/sidecar
/remove-area podutils/entrypoint
/remove-area podutils/clonerefs
/remove-area podutils/gcsupload
/remove-area sinker
/remove-area moonraker
/remove-area ghproxy
/remove-area jenkins-operator
/remove-area spyglass
/remove-area horologium
/remove-area documentation