Skip to main content

almaforge_github_connector Resource

Manage an AlmaForge GithubConnector resource.

Before you start​

Use the Terraform setup guide to install the provider and sign in. Your identity needs permission to manage this resource. Keep one owner for each resource name, following the ownership rules.

Create a GitHub OAuth app and register the callback URL described in the GitHub SSO guide. Have the organization name, team slug, and existing AlmaForge role names ready. teams_to_roles grants those roles to members of the selected team.

Keep a working admin login while testing the connector. Creating this resource does not create the GitHub organization, team, OAuth app, or AlmaForge roles.

Example Usage​

Download main.tf into its own directory. Replace example values with your cluster and integration settings. Use the plan and apply workflow after preparing the prerequisites above.

Supply sensitive inputs from your secret manager or protected TF_VAR_ environment variables. Sensitive values are hidden in normal plan output but remain in saved plans and state. See connector secrets.

HCL
# Map a GitHub organization team to existing AlmaForge roles.
terraform {
  required_providers {
    almaforge = {
      source = "get.almaforge.com/almaforge/almaforge"
    }
  }
}

provider "almaforge" {}

variable "client_secret" {
  type        = string
  description = "GitHub OAuth app secret. Supply through TF_VAR_client_secret."
  sensitive   = true
}

resource "almaforge_github_connector" "github" {
  metadata = {
    name = "github"
  }
  spec = {
    client_id     = "YOUR_CLIENT_ID"
    client_secret = var.client_secret
    teams_to_roles = [
      {
        organization = "example"
        team         = "ops"
        roles        = ["editor"]
      }
    ]
  }
}

See the configuration reference for the resource manifest and field context.

Changes and deletion​

Configuration is authoritative. Removing an optional attribute resets its API default or clears it when no default exists. Changing metadata.name replaces the resource. Review the plan before applying. See lifecycle behavior.

Destroy deletes the connector. Check the linked integration guide's operations and removal sections before removing a connector that users or approval workflows depend on.

To read an existing object without managing it, use the named data source.

Schema​

Required​

Optional​

Nested Schema for metadata​

Required:

  • name (String) Resource name. Changing this name replaces the resource.

Optional:

  • labels (Map of String) Labels attached to the resource.

Read-Only:

  • resource_version (String) Server revision used to detect concurrent changes.

Nested Schema for spec​

Optional:

  • allowed_email_domains (List of String) AllowedEmailDomains is an optional ordered list of email domains used to pick the user's AlmaForge username from their verified GitHub emails. The domains are evaluated in order. The first verified email whose domain matches any listed domain wins. If empty, the primary verified email is used.
  • api_endpoint_url (String) APIEndpointURL is the URL of the API endpoint of the GitHub instance this connector is for. Defaults to https://api.github.com when empty.
  • client_id (String) ClientID is the GitHub OAuth app client ID.
  • client_secret (String, Sensitive) ClientSecret is the GitHub OAuth app client secret. Accepts a literal value or a value-expansion reference such as "${file:/etc/github.secret}" or "${env:GITHUB_CLIENT_SECRET}".
  • display (String) Display is the connector display name shown in the login UI.
  • endpoint_url (String) EndpointURL is the URL of the GitHub instance this connector is for. Defaults to https://github.com when empty.
  • teams_to_roles (Attributes List) TeamsToRoles maps GitHub team memberships onto allowed roles. (see below for nested schema)

Nested Schema for spec.teams_to_roles​

Optional:

  • organization (String) Organization is the GitHub organization the user must belong to.
  • roles (List of String) Roles is the list of allowed AlmaForge roles for this org/team.
  • team (String) Team is the team within the organization the user must belong to.

Import​

Create the matching resource block first, then import the existing object's metadata.name. With the example above, the Terraform address and server name are:

Terminal
terraform import almaforge_github_connector.github githubterraform plan

Use the address from your configuration and the name of the existing object. Import records the object in Terraform state. Review the first plan carefully because omitted fields will reset or clear on apply. The import guide also covers generating configuration from an existing object.

Supply the connector's current secret values before applying. The API redacts credentials on reads, so import cannot recover them. Configured secrets are preserved during subsequent refreshes.