From 48a6c8fef12710aa7f570d40ebc9731357e5d347 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Fjellstr=C3=B6m?= <mattias.fjellstrom@gmail.com>
Date: Thu, 7 May 2026 13:02:24 +0200
Subject: [PATCH] feat: add display_name filter to github_external_groups data
 source

Add an optional display_name argument to the github_external_groups
data source. When provided, it filters external groups server-side
using the GitHub API's display_name query parameter, reducing the
amount of data returned and stored in state.

Changes:
- Add display_name optional string attribute to data source schema
- Pass display_name to ListExternalGroupsOptions when set
- Include display_name in resource ID for uniqueness
- Add acceptance tests for both filtered and unfiltered queries
- Update documentation and add filtered usage example

Closes #3409

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/data-sources/external_groups.md          | 20 +++++++-
 .../data-sources/external_groups/example_2.tf | 11 +++++
 github/data_source_github_external_groups.go  | 15 +++++-
 ...data_source_github_external_groups_test.go | 49 +++++++++++++++++++
 .../data-sources/external_groups.md.tmpl      |  8 ++-
 5 files changed, 100 insertions(+), 3 deletions(-)
 create mode 100644 examples/data-sources/external_groups/example_2.tf
 create mode 100644 github/data_source_github_external_groups_test.go

diff --git a/docs/data-sources/external_groups.md b/docs/data-sources/external_groups.md
index 7823355c6f..35c05628f3 100644
--- a/docs/data-sources/external_groups.md
+++ b/docs/data-sources/external_groups.md
@@ -10,6 +10,8 @@ Use this data source to retrieve external groups belonging to an organization.
 
 ## Example Usage
 
+### All external groups
+
 ```terraform
 data "github_external_groups" "example_external_groups" {}
 
@@ -22,9 +24,25 @@ output "groups" {
 }
 ```
 
+### Filtered by display name
+
+```terraform
+data "github_external_groups" "example_external_groups_filtered" {
+  display_name = "my-group"
+}
+
+locals {
+  filtered_groups = data.github_external_groups.example_external_groups_filtered
+}
+
+output "groups" {
+  value = local.filtered_groups
+}
+```
+
 ## Argument Reference
 
-N/A. This resource will retrieve all the external groups belonging to an organization.
+- `display_name` - (Optional) Filter the list of external groups by display name. Only groups whose name contains this value will be returned.
 
 ## Attributes Reference
 
diff --git a/examples/data-sources/external_groups/example_2.tf b/examples/data-sources/external_groups/example_2.tf
new file mode 100644
index 0000000000..d046b3445f
--- /dev/null
+++ b/examples/data-sources/external_groups/example_2.tf
@@ -0,0 +1,11 @@
+data "github_external_groups" "example_external_groups_filtered" {
+  display_name = "my-group"
+}
+
+locals {
+  filtered_groups = data.github_external_groups.example_external_groups_filtered
+}
+
+output "groups" {
+  value = local.filtered_groups
+}
diff --git a/github/data_source_github_external_groups.go b/github/data_source_github_external_groups.go
index b45023ec90..713d209815 100644
--- a/github/data_source_github_external_groups.go
+++ b/github/data_source_github_external_groups.go
@@ -14,6 +14,10 @@ func dataSourceGithubExternalGroups() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: dataSourceGithubExternalGroupsRead,
 		Schema: map[string]*schema.Schema{
+			"display_name": {
+				Type:     schema.TypeString,
+				Optional: true,
+			},
 			"external_groups": {
 				Type:     schema.TypeList,
 				Computed: true,
@@ -48,6 +52,11 @@ func dataSourceGithubExternalGroupsRead(ctx context.Context, d *schema.ResourceD
 
 	opts := &github.ListExternalGroupsOptions{}
 
+	if v, ok := d.GetOk("display_name"); ok {
+		displayName := v.(string)
+		opts.DisplayName = &displayName
+	}
+
 	externalGroups := new(github.ExternalGroupList)
 
 	for {
@@ -80,6 +89,10 @@ func dataSourceGithubExternalGroupsRead(ctx context.Context, d *schema.ResourceD
 		return diag.FromErr(err)
 	}
 
-	d.SetId(fmt.Sprintf("/orgs/%v/external-groups", orgName))
+	resourceID := fmt.Sprintf("/orgs/%v/external-groups", orgName)
+	if opts.DisplayName != nil {
+		resourceID = fmt.Sprintf("/orgs/%v/external-groups/%v", orgName, *opts.DisplayName)
+	}
+	d.SetId(resourceID)
 	return nil
 }
diff --git a/github/data_source_github_external_groups_test.go b/github/data_source_github_external_groups_test.go
new file mode 100644
index 0000000000..2317c4ddc7
--- /dev/null
+++ b/github/data_source_github_external_groups_test.go
@@ -0,0 +1,49 @@
+package github
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+)
+
+func TestAccGithubExternalGroupsDataSource(t *testing.T) {
+	t.Run("queries_all", func(t *testing.T) {
+		config := `
+			data "github_external_groups" "all" {}
+		`
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessEMUEnterprise(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config: config,
+					Check: resource.ComposeAggregateTestCheckFunc(
+						resource.TestCheckResourceAttrSet("data.github_external_groups.all", "external_groups.#"),
+					),
+				},
+			},
+		})
+	})
+
+	t.Run("queries_with_display_name_filter", func(t *testing.T) {
+		config := `
+			data "github_external_groups" "filtered" {
+				display_name = "test"
+			}
+		`
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessEMUEnterprise(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config: config,
+					Check: resource.ComposeAggregateTestCheckFunc(
+						resource.TestCheckResourceAttrSet("data.github_external_groups.filtered", "external_groups.#"),
+					),
+				},
+			},
+		})
+	})
+}
diff --git a/templates/data-sources/external_groups.md.tmpl b/templates/data-sources/external_groups.md.tmpl
index 206555129b..c311e3702a 100644
--- a/templates/data-sources/external_groups.md.tmpl
+++ b/templates/data-sources/external_groups.md.tmpl
@@ -10,11 +10,17 @@ Use this data source to retrieve external groups belonging to an organization.
 
 ## Example Usage
 
+### All external groups
+
 {{ tffile "examples/data-sources/external_groups/example_1.tf" }}
 
+### Filtered by display name
+
+{{ tffile "examples/data-sources/external_groups/example_2.tf" }}
+
 ## Argument Reference
 
-N/A. This resource will retrieve all the external groups belonging to an organization.
+- `display_name` - (Optional) Filter the list of external groups by display name. Only groups whose name contains this value will be returned.
 
 ## Attributes Reference