terraform-spaceship-github-pages

A Terraform/OpenTofu module to provision a GitHub repository with GitHub Pages enabled, and to configure the necessary DNS A and CNAME records using the Spaceship provider.

Features

• Creates a new GitHub repository with an initial commit.
• Automatically enables GitHub Pages on the master branch.
• Sets the repository's custom domain to your desired domain name.
• Connects to the spaceship provider and creates the 4 standard GitHub Pages A records and the www CNAME record for the domain.

Warning

GitHub Pages requires the repository to be public for GitHub Free accounts. According to the official documentation, "GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise." Keep this in mind since the default repository_settings.visibility is set to "private"! For personal use on a free GitHub account, you need to set the repository_settings.visibility to "public"!

Provider Bug #3450 Workaround: Due to a known bug in the GitHub Terraform Provider, the cname and https_enforced settings cannot be reliably managed by the github_repository_pages resource. This module uses a null_resource with a local-exec provisioner to configure these settings via the GitHub REST API. This workaround has specific requirements:

• System Dependencies: You must have bash, curl, and jq installed on the system where Terraform is executed.

Authentication

This module requires authentication with both GitHub and Spaceship:

1. GitHub: You must set the GITHUB_TOKEN environment variable. While Terraform can authenticate using the GitHub CLI (gh auth login), the local-exec provisioner script used for the GitHub Pages workaround requires the GITHUB_TOKEN environment variable to be explicitly set to interact directly with the GitHub API.
   • Note for Deletion: If you plan to destroy the repository using Terraform, you must have the delete_repo scope on your token.
2. Spaceship: You must provide your Spaceship API credentials by setting the SPACESHIP_API_KEY and SPACESHIP_API_SECRET environment variables.

Usage Example

module "spaceship_github_pages" {
  source = "../"

  domain = "example-test.com"
  name   = "example-test-repo"
}

See the examples/ directory for more use cases.

Requirements

Name	Version
terraform	1.15.6
github	~> 6.0
null	~> 3.0
spaceship	>= 0.4.1
time	~> 0.12

Providers

Name	Version
github	6.12.1
null	3.3.0
spaceship	0.5.1

Modules

No modules.

Resources

Name	Type
github_branch_default.this	resource
github_branch_protection.this	resource
github_repository.this	resource
github_repository_pages.this	resource
null_resource.configure_cname_enforce_https	resource
spaceship_dns_records.this	resource
github_user.current	data source

Inputs

Name	Description	Type	Default	Required
branch_protection	Settings for the GitHub branch protection	object({ pattern = optional(string) enforce_admins = optional(bool, true) require_signed_commits = optional(bool, true) required_linear_history = optional(bool, true) require_conversation_resolution = optional(bool, true) allows_deletions = optional(bool, false) allows_force_pushes = optional(bool, false) lock_branch = optional(bool, false) force_push_bypassers = optional(list(string), []) required_status_checks = optional(object({ strict = optional(bool, true) contexts = optional(list(string), []) })) required_pull_request_reviews = optional(object({ dismiss_stale_reviews = optional(bool, true) restrict_dismissals = optional(bool, true) dismissal_restrictions = optional(list(string), []) pull_request_bypassers = optional(list(string), []) require_code_owner_reviews = optional(bool, true) required_approving_review_count = optional(number, 2) require_last_push_approval = optional(bool, false) }), {}) restrict_pushes = optional(object({ blocks_creations = optional(bool, true) push_allowances = optional(list(string), []) }), {}) })	{}	no
dns_settings	Additional custom DNS records for Spaceship	object({ ttl = optional(number, 60) records = optional(list(object({ type = string name = string address = optional(string) alias_name = optional(string) association_data = optional(string) cname = optional(string) exchange = optional(string) flag = optional(number) matching = optional(number) nameserver = optional(string) pointer = optional(string) port = optional(string) port_number = optional(number) preference = optional(number) priority = optional(number) protocol = optional(string) scheme = optional(string) selector = optional(number) service = optional(string) svc_params = optional(string) svc_priority = optional(number) tag = optional(string) target = optional(string) target_name = optional(string) ttl = optional(number) usage = optional(number) value = optional(string) weight = optional(number) })), []) })	{}	no
domain	The custom domain for GitHub Pages (e.g., example.com)	string	n/a	yes
name	Name of the GitHub repository to create	string	n/a	yes
organization	Optional GitHub organization to create the repository in	string	""	no
pages_settings	Settings for the GitHub Pages configuration	object({ build_type = optional(string, "legacy") public = optional(bool) # Note: 'https_enforced' is temporarily disabled due to GitHub provider bug #3450. A local-exec provisioner handles this. https_enforced = optional(bool, true) source = optional(object({ branch = string path = optional(string, "/") }), { branch = "master" path = "/" }) })	{}	no
repository_settings	Detailed settings for the GitHub repository	object({ description = optional(string, "GitHub Pages repository") visibility = optional(string, "private") homepage_url = optional(string) fork = optional(bool, false) source_owner = optional(string) source_repo = optional(string) has_issues = optional(bool, true) has_discussions = optional(bool, false) has_projects = optional(bool, false) has_wiki = optional(bool, false) is_template = optional(bool, false) allow_merge_commit = optional(bool, false) allow_squash_merge = optional(bool, false) allow_rebase_merge = optional(bool, true) allow_auto_merge = optional(bool, false) allow_update_branch = optional(bool, true) allow_forking = optional(bool, true) squash_merge_commit_title = optional(string, "PR_TITLE") squash_merge_commit_message = optional(string, "PR_BODY") merge_commit_title = optional(string) merge_commit_message = optional(string) delete_branch_on_merge = optional(bool, true) web_commit_signoff_required = optional(bool, true) auto_init = optional(bool, true) gitignore_template = optional(string) license_template = optional(string, "apache-2.0") default_branch = optional(string, "master") archived = optional(bool, false) archive_on_destroy = optional(bool, false) topics = optional(list(string), []) # Note: This attribute is deprecated in the provider, but currently required to satisfy security and analysis checks. vulnerability_alerts = optional(bool, true) template = optional(object({ owner = string repository = string include_all_branches = optional(bool, false) })) security_and_analysis = optional(object({ advanced_security = optional(object({ status = string })) secret_scanning = optional(object({ status = string })) secret_scanning_push_protection = optional(object({ status = string })) secret_scanning_ai_detection = optional(object({ status = string })) secret_scanning_non_provider_patterns = optional(object({ status = string })) })) # Note: The inline pages configuration is deprecated. It is retained here for backwards compatibility, but pages_settings should be preferred. pages = optional(object({ build_type = optional(string) # Note: 'cname' is temporarily disabled due to GitHub provider bug #3450. A local-exec provisioner handles this. cname = optional(string) source = optional(object({ branch = string path = optional(string) })) })) })	{}	no
user	Optional GitHub user to create the repository under	string	""	no

Outputs

Name	Description
domain	The configured custom domain
pages_url	URL of the GitHub Pages site
repository_name	Name of the created GitHub repository
repository_url	URL of the created GitHub repository

Contributing

Report issues/questions/feature requests on in the issues section.

Full contributing guidelines are covered here.

License

Apache 2 Licensed. See LICENSE for full details.

Security

If you discover any security related issues, please email ivan.kornienko@gmail.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.