feat: Add github_enterprise_app_installation resource

.github/workflows/acceptance-tests.yaml

@@ -216,6 +216,7 @@ jobs:
           GITHUB_BASE_URL: https://api.github.com/
           GITHUB_OWNER: ${{ case(matrix.mode == 'anonymous', '', matrix.mode == 'individual', vars.GH_TEST_LOGIN, vars.GH_TEST_ORG_NAME) }}
           GITHUB_ENTERPRISE_SLUG: ${{ case(matrix.mode == 'enterprise', vars.GH_TEST_ENTERPRISE_SLUG, '') }}
+          GH_TEST_ENTERPRISE_APP_CLIENT_ID: ${{ vars.GH_TEST_ENTERPRISE_APP_CLIENT_ID }}
           GITHUB_LEGACY_CLIENT: "false"
           GH_TEST_AUTH_MODE: ${{ matrix.mode }}
           GH_TEST_ORG_USER1: ${{ vars.GH_TEST_ORG_USER1 }}

RESOURCES.md

@@ -69,6 +69,9 @@ The overall status of each resource or data source is captured in this document
 | `github_dependabot_public_key` | ⚠️ | ✅ | ❓ | ❓ | ❓ | ❓ |
 | `github_dependabot_secrets` | ⚠️ | ✅ | ❓ | ❓ | ❓ | ❓ |
 | `github_enterprise` | ⚠️ | ✅ | ❓ | ❓ | ❓ | ❓ |
+| `github_enterprise_app_installable_organizations` | ✅ | ✅ | ✅ | ✅ | ❓ | ✅ |
+| `github_enterprise_organization_app_accessible_repositories` | ✅ | ✅ | ✅ | ✅ | ❓ | ✅ |
+| `github_enterprise_organization_app_installations` | ✅ | ✅ | ✅ | ✅ | ❓ | ✅ |
 | `github_external_groups` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `github_ip_ranges` | ⚠️ | ✅ | ❓ | ❓ | ❓ | ❓ |
 | `github_issue_labels` | ⚠️ | ✅ | ❓ | ❓ | ❓ | ❓ |
@@ -162,6 +165,7 @@ The overall status of each resource or data source is captured in this document
 | `github_enterprise_actions_workflow_permissions` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
 | `github_enterprise_ip_allow_list_entry` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
 | `github_enterprise_organization` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
+| `github_enterprise_organization_app_installation` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
 | `github_enterprise_security_analysis_settings` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
 | `github_issue` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
 | `github_issue_label` | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |

docs/data-sources/enterprise_app_installable_organizations.md

@@ -0,0 +1,39 @@
+---
+page_title: "github_enterprise_app_installable_organizations (Data Source) - GitHub"
+subcategory: ""
+description: |-
+  Use this data source to retrieve the enterprise-owned organizations that GitHub Apps can be installed on. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+---
+
+# github_enterprise_app_installable_organizations (Data Source)
+
+Use this data source to retrieve the enterprise-owned organizations that GitHub Apps can be installed on. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+
+## Example Usage
+
+```terraform
+data "github_enterprise_app_installable_organizations" "example" {
+  enterprise_slug = "my-enterprise"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `enterprise_slug` (String) The slug of the enterprise.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `organizations` (List of Object) List of organizations in the enterprise that GitHub Apps can be installed on. (see [below for nested schema](#nestedatt--organizations))
+
+<a id="nestedatt--organizations"></a>
+### Nested Schema for `organizations`
+
+Read-Only:
+
+- `accessible_repositories_url` (String)
+- `id` (Number)
+- `login` (String)

docs/data-sources/enterprise_organization_app_accessible_repositories.md

@@ -0,0 +1,41 @@
+---
+page_title: "github_enterprise_organization_app_accessible_repositories (Data Source) - GitHub"
+subcategory: ""
+description: |-
+  Use this data source to retrieve the repositories of an enterprise-owned organization that GitHub Apps can be granted access to. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+---
+
+# github_enterprise_organization_app_accessible_repositories (Data Source)
+
+Use this data source to retrieve the repositories of an enterprise-owned organization that GitHub Apps can be granted access to. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+
+## Example Usage
+
+```terraform
+data "github_enterprise_organization_app_accessible_repositories" "example" {
+  enterprise_slug = "my-enterprise"
+  organization    = "my-org"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `enterprise_slug` (String) The slug of the enterprise that owns the organization.
+- `organization` (String) The login of the enterprise-owned organization.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `repositories` (List of Object) List of repositories of the organization that GitHub Apps can be granted access to. (see [below for nested schema](#nestedatt--repositories))
+
+<a id="nestedatt--repositories"></a>
+### Nested Schema for `repositories`
+
+Read-Only:
+
+- `full_name` (String)
+- `id` (Number)
+- `name` (String)

docs/data-sources/enterprise_organization_app_installations.md

@@ -0,0 +1,51 @@
+---
+page_title: "github_enterprise_organization_app_installations (Data Source) - GitHub"
+subcategory: ""
+description: |-
+  Use this data source to retrieve the GitHub App installations on an enterprise-owned organization. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+---
+
+# github_enterprise_organization_app_installations (Data Source)
+
+Use this data source to retrieve the GitHub App installations on an enterprise-owned organization. This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+
+## Example Usage
+
+```terraform
+data "github_enterprise_organization_app_installations" "example" {
+  enterprise_slug = "my-enterprise"
+  organization    = "my-org"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `enterprise_slug` (String) The slug of the enterprise that owns the organization.
+- `organization` (String) The login of the enterprise-owned organization.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `installations` (List of Object) List of GitHub App installations on the organization. (see [below for nested schema](#nestedatt--installations))
+
+<a id="nestedatt--installations"></a>
+### Nested Schema for `installations`
+
+Read-Only:
+
+- `app_id` (Number)
+- `app_slug` (String)
+- `client_id` (String)
+- `created_at` (String)
+- `events` (List of String)
+- `id` (Number)
+- `permissions` (Map of String)
+- `repository_selection` (String)
+- `single_file_paths` (List of String)
+- `suspended` (Boolean)
+- `target_id` (Number)
+- `target_type` (String)
+- `updated_at` (String)

docs/resources/enterprise_organization_app_installation.md

@@ -0,0 +1,59 @@
+---
+page_title: "github_enterprise_organization_app_installation (Resource) - GitHub"
+subcategory: ""
+description: |-
+  Manage the installation of a GitHub App on an organization owned by an enterprise. The app is installed on the organization, not on the enterprise account itself; GitHub offers no API for the latter. This resource requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+---
+
+# github_enterprise_organization_app_installation (Resource)
+
+Manage the installation of a GitHub App on an organization owned by an enterprise. The app is installed on the organization, not on the enterprise account itself; GitHub offers no API for the latter. This resource requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.
+
+## Example Usage
+
+```terraform
+resource "github_enterprise_organization_app_installation" "all_repos" {
+  enterprise_slug      = "my-enterprise"
+  organization         = "my-org"
+  client_id            = "Iv1.abc123def456"
+  repository_selection = "all"
+}
+
+resource "github_enterprise_organization_app_installation" "selected_repos" {
+  enterprise_slug       = "my-enterprise"
+  organization          = "my-org"
+  client_id             = "Iv1.789ghi012jkl"
+  repository_selection  = "selected"
+  selected_repositories = ["my-repo-1", "my-repo-2"]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `client_id` (String) The client ID of the GitHub App to install.
+- `enterprise_slug` (String) The slug of the enterprise that owns the organization.
+- `organization` (String) The login of the enterprise-owned organization to install the app on.
+- `repository_selection` (String) The repositories the installation can access. Can be one of 'all', 'selected' or 'none'.
+
+### Optional
+
+- `selected_repositories` (Set of String) The names of the repositories the installation can access when 'repository_selection' is 'selected'.
+
+### Read-Only
+
+- `app_slug` (String) The slug of the installed app.
+- `id` (String) The ID of this resource.
+- `installation_id` (String) The ID of the installation.
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+terraform import github_enterprise_organization_app_installation.all_repos my-enterprise:my-org:Iv1.abc123def456
+```

examples/data-sources/github_enterprise_app_installable_organizations/data-source_1.tf

@@ -0,0 +1,3 @@
+data "github_enterprise_app_installable_organizations" "example" {
+  enterprise_slug = "my-enterprise"
+}

examples/data-sources/github_enterprise_organization_app_accessible_repositories/data-source_1.tf

@@ -0,0 +1,4 @@
+data "github_enterprise_organization_app_accessible_repositories" "example" {
+  enterprise_slug = "my-enterprise"
+  organization    = "my-org"
+}

examples/data-sources/github_enterprise_organization_app_installations/data-source_1.tf

@@ -0,0 +1,4 @@
+data "github_enterprise_organization_app_installations" "example" {
+  enterprise_slug = "my-enterprise"
+  organization    = "my-org"
+}

examples/resources/github_enterprise_organization_app_installation/import.sh

@@ -0,0 +1 @@
+terraform import github_enterprise_organization_app_installation.all_repos my-enterprise:my-org:Iv1.abc123def456

examples/resources/github_enterprise_organization_app_installation/resource.tf

@@ -0,0 +1,14 @@
+resource "github_enterprise_organization_app_installation" "all_repos" {
+  enterprise_slug      = "my-enterprise"
+  organization         = "my-org"
+  client_id            = "Iv1.abc123def456"
+  repository_selection = "all"
+}
+
+resource "github_enterprise_organization_app_installation" "selected_repos" {
+  enterprise_slug       = "my-enterprise"
+  organization          = "my-org"
+  client_id             = "Iv1.789ghi012jkl"
+  repository_selection  = "selected"
+  selected_repositories = ["my-repo-1", "my-repo-2"]
+}

github/data_source_github_enterprise_app_installable_organizations.go

@@ -0,0 +1,80 @@
+package github
+
+import (
+	"context"
+
+	"github.com/google/go-github/v89/github"
+	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
+	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
+)
+
+func dataSourceGithubEnterpriseAppInstallableOrganizations() *schema.Resource {
+	return &schema.Resource{
+		ReadContext: dataSourceGithubEnterpriseAppInstallableOrganizationsRead,
+		Description: "Use this data source to retrieve the enterprise-owned organizations that GitHub Apps can be installed on. " +
+			"This data source requires GitHub Enterprise Cloud or GitHub Enterprise Server 3.19+ and an authenticated user that is an enterprise owner.",
+
+		Schema: map[string]*schema.Schema{
+			"enterprise_slug": {
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The slug of the enterprise.",
+			},
+			"organizations": {
+				Type:        schema.TypeList,
+				Computed:    true,
+				Description: "List of organizations in the enterprise that GitHub Apps can be installed on.",
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"id": {
+							Type:        schema.TypeInt,
+							Computed:    true,
+							Description: "The ID of the organization.",
+						},
+						"login": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "The login of the organization.",
+						},
+						"accessible_repositories_url": {
+							Type:        schema.TypeString,
+							Computed:    true,
+							Description: "The API URL listing the repositories that can be made accessible to a GitHub App installed on the organization.",
+						},
+					},
+				},
+			},
+		},
+	}
+}
+
+func dataSourceGithubEnterpriseAppInstallableOrganizationsRead(ctx context.Context, d *schema.ResourceData, m any) diag.Diagnostics {
+	meta, _ := m.(*Owner)
+	client := meta.v3client
+
+	enterpriseSlug := d.Get("enterprise_slug").(string)
+
+	opts := &github.ListOptions{
+		PerPage: meta.maxPerPage,
+	}
+
+	results := make([]map[string]any, 0)
+	for organization, err := range client.Enterprise.ListAppInstallableOrganizationsIter(ctx, enterpriseSlug, opts) {
+		if err != nil {
+			return diag.FromErr(err)
+		}
+
+		results = append(results, map[string]any{
+			"id":                          organization.ID,
+			"login":                       organization.Login,
+			"accessible_repositories_url": organization.GetAccessibleRepositoriesURL(),
+		})
+	}
+
+	d.SetId(enterpriseSlug)
+	if err := d.Set("organizations", results); err != nil {
+		return diag.FromErr(err)
+	}
+
+	return nil
+}

github/data_source_github_enterprise_app_installable_organizations_test.go

@@ -0,0 +1,43 @@
+package github
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
+	"github.com/hashicorp/terraform-plugin-testing/statecheck"
+	"github.com/hashicorp/terraform-plugin-testing/tfjsonpath"
+)
+
+func TestAccDataSourceGithubEnterpriseAppInstallableOrganizations(t *testing.T) {
+	t.Parallel()
+
+	skipUnlessEnterprise(t)
+
+	t.Run("queries_installable_organizations", func(t *testing.T) {
+		t.Parallel()
+
+		config := fmt.Sprintf(`
+data "github_enterprise_app_installable_organizations" "test" {
+  enterprise_slug = "%s"
+}
+`, testAccConf.enterpriseSlug)
+
+		resource.Test(t, resource.TestCase{
+			ProviderFactories: providerFactories,
+			Steps: []resource.TestStep{
+				{
+					Config: config,
+					ConfigStateChecks: []statecheck.StateCheck{
+						statecheck.ExpectKnownValue("data.github_enterprise_app_installable_organizations.test", tfjsonpath.New("organizations"), knownvalue.SetPartial([]knownvalue.Check{
+							knownvalue.MapPartial(map[string]knownvalue.Check{
+								"login": knownvalue.StringExact(testAccConf.owner),
+							}),
+						})),
+					},
+				},
+			},
+		})
+	})
+}