Skip to content

Commit f4e8836

Browse files
nickfloydnickfloyd
authored
feat: Adds enterprise settings resources to the provider (#2852)
* Adds enterprise settings resources to the provider * Adds example * Updates tests for better coverage * Register the resource * go fmt * adds example readme and docs * breaks up the resources following a 1 to 1 pattern that more closely aligns with the API resource structure * breaks up the resources following a 1 to 1 pattern that more closely aligns with the API resource structure * Adds test coverage for ent securtiy settings * Apply suggestion from @nickfloyd
1 parent b599ebb commit f4e8836

10 files changed

+1202
-0
lines changed

‎examples/enterprise_settings/README.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# GitHub Enterprise Settings Example
2+
3+
This example demonstrates how to configure GitHub Enterprise settings using the Terraform GitHub provider.
4+
5+
## Overview
6+
7+
Manage enterprise-level GitHub Actions settings with focused, composable resources:
8+
9+
- **Actions Permissions**: Control which organizations can use GitHub Actions and what actions are allowed
10+
- **Workflow Permissions**: Manage default GITHUB_TOKEN permissions and pull request review settings
11+
12+
## Requirements
13+
14+
- GitHub Enterprise account
15+
- Personal access token with enterprise admin permissions
16+
- Terraform >= 0.14
17+
18+
## Usage
19+
20+
1. Set your environment variables:
21+
22+
```bash
23+
export TF_VAR_github_token="your_github_token"
24+
export TF_VAR_enterprise_slug="your-enterprise-slug"
25+
```
26+
27+
2. Initialize and apply:
28+
29+
```bash
30+
terraform init
31+
terraform plan
32+
terraform apply
33+
```
34+
35+
## Configuration Examples
36+
37+
### Basic Configuration - Allow All Actions
38+
39+
```terraform
40+
# Allow all actions for all organizations
41+
resource "github_enterprise_actions_permissions" "basic" {
42+
enterprise_slug = "my-enterprise"
43+
44+
enabled_organizations = "all"
45+
allowed_actions = "all"
46+
}
47+
48+
# Use restrictive workflow permissions
49+
resource "github_enterprise_actions_workflow_permissions" "basic" {
50+
enterprise_slug = "my-enterprise"
51+
52+
default_workflow_permissions = "read"
53+
can_approve_pull_request_reviews = false
54+
}
55+
```
56+
57+
### Advanced Configuration - Selective Permissions
58+
59+
```terraform
60+
# Selective actions and organizations
61+
resource "github_enterprise_actions_permissions" "advanced" {
62+
enterprise_slug = "my-enterprise"
63+
64+
enabled_organizations = "selected"
65+
allowed_actions = "selected"
66+
67+
allowed_actions_config {
68+
github_owned_allowed = true
69+
verified_allowed = true
70+
patterns_allowed = [
71+
"actions/cache@*",
72+
"actions/checkout@*",
73+
"my-org/custom-action@v1"
74+
]
75+
}
76+
77+
enabled_organizations_config {
78+
organization_ids = [123456, 789012] # Replace with actual org IDs
79+
}
80+
}
81+
82+
# More permissive workflow settings
83+
resource "github_enterprise_actions_workflow_permissions" "advanced" {
84+
enterprise_slug = "my-enterprise"
85+
86+
default_workflow_permissions = "write"
87+
can_approve_pull_request_reviews = true
88+
}
89+
```
90+
91+
## Available Enterprise Resources
92+
93+
### Actions & Workflow Management
94+
- **`github_enterprise_actions_permissions`** - Controls which organizations can use GitHub Actions and which actions are allowed to run
95+
- **`github_enterprise_actions_workflow_permissions`** - Manages default GITHUB_TOKEN permissions and whether GitHub Actions can approve pull requests
96+
97+
### Security & Analysis
98+
- **`github_enterprise_security_analysis_settings`** - Manages Advanced Security, secret scanning, and code analysis features for new repositories
99+
100+
### Additional Resources (Available)
101+
- **`github_enterprise_actions_runner_group`** - Manages enterprise-level runner groups for GitHub Actions
102+
103+
## Security Recommendations
104+
105+
1. Use `"read"` workflow permissions by default
106+
2. Disable pull request review approvals for security
107+
3. Use `"selected"` actions policy to limit which actions can run
108+
4. Store tokens securely using environment variables
109+
110+
## Configuration Reference
111+
112+
### Actions Settings
113+
114+
- **`actions_enabled_organizations`**: Controls which organizations can run GitHub Actions
115+
- `"all"` - All organizations in the enterprise
116+
- `"none"` - No organizations
117+
- `"selected"` - Only specified organizations (requires additional configuration)
118+
119+
- **`actions_allowed_actions`**: Controls which actions can be run
120+
- `"all"` - All actions and reusable workflows
121+
- `"local_only"` - Only actions and workflows in the same repository/organization
122+
- `"selected"` - Only specified actions (requires additional configuration)
123+
124+
When `actions_allowed_actions` is set to `"selected"`, you can specify:
125+
126+
- **`actions_github_owned_allowed`**: Allow GitHub-owned actions (e.g., `actions/checkout`)
127+
- **`actions_verified_allowed`**: Allow verified Marketplace actions
128+
- **`actions_patterns_allowed`**: List of specific action patterns to allow
129+
130+
### Workflow Settings
131+
132+
- **`default_workflow_permissions`**: Default permissions for the GITHUB_TOKEN
133+
- `"read"` - Read-only permissions (recommended for security)
134+
- `"write"` - Read and write permissions
135+
136+
- **`can_approve_pull_request_reviews`**: Whether GitHub Actions can approve pull request reviews
137+
- `true` - Actions can approve PR reviews
138+
- `false` - Actions cannot approve PR reviews (recommended for security)
139+
140+
## Security Considerations
141+
142+
1. **Workflow Permissions**: Use `"read"` permissions by default and grant `"write"` only when necessary
143+
2. **PR Approvals**: Disable `can_approve_pull_request_reviews` to prevent automated approval bypasses
144+
3. **Action Restrictions**: Use `"selected"` for `actions_allowed_actions` to limit which actions can run
145+
4. **Token Security**: Store your GitHub token securely and use environment variables
146+
147+
## Limitations
148+
149+
This resource currently supports a subset of enterprise settings available through the GitHub API. Additional settings like fork PR workflows, artifact retention, and self-hosted runner permissions are not yet supported by the go-github version used in this provider and will be added in future versions.
150+
151+
## Import
152+
153+
You can import existing enterprise settings:
154+
155+
```bash
156+
terraform import github_enterprise_settings.example my-enterprise
157+
```
158+
159+
## Troubleshooting
160+
161+
### Common Issues
162+
163+
1. **Authentication**: Ensure your token has enterprise admin permissions
164+
2. **Enterprise Access**: Verify you have access to the specified enterprise
165+
3. **API Limits**: GitHub API has rate limits; consider adding delays for large configurations
166+
167+
### Verification
168+
169+
After applying, verify settings in the GitHub Enterprise dashboard:
170+
1. Go to your enterprise settings
171+
2. Navigate to "Policies" > "Actions"
172+
3. Check that the configured settings match your Terraform configuration

‎examples/enterprise_settings/main.tf‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
terraform {
2+
required_providers {
3+
github = {
4+
source = "integrations/github"
5+
version = "~> 6.0"
6+
}
7+
}
8+
}
9+
10+
provider "github" {
11+
token = var.github_token
12+
}
13+
14+
variable "github_token" {
15+
description = "GitHub personal access token with enterprise admin permissions"
16+
type = string
17+
sensitive = true
18+
}
19+
20+
variable "enterprise_slug" {
21+
description = "The GitHub Enterprise slug"
22+
type = string
23+
}
24+
25+
# Basic Enterprise Actions Permissions - Allow all actions for all organizations
26+
resource "github_enterprise_actions_permissions" "basic" {
27+
enterprise_slug = var.enterprise_slug
28+
29+
enabled_organizations = "all"
30+
allowed_actions = "all"
31+
}
32+
33+
# Basic Enterprise Workflow Permissions - Restrictive settings
34+
resource "github_enterprise_actions_workflow_permissions" "basic" {
35+
enterprise_slug = var.enterprise_slug
36+
37+
default_workflow_permissions = "read"
38+
can_approve_pull_request_reviews = false
39+
}
40+
41+
# Advanced Enterprise Actions Permissions - Selective configuration
42+
resource "github_enterprise_actions_permissions" "advanced" {
43+
enterprise_slug = var.enterprise_slug
44+
45+
enabled_organizations = "selected"
46+
allowed_actions = "selected"
47+
48+
# Configure allowed actions when "selected" policy is used
49+
allowed_actions_config {
50+
github_owned_allowed = true
51+
verified_allowed = true
52+
patterns_allowed = [
53+
"actions/cache@*",
54+
"actions/checkout@*",
55+
"actions/setup-node@*",
56+
"actions/setup-python@*",
57+
"actions/upload-artifact@*",
58+
"actions/download-artifact@*",
59+
"my-org/custom-action@v1"
60+
]
61+
}
62+
63+
# Configure enabled organizations when "selected" policy is used
64+
enabled_organizations_config {
65+
organization_ids = [123456, 789012] # Replace with actual org IDs
66+
}
67+
}
68+
69+
# Advanced Enterprise Workflow Permissions - Permissive settings
70+
resource "github_enterprise_actions_workflow_permissions" "advanced" {
71+
enterprise_slug = var.enterprise_slug
72+
73+
default_workflow_permissions = "write"
74+
can_approve_pull_request_reviews = true
75+
}
76+
77+
# Security Analysis Settings - Enable security features for new repositories
78+
resource "github_enterprise_security_analysis_settings" "example" {
79+
enterprise_slug = var.enterprise_slug
80+
81+
advanced_security_enabled_for_new_repositories = true
82+
secret_scanning_enabled_for_new_repositories = true
83+
secret_scanning_push_protection_enabled_for_new_repositories = true
84+
secret_scanning_validity_checks_enabled = true
85+
secret_scanning_push_protection_custom_link = "https://octokit.com/security-help"
86+
}
87+
88+
output "basic_enterprise_actions" {
89+
description = "Basic enterprise actions permissions configuration"
90+
value = {
91+
enterprise_slug = github_enterprise_actions_permissions.basic.enterprise_slug
92+
enabled_organizations = github_enterprise_actions_permissions.basic.enabled_organizations
93+
allowed_actions = github_enterprise_actions_permissions.basic.allowed_actions
94+
}
95+
}
96+
97+
output "basic_enterprise_workflow" {
98+
description = "Basic enterprise workflow permissions configuration"
99+
value = {
100+
enterprise_slug = github_enterprise_actions_workflow_permissions.basic.enterprise_slug
101+
default_workflow_permissions = github_enterprise_actions_workflow_permissions.basic.default_workflow_permissions
102+
can_approve_pull_request_reviews = github_enterprise_actions_workflow_permissions.basic.can_approve_pull_request_reviews
103+
}
104+
}
105+
106+
output "advanced_enterprise_actions" {
107+
description = "Advanced enterprise actions permissions configuration"
108+
value = {
109+
enterprise_slug = github_enterprise_actions_permissions.advanced.enterprise_slug
110+
enabled_organizations = github_enterprise_actions_permissions.advanced.enabled_organizations
111+
allowed_actions = github_enterprise_actions_permissions.advanced.allowed_actions
112+
}
113+
}
114+
115+
output "advanced_enterprise_workflow" {
116+
description = "Advanced enterprise workflow permissions configuration"
117+
value = {
118+
enterprise_slug = github_enterprise_actions_workflow_permissions.advanced.enterprise_slug
119+
default_workflow_permissions = github_enterprise_actions_workflow_permissions.advanced.default_workflow_permissions
120+
can_approve_pull_request_reviews = github_enterprise_actions_workflow_permissions.advanced.can_approve_pull_request_reviews
121+
}
122+
}

‎github/provider.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,8 @@ func Provider() *schema.Provider {
209209
"github_user_ssh_key": resourceGithubUserSshKey(),
210210
"github_enterprise_organization": resourceGithubEnterpriseOrganization(),
211211
"github_enterprise_actions_runner_group": resourceGithubActionsEnterpriseRunnerGroup(),
212+
"github_enterprise_actions_workflow_permissions": resourceGithubEnterpriseActionsWorkflowPermissions(),
213+
"github_enterprise_security_analysis_settings": resourceGithubEnterpriseSecurityAnalysisSettings(),
212214
"github_workflow_repository_permissions": resourceGithubWorkflowRepositoryPermissions(),
213215
},
214216

0 commit comments

Comments
 (0)