[FEAT] Support looking up github_membership data source by user_id

Add an optional 'user_id' input (mutually exclusive with 'username') to the
github_membership data source. When set, the user is resolved via
GET /user/{id} and the resulting login is used to query the org
membership endpoint, which only accepts logins.

The data source now always exposes 'user_id' as a computed attribute too,
so downstream resources can refer to the stable numeric ID even when the
query used a login.

Refs #524

Author: niklasbeinghaus

docs/data-sources/membership.md

@@ -16,15 +16,31 @@ data "github_membership" "membership_for_some_user" {
 }
 ```
 
+### Lookup by stable user ID
+
+```terraform
+# Look up a membership by the stable GitHub user ID.
+# The numeric ID does not change when the user renames their account.
+data "github_membership" "by_user_id" {
+  user_id = 1
+}
+```
+
 ## Argument Reference
 
-- `username` - (Required) The username to lookup in the organization.
+Exactly one of the following must be set:
+
+- `username` - (Optional) The username (login) to lookup in the organization.
+- `user_id` - (Optional) The GitHub numeric user ID. Stable across username changes; prefer this for lookups that should survive renames.
+
+Other arguments:
 
-- `organization` - (Optional) The organization to check for the above username.
+- `organization` - (Optional) The organization to check for the above user.
 
 ## Attributes Reference
 
-- `username` - The username.
+- `username` - The username (login). Always reflects the user's current login at refresh time.
+- `user_id` - The GitHub numeric user ID.
 - `role` - `admin` or `member` -- the role the user has within the organization.
 - `etag` - An etag representing the membership object.
 - `state` - `active` or `pending` -- the state of membership within the organization. `active` if the member has accepted the invite, or `pending` if the invite is still pending.

examples/data-sources/membership/example_2.tf

@@ -0,0 +1,5 @@
+# Look up a membership by the stable GitHub user ID.
+# The numeric ID does not change when the user renames their account.
+data "github_membership" "by_user_id" {
+  user_id = 1
+}

github/data_source_github_membership.go

@@ -13,8 +13,18 @@ func dataSourceGithubMembership() *schema.Resource {
 
 		Schema: map[string]*schema.Schema{
 			"username": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:         schema.TypeString,
+				Optional:     true,
+				Computed:     true,
+				ExactlyOneOf: []string{"username", "user_id"},
+				Description:  "The username (login) to lookup in the organization. Exactly one of `username` or `user_id` must be set.",
+			},
+			"user_id": {
+				Type:         schema.TypeInt,
+				Optional:     true,
+				Computed:     true,
+				ExactlyOneOf: []string{"username", "user_id"},
+				Description:  "The GitHub numeric user ID to lookup in the organization. Stable across username changes. Exactly one of `username` or `user_id` must be set.",
 			},
 			"organization": {
 				Type:     schema.TypeString,
@@ -37,37 +47,48 @@ func dataSourceGithubMembership() *schema.Resource {
 }
 
 func dataSourceGithubMembershipRead(ctx context.Context, d *schema.ResourceData, meta any) diag.Diagnostics {
-	username := d.Get("username").(string)
-
 	client := meta.(*Owner).v3client
 	orgName := meta.(*Owner).name
 
 	if configuredOrg := d.Get("organization").(string); configuredOrg != "" {
 		orgName = configuredOrg
 	}
 
-	membership, resp, err := client.Organizations.GetOrgMembership(ctx,
-		username, orgName)
+	// Resolve to username (login). If user_id is provided, resolve it via
+	// GET /user/{id} since GitHub's membership endpoints only accept the
+	// username. This makes the data source robust against username changes.
+	var username string
+	if v, ok := d.GetOk("user_id"); ok {
+		userID := int64(v.(int))
+		user, _, err := client.Users.GetByID(ctx, userID)
+		if err != nil {
+			return diag.FromErr(err)
+		}
+		username = user.GetLogin()
+	} else {
+		username = d.Get("username").(string)
+	}
+
+	membership, resp, err := client.Organizations.GetOrgMembership(ctx, username, orgName)
 	if err != nil {
 		return diag.FromErr(err)
 	}
 
 	d.SetId(buildTwoPartID(membership.GetOrganization().GetLogin(), membership.GetUser().GetLogin()))
 
-	err = d.Set("username", membership.GetUser().GetLogin())
-	if err != nil {
+	if err = d.Set("username", membership.GetUser().GetLogin()); err != nil {
 		return diag.FromErr(err)
 	}
-	err = d.Set("role", membership.GetRole())
-	if err != nil {
+	if err = d.Set("user_id", membership.GetUser().GetID()); err != nil {
 		return diag.FromErr(err)
 	}
-	err = d.Set("etag", resp.Header.Get("ETag"))
-	if err != nil {
+	if err = d.Set("role", membership.GetRole()); err != nil {
 		return diag.FromErr(err)
 	}
-	err = d.Set("state", membership.GetState())
-	if err != nil {
+	if err = d.Set("etag", resp.Header.Get("ETag")); err != nil {
+		return diag.FromErr(err)
+	}
+	if err = d.Set("state", membership.GetState()); err != nil {
 		return diag.FromErr(err)
 	}
 	return nil

github/data_source_github_membership_test.go

@@ -26,6 +26,7 @@ func TestAccGithubMembershipDataSource(t *testing.T) {
 			resource.TestCheckResourceAttrSet("data.github_membership.test", "role"),
 			resource.TestCheckResourceAttrSet("data.github_membership.test", "etag"),
 			resource.TestCheckResourceAttrSet("data.github_membership.test", "state"),
+			resource.TestCheckResourceAttrSet("data.github_membership.test", "user_id"),
 		)
 
 		resource.Test(t, resource.TestCase{
@@ -59,4 +60,104 @@ func TestAccGithubMembershipDataSource(t *testing.T) {
 			},
 		})
 	})
+
+	t.Run("queries the membership for a user by user_id", func(t *testing.T) {
+		ctx := t.Context()
+
+		meta, err := getTestMeta()
+		if err != nil {
+			t.Fatalf("failed to get test meta: %s", err)
+		}
+
+		ghUser, _, err := meta.v3client.Users.Get(ctx, testAccConf.testOrgUser)
+		if err != nil {
+			t.Fatalf("failed to resolve org user id: %s", err)
+		}
+
+		config := fmt.Sprintf(`
+			data "github_membership" "test" {
+				user_id      = %d
+				organization = "%s"
+			}
+		`, ghUser.GetID(), testAccConf.owner)
+
+		check := resource.ComposeTestCheckFunc(
+			resource.TestCheckResourceAttr("data.github_membership.test", "username", testAccConf.testOrgUser),
+			resource.TestCheckResourceAttr("data.github_membership.test", "user_id", fmt.Sprintf("%d", ghUser.GetID())),
+			resource.TestCheckResourceAttrSet("data.github_membership.test", "role"),
+			resource.TestCheckResourceAttrSet("data.github_membership.test", "etag"),
+			resource.TestCheckResourceAttrSet("data.github_membership.test", "state"),
+		)
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessHasOrgs(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config: config,
+					Check:  check,
+				},
+			},
+		})
+	})
+
+	t.Run("errors when querying with non-existent user_id", func(t *testing.T) {
+		config := fmt.Sprintf(`
+			data "github_membership" "test" {
+				user_id      = 999999999999
+				organization = "%s"
+			}
+		`, testAccConf.owner)
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessHasOrgs(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config:      config,
+					ExpectError: regexp.MustCompile(`Not Found`),
+				},
+			},
+		})
+	})
+
+	t.Run("errors when neither username nor user_id is provided", func(t *testing.T) {
+		config := fmt.Sprintf(`
+			data "github_membership" "test" {
+				organization = "%s"
+			}
+		`, testAccConf.owner)
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessHasOrgs(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config:      config,
+					ExpectError: regexp.MustCompile(`one of (\x60username\x60,\x60user_id\x60|\x60user_id\x60,\x60username\x60) must be specified`),
+				},
+			},
+		})
+	})
+
+	t.Run("errors when both username and user_id are provided", func(t *testing.T) {
+		config := fmt.Sprintf(`
+			data "github_membership" "test" {
+				username     = "%s"
+				user_id      = 1
+				organization = "%s"
+			}
+		`, testAccConf.testOrgUser, testAccConf.owner)
+
+		resource.Test(t, resource.TestCase{
+			PreCheck:          func() { skipUnlessHasOrgs(t) },
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config:      config,
+					ExpectError: regexp.MustCompile(`only one of (\x60user_id\x60,\x60username\x60|\x60username\x60,\x60user_id\x60) can be specified`),
+				},
+			},
+		})
+	})
 }

templates/data-sources/membership.md.tmpl

@@ -12,15 +12,25 @@ Use this data source to find out if a user is a member of your organization, as
 
 {{ tffile "examples/data-sources/membership/example_1.tf" }}
 
+### Lookup by stable user ID
+
+{{ tffile "examples/data-sources/membership/example_2.tf" }}
+
 ## Argument Reference
 
-- `username` - (Required) The username to lookup in the organization.
+Exactly one of the following must be set:
+
+- `username` - (Optional) The username (login) to lookup in the organization.
+- `user_id` - (Optional) The GitHub numeric user ID. Stable across username changes; prefer this for lookups that should survive renames.
+
+Other arguments:
 
-- `organization` - (Optional) The organization to check for the above username.
+- `organization` - (Optional) The organization to check for the above user.
 
 ## Attributes Reference
 
-- `username` - The username.
+- `username` - The username (login). Always reflects the user's current login at refresh time.
+- `user_id` - The GitHub numeric user ID.
 - `role` - `admin` or `member` -- the role the user has within the organization.
 - `etag` - An etag representing the membership object.
 - `state` - `active` or `pending` -- the state of membership within the organization. `active` if the member has accepted the invite, or `pending` if the invite is still pending.