cki_tools.rover_group_sync

Overview

The rover_group_sync tool syncs Rover group membership from declarative YAML definitions against the Internal Groups API.

Group membership is defined in a YAML file using cki-lib config_tree features (.default, .extends) for owner inheritance and member list reuse. The tool compares the desired state from YAML against the live state from the API and reports (or applies) the diff.

Usage

python -m cki_tools.rover_group_sync [options] <yaml-file>

positional arguments:
  yaml_file             Path to the group definitions YAML file

options:
  -h, --help            show this help message and exit
  --fix                 Apply changes (default: dry-run, show diff only)
  --api-url API_URL     Internal Groups API base URL (env: ROVER_GROUP_SYNC_API_URL)
  --principal PRINCIPAL Kerberos principal (env: KRB_PRINCIPAL)
  --password PASSWORD   Kerberos password (env: KRB_PASSWORD)

Operation Modes

• Diff mode (default): Shows what would change per group without modifying anything. Exit code 0 on success, 1 on safety check failure or missing groups.
• Fix mode (--fix): Applies changes via the membersMod, ownersMod, and PATCH endpoints.

Examples

Show diff for all groups:

python -m cki_tools.rover_group_sync --api-url "$API_URL" groups/myproject.yaml

Apply changes:

python -m cki_tools.rover_group_sync --api-url "$API_URL" --fix groups/myproject.yaml

Authentication

Uses an existing Kerberos ticket from the credential cache to obtain an OIDC Bearer token via SPNEGO -> authorization_code + PKCE flow against auth.redhat.com. No additional configuration needed if kinit has been run.

For CI, pass --principal and --password (or set KRB_PRINCIPAL and KRB_PASSWORD environment variables) to acquire credentials programmatically.

YAML Schema

The YAML file uses cki-lib config_tree features:

• .default: Merged into every group automatically. Use for shared owners and notes.
• .extends: Inherit members/owners from named templates.
• Dot-prefixed keys (e.g. .team): Templates, stripped from output.

Members and owners are dicts with Kerberos UIDs as keys (values are always null). All entities are sent to the API as user type.

notes is synced to the group’s notes field in the API. Use it in .default to set a standard notice on all groups:

.default:
  owners:
    alice:
    bot-account:
  notes: >-
    Please do not modify membership directly, it is managed at
    https://gitlab.com/org/group/project

.team:
  members:
    alice:
    bob:

my-group:
  .extends: .team
  description: My project - team members
  members:
    charlie:

Environment variables

CLI arguments take precedence over environment variables.

Safety Guards

• Refuse to empty: Aborts if changes would remove all members or all owners from a group.
• Dry-run by default: Requires --fix to apply changes.
• Token refresh: Bearer tokens are refreshed automatically before expiry.

Dependencies

Install with the rover-group-sync extra:

pip install 'cki-tools[rover-group-sync]'