Org & Governance
Complete guide to organization management, RBAC, teams, grants, service accounts, and break-glass operations.
An Organization is the top-level isolation boundary in GitOpsHQ. All resources — projects, clusters, tenants, environments, and members — belong to exactly one organization. This module covers the full governance model: membership, roles, resource grants, teams, service accounts, and break-glass emergency access.
Organization Lifecycle
Creating an Organization
Name and Slug
Choose a display name (e.g., "Acme Corp") and a URL-safe slug (e.g., acme-corp). The slug is used in URLs and API paths.
Owner Assignment
The user who creates the organization is automatically assigned the owner role. All new organizations start on the Free plan (OrgPlanFree). At least one owner must exist at all times.
Organization Settings
Navigate to Organization > Settings (/org/settings) to manage:
| Setting | Description |
|---|---|
| Name | Display name visible in the UI and notifications |
| Slug | URL-safe identifier (changing this updates all resource URLs) |
| Environments | Ordered list of org-level environment stages |
| Registry | Chart registry and OCI integration settings |
Managing Environments
Organization environments define the ordered pipeline stages that all projects inherit. Common patterns:
| Pattern | Stages |
|---|---|
| Standard | dev → staging → production |
| Multi-region | dev → staging → us-prod → eu-prod |
| Hotfix | dev → hotfix → production |
| Regulated | dev → qa → uat → staging → production |
Environments are ordered — this order defines the default promotion direction. You can reorder environments at any time via drag-and-drop in the settings UI.
There is currently no organization deletion endpoint in the API. Contact support if you need to remove an organization.
Membership and Roles
Built-In Roles
GitOpsHQ provides four built-in roles with a fixed permission hierarchy:
| Capability | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| Clusters | Full CRUD | Full CRUD | Read + Operate | Read |
| Projects | Full CRUD | Full CRUD | Read + Operate | Read |
| Tenants | Full CRUD | Full CRUD | Read + Operate | Read |
| Environments | Full CRUD | Full CRUD | Read | Read |
| Teams | Full CRUD | Full CRUD | Read own | None |
| Permissions | Full CRUD | Read + Assign | Read own | Read own |
| Org Settings | Full CRUD | Read | None | None |
| Service Accounts | Full CRUD | Full CRUD | None | None |
| Break-Glass | Create | Create | None | None |
Role Descriptions
Full control over the organization, including member roles and all operational resources. Every organization must have at least one owner.
Typical user: CTO, VP of Engineering, Head of Platform
Can manage all operational resources (clusters, projects, tenants) and assign resource-level grants. Cannot change billing or organization-level settings.
Typical user: Platform Lead, DevOps Manager
Can read and operate on resources they have been granted access to. Default access is read-oriented; write access comes from explicit resource grants.
Typical user: DevOps Engineer, SRE, Developer
Read-only access to all resources. Cannot perform any mutations. Useful for auditors, stakeholders, and external consultants.
Typical user: Auditor, Project Manager, External Consultant
Managing Members
| Operation | Who Can Do It | Endpoint |
|---|---|---|
| Invite | Owner, Admin | POST /api/v1/organizations/{slug}/invitations |
| Change role | Owner | PATCH /api/v1/organizations/{slug}/members/{id} |
| Remove | Owner, Admin | DELETE /api/v1/organizations/{slug}/members/{id} |
You cannot remove or demote the last owner. The system returns 400 cannot remove the last owner or 400 cannot demote the last owner if you attempt this.
Resource-Level Grants
While org roles provide baseline permissions, resource grants allow fine-grained access control at the cluster, project, or tenant level.
Grant Types
| Grant Type | Scope | Example |
|---|---|---|
| Cluster Grant | Single cluster | "SRE team can operate on production cluster" |
| Project Grant | Single project | "DevOps team can manage releases in payments project" |
| Tenant Grant | Single tenant | "Partner team can read tenant-acme resources" |
Named Presets
Presets are pre-defined bundles of actions that accelerate grant assignment:
| Preset | Actions Included |
|---|---|
cluster.read | View cluster status, inventory, agent health |
cluster.operate | Read + sync, restart, scale workloads |
cluster.lifecycle | Operate + register, deregister clusters |
cluster.admin | Full cluster management including token rotation |
cluster.inspect | View cluster details and diagnostics |
cluster.secrets_read | Read cluster-level secrets |
tenant.viewer | View tenant configuration and bindings |
Custom Allow/Deny Lists
For scenarios where presets are not granular enough, you can specify explicit allow and deny action lists:
{
"grantType": "project",
"resourceId": "proj_01H5K...",
"subjectType": "team",
"subjectId": "team_01H5K...",
"allow": ["project.releases.create", "project.releases.deploy"],
"deny": ["project.settings.delete"]
}Permission Resolution
Effective permissions are computed by merging the org role defaults with explicit grants:
Rules:
- Org role provides a baseline set of allowed actions.
- Resource grants add or restrict actions for specific resources.
- Explicit deny always wins — if any grant denies an action, it is blocked regardless of other allows.
- If no allow exists (from role or grant), the action is implicitly denied.
Teams
Teams are named groups of members that simplify grant management. Instead of assigning grants to individual users, assign them to teams.
The Teams API lives under /api/v2/teams and requires the FeatureTeams feature gate to be enabled for your organization.
Team Operations
| Operation | Description | Endpoint |
|---|---|---|
| Create | Create a named team | POST /api/v2/teams |
| Add member | Add an org member to a team | POST /api/v2/teams/{id}/members |
| Remove member | Remove a member from a team | DELETE /api/v2/teams/{id}/members/{userId} |
| Assign grant | Give the team a permission grant | POST /api/v2/permissions |
| Delete | Delete the team (grants are revoked) | DELETE /api/v2/teams/{id} |
Team-Based Access Pattern
When a user is added to a team, they inherit the team's grants. When removed, those grants are revoked. This makes onboarding and offboarding straightforward.
Service Accounts
Service accounts are machine identities designed for CI/CD pipelines, automation scripts, and external integrations.
Service Account Properties
| Property | Description |
|---|---|
| Name | Human-readable label (e.g., "github-actions-deployer") |
| Role | Assigned org role: viewer, member, or admin (service accounts cannot hold the owner role) |
| Allowed Actions | Action patterns the token is authorized for |
| Tokens | One or more API tokens with individual expiry dates |
Token Management
| Operation | Description |
|---|---|
| Create | Generate a new token with configurable expiry |
| Rotate | Create a new token and revoke the old one |
| Revoke | Immediately invalidate a specific token |
| Last used | Timestamp and IP of last token usage |
Example: CI/CD Integration
curl -X POST \
-H "Authorization: Bearer sa_token_01H5K..." \
-H "X-Organization-ID: org_01H5K..." \
-H "Content-Type: application/json" \
-d '{"targetVersion":"2.1.0"}' \
https://app.gitopshq.io/api/v2/workloads/{id}/upgradeService accounts appear as distinct actor types in audit logs. Every action performed by a service account is fully traceable.
Break-Glass Sessions
Break-glass sessions provide time-limited, emergency elevated access for incident response. They are an Enterprise-tier feature designed to handle situations where normal approval workflows are too slow.
Break-Glass Flow
Request
A caller with the ActionOrgPermissionsManage permission creates a break-glass session via CreateBreakGlassSession, specifying: scope (which resources), duration (1 to 240 minutes), and a justification reason. The session is activated immediately -- there is no separate approval step.
Active Session
The caller receives temporarily elevated permissions. A visible timer shows the remaining duration. All actions are audit-logged with the break-glass session ID.
Expiry
The session automatically expires after the configured duration. Permissions revert to the user's normal level. An audit summary is generated.
Break-Glass Rules
- Every break-glass session must include a justification reason (free text).
- Sessions have a maximum duration of 240 minutes (4 hours).
- All actions during a break-glass session are tagged with the session ID in audit logs.
- Break-glass sessions cannot be extended; a new session must be requested.
- The UI surfaces active break-glass sessions prominently to prevent normalization of emergency access.
IAM Center
The IAM Center (/iam) provides a unified view of all identity and access management for the organization.
| Tab | Content |
|---|---|
| Overview | Summary dashboard: member count, team count, active grants, service account count |
| Members | Member list with role badges, invitation history, role change controls |
| Teams | Team management: create, edit, add/remove members, view team grants |
| Access | Grant composer: create, edit, delete resource grants with preset or custom actions |
| Service Accounts | Service account catalog: create, manage tokens, view usage history |
| Break-Glass | Active and historical break-glass sessions with approval status |
| Approval Policies | Configure approval requirements for sensitive actions (Enterprise) |
| IAM Audit | Filtered audit log for identity and access events only |
Common Governance Patterns
- Roles: 2 owners, everyone else is
admin - Teams: Not needed at this scale
- Grants: Default org role is sufficient
- Service accounts: 1 for CI/CD pipeline
- Break-glass: Not needed; admins have sufficient access
- Roles: 2 owners, 3-5 admins, rest are
member - Teams:
platform,backend,frontend,sre - Grants: Project-level operator grants per team
- Service accounts: 1 per CI/CD pipeline (GitHub Actions, GitLab CI, etc.)
- Break-glass: Configure for production incidents
- Roles: 2-3 owners, dedicated admins per domain, strict
member/viewerfor everyone else - Teams: Per business unit + per function (platform, sre, devops, security)
- Grants: Fine-grained cluster + project + tenant grants per team
- Service accounts: Per-project, with scoped action patterns
- Break-glass: Mandatory with post-incident review process
- Approval policies: Required for production deployments
Error Reference
Security Recommendations
- Limit owner count to 2-3 people. Owners have unrestricted access including billing and deletion.
- Use teams for grants, not individual user grants. This simplifies auditing and offboarding.
- Scope service accounts narrowly. A CI/CD service account should only have the actions it needs (e.g.,
project.releases.create,project.releases.deploy). - Review break-glass logs after every emergency. Ensure actions taken were necessary and appropriate.
- Audit IAM changes weekly. Use the IAM Audit tab to review role changes, grant modifications, and token rotations.