feat: support inviting organization members by email in github_membership by kazuki-hanai · Pull Request #3661 · integrations/terraform-provider-github

kazuki-hanai · 2026-10-01T05:38:43Z

Resolves #2197

Before the change?

github_membership can only address people by username (it uses EditOrgMembership), so there is no way to invite someone to the organization who does not have a GitHub account yet.

After the change?

github_membership accepts email as an alternative to username and sends an organization invitation (POST /orgs/{org}/invitations):

resource "github_membership" "invite" {
  email = "newmember@example.com"
  role  = "member"
}

The design is shaped by an API limitation: there is no endpoint to look up an invitation — or the member who later accepted it — by email. Concretely:

Create adopts an existing pending invitation for the same address, and cancels + re-sends it when the configured role differs (invitations cannot be edited). A lingering failed invitation is cancelled first, so it cannot block the new one (same motivation as [BUG] ensure failed membership invite can be deleted #3058).
Read scans pending invitations, then failed ones. A failed invitation is removed from state so it gets re-sent. If neither exists, the invitation was either accepted or cancelled externally — indistinguishable by email — so the resource stays in state instead of re-inviting an existing member on every apply. This trade-off is documented in the resource docs.
Destroy cancels the pending/failed invitation. If none exists, a warning is emitted because an invitee who already accepted keeps their organization access; from that point the membership should be managed via username.
email + downgrade_on_destroy = true is rejected at plan time (ConflictsWith cannot express this because an explicit downgrade_on_destroy = false would also trigger it).

Relation to #3464: that PR proposes a separate github_organization_invitation resource. This PR instead extends the existing resource, which is what #2197 asks for and follows the review guidance there that additions to existing resources are preferred over new resources.

Testing

Unit tests, go build, go vet, and both golangci-lint configs (default and strict-on-new-code) pass; docs regenerated with make generatedocs.
Added an acceptance test gated on a new GH_TEST_INVITATION_EMAIL env var (the address must not belong to an existing org member). I have not yet run the acceptance tests against a real organization.

Per the contributing guidelines: this PR was largely generated with an AI assistant (Claude Code), driven and reviewed iteratively by me.

Pull request checklist

Schema migrations have been created if needed — not applicable
Tests for the changes have been added (for bug fixes / features)
Docs have been reviewed and added / updated if needed (for bug fixes / features)

Does this introduce a breaking change?

Yes
No

username changes from Required to Optional with ExactlyOneOf, which keeps all existing configurations valid.

🤖 Generated with Claude Code

…ship GitHub's membership API (EditOrgMembership) can only address people by username, so github_membership could not invite someone who does not have a GitHub account yet. Add an 'email' argument that uses the organization invitation API (CreateOrgInvitation) instead. Because there is no endpoint to look up an invitation (or the resulting member) by email, the email flavour of the resource manages the invitation lifecycle: pending invitations are adopted, cancelled on destroy (including failed invitations), and re-sent when the role changes. Once an invitation is accepted the resource keeps it in state rather than re-inviting an existing member on every apply. Closes integrations#2197 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-10-01T05:38:53Z

👋 Hi, and thank you for this contribution!

This repo is maintained by GitHub and community members on a best-effort basis. We'll get to this as soon as we can.

You can help us prioritize by joining the discussion on open issues and PRs, sharing details on the changes you need, and reviewing other contributions.

_{🤖 This is an automated message.}

deiga · 2026-10-11T14:27:27Z

Duplicate of #3229

kazuki-hanai · 2026-10-14T03:54:29Z

Thanks for the triage @deiga. I understand this addresses the same issue, but I would like to ask you to reconsider which PR to keep:

feat: add org invite resource #3229 has had no activity since your review in February (8 months now), and it predates the docs migration (it still edits website/docs/), so it would need significant rework to be mergeable. feat: add github_organization_invitation resource #3464 is currently a draft.
This PR is up to date (go-github v92, current docs layout), extends the existing github_membership resource as [FEAT]: github_membership invite using the email address #2197 literally asks for, and follows your guidance in feat: add github_organization_invitation resource #3464 that additions to existing resources are more likely to be merged than new resources.

Given that, closing the stalled PR and keeping this one open seems like the better outcome for #2197. I put real effort into this implementation and I am motivated to address review feedback quickly, so I would appreciate the chance to get it reviewed. If the team has firmly settled on the separate-resource approach instead, let me know and I will help review #3229.

deiga · 2026-10-14T11:02:45Z

@kazuki-hanai I think you raise an excellent point. And while I can't promise how quickly we can get your change merged, I'll re-open this and mark the others as stale

Copilot

🟡 Changes recommended

Core invitation update, adoption, and failed-invitation reconciliation paths lack test coverage.

1 open finding

Add acceptance tests for invitation updates and reconciliation · New

What changed in this PR

These provider review instructions are being used. This PR extends github_membership to manage organization invitations by email.

Changes:

Adds email-based invitation lifecycle handling.
Adds schema validation, documentation, and examples.
Adds acceptance coverage for creation, import, and deletion.

File	Description
`github/resource_github_membership.go`	Implements email invitation lifecycle.
`github/resource_github_membership_test.go`	Adds invitation tests.
`github/acc_test.go`	Adds invitation email configuration.
`examples/resources/membership/example_2.tf`	Demonstrates email invitations.
`templates/resources/membership.md.tmpl`	Documents the new behavior.
`docs/resources/membership.md`	Regenerates user-facing documentation.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+			Steps: []resource.TestStep{
+				{
+					Config: testAccGithubMembershipConfigEmail(testAccConf.testInvitationEmail),
+					Check: resource.ComposeTestCheckFunc(
+						resource.TestCheckResourceAttr(rn, "email", testAccConf.testInvitationEmail),


deiga

Partial review

deiga · 2026-10-14T11:07:18Z

+	// Inviting an email that already has a pending invitation fails, so adopt
+	// an existing pending invitation when it matches the configured role.
+	invitation, err := findPendingOrgInvitationByEmail(ctx, owner, email)
+	if err != nil {
+		return diag.FromErr(err)
+	}
+
+	if invitation != nil && invitationRoleToMembershipRole(invitation.GetRole()) != roleName {
+		if _, err := owner.v3client.Organizations.CancelInvite(ctx, orgName, invitation.GetID()); err != nil {
+			return diag.FromErr(err)
+		}
+		invitation = nil
+	}


issue: This sounds like something that should be left to the user with an import statement and not part of Create 🤔

Done in 3741f90. Create now just sends the invitation; a pre-existing invitation surfaces the API error, which points the user at terraform import. Cancel-and-reinvite only runs on role updates, since invitations cannot be edited.

deiga · 2026-10-14T11:10:16Z

-	orgName := meta.(*Owner).name
-	_, username, err := parseID2(d.Id())
+	orgName := owner.name
+	_, usernameOrEmail, err := parseID2(d.Id())


issue: lets not parse the ID, but instead d.Get from the attributes

Done in 7d52b47. Read now dispatches on d.Get("email"). To keep imports working, a custom importer maps an email-shaped import ID onto the email attribute, so ID parsing stays confined to the importer.

deiga · 2026-10-14T11:11:57Z

 	})
 }

+func TestAccGithubMembershipEmailInvitation(t *testing.T) {


issue: Add tests as subtests of the one existing test

Done in 5429008. The email test is now a subtest of TestAccGithubMembership, and it gained a role-change step covering the update path.

deiga · 2026-10-14T11:13:19Z

 ## Example Usage

 {{ tffile "examples/resources/membership/example_1.tf" }}

+Inviting by email address:
+
+{{ tffile "examples/resources/membership/example_2.tf" }}
+


suggestion: Could you update this to use the auto-discovery of example files?

Done in d69b9e9. The template now uses .ExampleFiles, and the example files moved to examples/resources/github_membership/resource_*.tf to match the discovery convention.

kazuki-hanai · 2026-10-14T12:52:36Z

Thank you for reopening this and for the quick review, @deiga! I will address the feedback shortly.

kazuki-hanai · 2026-10-14T14:01:21Z

All review feedback addressed, split into one commit per review point (3741f90, 7d52b47, 5429008, d69b9e9). See the reply on each review thread for details.

Create now just sends the invitation; a pre-existing invitation surfaces the API error and points the user at terraform import. Cancelling and re-inviting only happens on role updates, since invitations cannot be edited. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A custom importer maps an email-shaped import ID onto the email attribute, so ID parsing stays confined to the importer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Also add a role-change step covering the cancel-and-reinvite update path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Example files move to examples/resources/github_membership/resource_*.tf to match the tfplugindocs discovery convention. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…membership

kazuki-hanai mentioned this pull request Oct 5, 2026

[FEAT]: github_membership invite using the email address #2197

Open

1 task done

deiga marked this as a duplicate of #3229 Oct 11, 2026

deiga closed this Oct 11, 2026

deiga reopened this Oct 14, 2026

This was referenced Oct 14, 2026

feat: add github_organization_invitation resource #3464

Closed

feat: add org invite resource #3229

Closed

deiga added Type: Feature New feature or request r/membership labels Oct 14, 2026

deiga requested a balanced review from Copilot October 14, 2026 11:04

Copilot started reviewing on behalf of deiga October 14, 2026 11:04

View session

Copilot AI reviewed Oct 14, 2026

View reviewed changes

deiga requested changes Oct 14, 2026

View reviewed changes

kazuki-hanai and others added 4 commits October 14, 2026 23:07

fix: dispatch read on the email attribute instead of parsing the ID

7d52b47

A custom importer maps an email-shaped import ID onto the email attribute, so ID parsing stays confined to the importer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test: fold the email invitation test into TestAccGithubMembership

5429008

Also add a role-change step covering the cancel-and-reinvite update path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: use example auto-discovery in the membership template

d69b9e9

Example files move to examples/resources/github_membership/resource_*.tf to match the tfplugindocs discovery convention. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

kazuki-hanai force-pushed the kazuki-hanai/Add-email-invitation-to-github_membership branch from aaae5d9 to d69b9e9 Compare October 14, 2026 14:14

kazuki-hanai requested a review from deiga October 14, 2026 14:50

Merge branch 'main' into kazuki-hanai/Add-email-invitation-to-github_…

664297d

…membership

Conversation

kazuki-hanai commented Oct 1, 2026

Before the change?

After the change?

Testing

Pull request checklist

Does this introduce a breaking change?

Uh oh!

github-actions Bot commented Oct 1, 2026

Uh oh!

deiga commented Oct 11, 2026

Uh oh!

kazuki-hanai commented Oct 14, 2026

Uh oh!

deiga commented Oct 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

deiga left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kazuki-hanai commented Oct 14, 2026

Uh oh!

kazuki-hanai commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kazuki-hanai commented Oct 14, 2026 •

edited

Loading