Access

Access has two parts:

• An identity source decides who can join the organization.
• An SSO group binding gives GantryCD roles to those members.

A user needs both an active organization membership and a role before they can work with organization resources.

Configure an identity source

Open Settings → Identity Sources and select Add Source. Give the source a short slug, then choose its provider.

GitHub

GitHub sign-in must already be enabled for the GantryCD installation. If GitHub is not available in the provider list, ask the GantryCD administrator to enable it.

Choose who may join the organization:

• GitHub Organization member: any member of the named GitHub organization.
• GitHub Team member: only members of the named team. Use the team slug, such as platform, rather than its display name.

GantryCD asks GitHub for access to organization and team membership during sign-in.

Google Workspace

Google sign-in must already be enabled for the GantryCD installation. Add one or more verified Workspace domains, such as acme.com.

An account may join when its Workspace domain matches one of these values. Personal gmail.com accounts do not match.

OIDC

First, create an OIDC client in your identity provider. Register this redirect URI, using the public URL of your GantryCD installation:

https://gantry.example.com/api/v1/auth/sso/callback

Then add the source in GantryCD:

• Issuer URL: the issuer used for OIDC discovery.
• Client ID and secret: the credentials from the OIDC client.
• Required group: the IdP group whose members may join the organization.

GantryCD requests the openid, profile, and email scopes. Open the advanced settings only when your provider needs different claims or an extra scope:

• Groups claim: where the group list is returned. Default: groups.
• Username claim: the name shown for the user. Default: preferred_username.
• Email claim: the user’s email. Default: email.
• Groups scope: an extra scope needed to return group membership. It has no default because each provider uses a different value.

The required group must appear in the configured groups claim, either in the ID token or from the user info endpoint. Use Test on the identity source to check that GantryCD can reach its discovery endpoint.

Share the login URL

The Identity Sources page shows a Team login URL for the organization. Share this URL with members. It starts the organization login flow and checks the rules of its enabled identity sources.

Map groups to roles

Open Settings → Roles, find SSO group → role bindings, and select Add binding.

Choose the identity source, enter the exact group key, and select the roles to grant. The group key depends on the provider:

GitHub team keys use the organization login and team slug. A team slug on its own does not match.

Each binding may grant up to five roles. Members receive the combined permissions of every selected role. The binding belongs to one identity source, so the same group name from another source does not match it.

After adding a binding for a new group, ask existing users to sign in again so GantryCD can refresh their group membership. Disabling an identity source stops its bindings from granting roles.

Limit access

The role defines what the group can reach. The binding itself has no resource scope. Use a custom role when a team needs access only to resources carrying certain authorization labels.

Use a direct role assignment only for a fixed exception. Group bindings are a better default because access follows membership in the identity provider.

Role keys

A custom role carries a key as well as a display name. You choose the key when you create the role, using lowercase letters, digits and hyphens. The key is what everything else points at — a role assignment, a group binding, and the role_key argument in Terraform — so it cannot be changed afterwards. The name can be renamed at any time.

Pick the key you want to write in your configuration. To change one later, create a role with the new key and move the assignments to it.

Service accounts are for code. Standalone service accounts use tokens for CI and other tools. Each stack also has a built-in service account used only during its runs.

The stack account starts with no roles. Grant it access only when the stack must call GantryCD, such as when it reads another stack’s outputs or follows the stacks-of-stacks pattern.

Target resources with authorization labels

Authorization labels are protected access selectors. Set them on stacks, contexts, runner groups, SCM integrations, notification integrations, and standalone service accounts. In a custom role, choose a resource type and action, then enter one exact authorization label. Leave the label empty to grant that action across the resource type in the organization.

A resource can have multiple labels. For example:

A stack:read grant targeting team-payments reaches both payments stacks. A grant targeting env-production reaches both production stacks. Grants add access; they do not require a resource to match all of the principal’s granted labels. To grant a narrower subset, give those resources a dedicated label.

Names and glob patterns do not grant access. A resource with no authorization labels is reachable only through a grant covering the entire resource type. Ordinary metadata labels used for filtering, runner selection, or context auto-attach do not grant access either.

Adding or removing an authorization label requires assign_label for that label on the resource type, in addition to permission to create or update the resource. A creator whose grant targets a label must include that label when creating the resource. These rules prevent someone with ordinary edit access from moving a resource into another team’s scope.

Cloud integrations use the parent stack’s authorization labels, but still need a cloud_integration grant. Runners use their runner group’s labels. Roles, memberships, identity sources, and organization administration remain organization-scoped.

For a standalone service account, open Settings → Service accounts and use Edit labels on its row. These labels decide who may manage the account; the roles assigned to it decide what the account may do. The Manage button edits its roles and tokens.

The Terraform provider can manage the same authorization labels and role grants as code.