feat: Add downgrade_to option to github_membership resource

[galargh]

Resolves #3607

---

Before the change?

• github_membership accepted optional downgrade_on_destroy parameter
• when enabled, on destroy, if a user was an admin, their permissions were downgraded to a regular member
• if they were already a member, the resource was destroyed without modifying the user's status

After the change?

• github_membership gets a new optional downgrade_to parameter
• it defaults to member, which preserves the previous behaviour in a backwards-compatible manner
• it also accepts outside_collaborator
• when the new value is passed, an existing member is turned into an outside collaborator on destroy (i.e. their repository collaborator access is preserved where GitHub allows it)

Pull request checklist

• Schema migrations have been created if needed (example) (n/a: the proposal is backwards-compatible)
• 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?

Please see our docs on breaking changes to help!

• Yes
• No, this is a backwards-compatible change. We're not modifying the defaults.

---

Testing

Warning

TestAccGithubMembership/downgrades_organization_membership_to_outside_collaborator requires GH_TEST_EXTERNAL_USER1_TOKEN to be a Classic PAT with write:org permissions. This is because only active organisation members can be turned into outside collaborators, so the invite it issues must be accepted. Unfortunately, the fine-grained tokens do not cover organisation invitation acceptance. The newly added behaviour is also covered by unit tests, so we could remove this acceptance test case if we don't want to use a classic token here.

✅ Acceptance Tests

TestAccGithubMembership/downgrades_organization_membership_to_outside_collaborator

1. Creates member-level membership for the external user
2. Accepts the org invitation
3. Adds the user as a direct collaborator with write access to a test repo.
4. Destroys the github_membership resource
5. Asserts the user is now an outside collaborator

✅ Unit Tests

• Test_resourceGithubMembershipDelete/removes membership - asserts that destroy with downgrade_on_destroy = false is successful (uses mocks);
• Test_resourceGithubMembershipDelete/member default; asserts that destroy with downgrade_on_destroy = true is successful (uses mocks);
• Test_resourceGithubMembershipDelete/outside collaborator; asserts that destroy with downgrade_on_destroy = true and downgrade_to = outside_collaborator is successful (uses mocks);
• Test_resourceGithubMembershipDelete/outside collaborator pending invitation - asserts that destroy with downgrade_on_destroy = true and downgrade_to = outside_collaborator when the org invitation has not been accepted is NOT successful (uses mocks);
• Test_resourceGithubMembershipDelete/membership not found - asserts that destroy with downgrade_on_destroy = true and downgrade_to = outside_collaborator exits cleanly when the user is not an organisation member (uses mocks);
• Test_resourceGithubMembershipDowngradeToValidation - verifies valid downgrade_to values:
  • member
  • outside_collaborator

[github-actions]

👋 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.}