[BUG] github_team_sync_group_mapping repeatedly diffs when group_description differs between IdP catalog and team mapping endpoint

[mhascak]

Terraform Version

Terraform v1.10.0

Affected Provider

integrations/github v6.12.1

Affected Resource

github_team_sync_group_mapping

Summary

github_team_sync_group_mapping can produce a persistent in-place update when only group.group_description differs between the desired config and the value returned by GitHub's team-specific mapping endpoint.

The confusing part is that GitHub's organization-level Team Sync IdP group catalog can return the updated group_description, while the team-specific mapping endpoint for the same group_id continues returning an older/stale group_description. Because the provider reads resource state from the team-specific mapping endpoint and group is modeled as a TypeSet, Terraform plans to remove and re-add the same group block on every run.

Terraform Configuration

This follows the documented pattern using the IdP group catalog:

data "github_organization_team_sync_groups" "all" {}

resource "github_team" "example" {
  name        = "example-team"
  description = "example"
  privacy     = "closed"
}

resource "github_team_sync_group_mapping" "example" {
  team_slug = github_team.example.slug

  dynamic "group" {
    for_each = [
      for g in data.github_organization_team_sync_groups.all.groups :
      g if g.group_id == "00000000-0000-0000-0000-000000000000"
    ]

    content {
      group_id          = group.value.group_id
      group_name        = group.value.group_name
      group_description = group.value.group_description
    }
  }
}

Observed API Behavior

For the same group_id, the org-level catalog returns the current IdP group description:

gh api '/orgs/ORG/team-sync/groups?q=example-idp-group'

{
  "groups": [
    {
      "group_id": "00000000-0000-0000-0000-000000000000",
      "group_name": "example-idp-group",
      "group_description": "current description"
    }
  ]
}

But the team-specific mapping endpoint returns a stale/historical description for the same group_id:

gh api '/orgs/ORG/teams/example-team/team-sync/group-mappings'

{
  "groups": [
    {
      "group_id": "00000000-0000-0000-0000-000000000000",
      "group_name": "example-idp-group",
      "group_description": "old description",
      "status": "synced",
      "synced_at": "2026-05-22T13:49:30.000+02:00"
    }
  ]
}

Observed Terraform Plan

Terraform repeatedly plans an in-place update even after apply:

# github_team_sync_group_mapping.example will be updated in-place
~ resource "github_team_sync_group_mapping" "example" {
    id = "teams/example-team/team-sync/group-mappings"

  - group {
      - group_description = "old description" -> null
      - group_id          = "00000000-0000-0000-0000-000000000000" -> null
      - group_name        = "example-idp-group" -> null
    }
  + group {
      + group_description = "current description"
      + group_id          = "00000000-0000-0000-0000-000000000000"
      + group_name        = "example-idp-group"
    }
}

Plan: 0 to add, 1 to change, 0 to destroy.

Re-running apply does not clear the diff. The next plan shows the same change.

Expected Behavior

Either:

1. The provider should converge state after PATCH if GitHub supports updating group_description, or
2. The provider should avoid treating group_description drift as a destructive TypeSet element replacement when group_id is unchanged, or
3. The documentation should clarify that group_description is read from the team mapping endpoint and may not converge with the organization IdP catalog.

Actual Behavior

The provider sends the desired group list via CreateOrUpdateIDPGroupConnectionsBySlug, then reads back via ListIDPGroupsForTeamBySlug. The read returns the stale group_description, so Terraform keeps planning the same TypeSet element replacement.

Relevant Provider Implementation

From resource_github_team_sync_group_mapping.go:

• Read uses ListIDPGroupsForTeamBySlug
• Update uses CreateOrUpdateIDPGroupConnectionsBySlug, then calls Read
• group is a TypeSet
• group_description is required and part of the set element

This makes the resource sensitive to stale/non-converging group_description values even when the actual binding identity (group_id) is correct.

Notes

This was observed with an Enterprise organization using Team Sync with an external IdP-backed group. The team description itself was already updated correctly; only the Team Sync mapping endpoint continued returning stale group metadata.

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀