feat: detect and install permission drift if boolean is set

[zaheersufi]

Fixes #45

Summary

This PR adds an optional boolean attribute auto_accept_permission_drift (defaulting to false) to the gh-app-unofficial_installation resource. This attribute allows operators to configure how Terraform responds when a GitHub App definition updates its requested permissions on GitHub.

Default Behavior (auto_accept_permission_drift = false)

• Non-destructive and stable: Read() tracks active installed permissions in the target organization.
• Preserves installation_id: Terraform will not automatically accept permission changes upon drift.
• Requires Email / UI Approval: When an App's requested permissions change on GitHub, GitHub marks the installation as pending and sends an email notification to Organization Owners. An Organization Owner must manually review and accept the updated permission request via the GitHub UI. Once accepted, Terraform updates active permissions in the state file on the next run.

Opt-In Behavior (auto_accept_permission_drift = true)

• Automated Permission Drift Detection: ModifyPlan() queries the GitHub App definition endpoint (GET /apps/{app_slug}) to compare requested permissions against active installed permissions.
• In-Place Auto-Acceptance: When permission drift is detected, Terraform updates the resource in-place. During terraform apply, Terraform executes InstallApp to auto-accept updated permissions directly on GitHub, followed by UpdateAppInstallationRepositories to ensure repository access lists remain in sync.
• Preserves installation_id: Unlike resource replacement, in-place update preserves the existing installation_id, avoiding outages or broken references in downstream systems (such as Vault, Kubernetes secrets, or CI/CD pipelines).

Important Tradeoffs & Considerations

• Automated Consent: Setting auto_accept_permission_drift = true automatically consents to permission escalations requested by the GitHub App definition during terraform apply.

Key Changes

• Added auto_accept_permission_drift boolean attribute to the resource schema in internal/provider/installation_resource.go.
• Implemented ModifyPlan() to query client.Apps.Get(ctx, appSlug) and mark permissions, events, and updated_at as known after apply when drift is detected and auto-acceptance is enabled.
• Updated Update() to execute InstallApp (auto-accepting permissions) and UpdateAppInstallationRepositories (syncing repository selection).
• Added acceptance test coverage for auto_accept_permission_drift = true combined with repository updates in internal/provider/installation_resource_test.go.
• Updated provider documentation in docs/resources/installation.md.

[pdewilde]

I'm wondering if there is a way to change how this behaves. I don't think we want to delete and then create, as like you said that will change installation ID which seems error prone.

I know the API itself lets you just re-install in place to update the permission list, but i'm not quite sure how that would map to the terraform world.

I'm wondering if terraform is the right tool for the job, or if we would be better served with a separate permission drift detection job. The issue i see is we really should have the permissions as part of the IaC, so its explicit to approver what has chnaged. The problem is that implies the org owner can choose which permissions to apply to the installation, which isn't how the permission model works.

[zaheersufi]

I know the API itself lets you just re-install in place to update the permission list, but i'm not quite sure how that would map to the terraform world.

To my knowledge this isn't the case. You could achieve this by getting rid of the RequiresReplace attribute in ModifyPlan, which would call the Update function instead of Delete and Create. Then in the Update function you need to have a branch which checks if the permissions change. If so, then just call InstallApp. After testing this out I get the following error: Provider produced inconsistent result after apply, which means it tried to call InstallApp but that didn't fix the drift between the permissions, still would require manually accepting/uninstall and reinstall. Let me know if you were thinking of a different approach to reinstall in place.

I'm wondering if terraform is the right tool for the job, or if we would be better served with a separate permission drift detection job. The issue i see is we really should have the permissions as part of the IaC, so its explicit to approver what has chnaged. The problem is that implies the org owner can choose which permissions to apply to the installation, which isn't how the permission model works.

I agree. I think as long as there isn't a clear API to accept the permissions (without creating a brittle API to access the Web UI endpoint in a browser to click Accept), the best way might be to handle the drift out of terraform.

[zaheersufi]

Turns out instead of worrying about deletion -> reinstallation, we can just call the installation. This would accept the new permissions in place, not having to worry about generating a new installation_id. Changed to call InstallApp instead of turning on RequiresReplacement.