This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

GitHub

GitHub organization, repositories, access, and Pages configuration

This project manages the GitHub organization and repositories declared by the shared repository catalog, including existing forks, project landing sites, organization membership, and developer access.

Service Terraform adopts existing resources and preserves their identities. It also manages repository default-branch rules and existing Pages configuration. Site content is published through the owning project deployment targets; this infrastructure package does not publish it.

1 -

Infrastructure GitHub

Describe Terraform ownership of the catalog-defined GitHub organization, repositories, member access, default-branch restrictions, and Pages settings. These requirements describe source guarantees; they do not assert that a plan has been applied or that published sites are healthy.

Sources: component documentation, Terraform workflow, shared catalog, packaged inputs, repository resources, organization access, branch rules, and provider configuration.

The package SHALL consume organization identity, administrator and developer lists, repository identity, default branches, repository settings, and Pages configuration through infra/repos/tf. It SHALL NOT generate a second inventory from the build-project registry. Its provider instance SHALL require exactly one configured GitHub organization.

  • WHEN the package renders its repository resources
  • THEN every catalog GitHub repository is managed from its catalog record

Dedicated per-project landing repositories SHALL NOT be managed. The main site publishes every project landing at /projects/<name>/, so the catalog carries no landing_project key and no per-project Pages repository, custom domain, github-pages environment, or landing default branch is declared.

  • WHEN a project’s landing page is published
  • THEN it is served by the apex site at /projects/<name>/ from the apex Pages repository
  • AND no per-project repository, Pages configuration, or custom domain is managed

The package SHALL provide import blocks for existing organization settings, repositories, default branches, memberships, developer collaborators, and the two existing src rulesets. Repositories with observed catalog IDs SHALL retain those IDs. Managed resources SHALL reject Terraform destruction, and any deletion or replacement SHALL require explicit user approval before apply.

The organization settings resource SHALL own only catalog-defined base repository access. Its mandatory billing argument SHALL be an import-only placeholder whose imported value is ignored; billing, profile, and other organization defaults SHALL remain outside this module’s ownership. Existing Dependabot alert settings SHALL be preserved.

  • WHEN import cannot resolve an observed catalog repository
  • THEN the operation fails rather than creating a replacement repository

Catalog administrators SHALL be organization owners. Catalog developers SHALL receive explicit write access on every GitHub catalog repository through non-authoritative collaborator resources. Repository default branches SHALL have active rulesets restricting creation, updates, deletion, and force pushes, with bypass restricted to organization administrators. The update restriction SHALL NOT permit fork syncing as a developer bypass. Ruleset application SHALL follow the managed default-branch selection. The two pre-existing src rulesets SHALL be imported unchanged, retaining their rules and bypass actors alongside the new default-branch ruleset.

  • WHEN a catalog developer writes to a non-protected contribution branch
  • THEN repository write access permits the contribution and opening a pull request
  • AND the developer cannot push or merge into the default branch
  • WHEN the site publisher writes content to the apex repository’s pages branch
  • THEN repository write access permits publication
  • AND its master default branch remains protected from developer pushes and merges

This package SHALL own repository resources and Pages settings. The documented workflow SHALL use //projects/alwaldend.com:deploy for site content and //infra/dns for DNS records.

  • WHEN an operator prepares an authorized site rollout
  • THEN repository and Pages changes are reviewed in the Terraform workflow
  • AND built content publication and DNS changes use their separately owned workflows

GitHub issues the custom-domain certificate as part of its Pages build and offers no direct reissue action, so the package SHALL document a supported, separately reviewed way to omit the apex site’s Pages block and then restore it, forcing a new certificate. The procedure SHALL use two filtered applies and SHALL include an HTTPS verification step.

  • WHEN an authorized apply removes the apex site’s Pages block
  • THEN the reviewed plan removes only that configuration
  • AND the documented procedure restores it with a later apply
  • AND the operator verifies the certificate served for the custom domain

2 - GitHub Terraform

GitHub organization, repository, access, and Pages management

This package consumes the shared repository catalog through its provider-free Terraform module. The catalog supplies the GitHub owner, repositories, default branches, repository settings, organization administrators, and developers. This root supports one GitHub organization per provider instance and rejects multiple configured owners.

Existing repositories are imported, including forks. The apex site repository keeps its Pages configuration and custom domain. Published repository names and Pages domains come directly from the catalog; they are not regenerated from the current build-project registry.

Dedicated per-project landing repositories were retired: the main site now publishes every project landing at /projects/<name>/, so the catalog carries no landing_project key and this root manages no per-project Pages repository, custom domain, github-pages environment, or landing default branch.

The checked-in import blocks adopt the organization, existing repositories, default branches, memberships, developer collaborators, and both existing src rulesets. A repository with an observed catalog github.id must retain that numeric identity. An import failure must be resolved before applying; never remove an import merely to create an existing object again. Repositories, memberships, access grants, environments, and rulesets have deletion guards. Review the complete plan and obtain explicit authorization for any deletion or replacement. Previously authorized retirement may proceed within its exact reviewed scope.

Organization settings own only catalog-defined repository base permissions. Billing, profile fields, and other organization defaults remain controlled by GitHub and are explicitly ignored. The required empty billing_email argument is an import-only placeholder: the existing billing address is retained from state and must never be committed or exposed in plan output. Do not create this organization-settings resource without its import block. Dependabot alert settings for newly adopted repositories are similarly preserved.

Catalog administrators are organization owners. Developers receive explicit write access on every catalog repository, while organization base permissions remain at the catalog setting. The grants are non-authoritative, preserving other collaborators. Each repository has an active default-branch ruleset restricting creation, updates, deletion, and force pushes, with an organization administrator bypass. Developers can push other branches and open pull requests, but cannot directly push or merge into the default branch. Forks also disable the upstream fetch-and-merge exception. Catalog repositories permit merge commits only; squash and rebase merges are disabled, so an accepted pull request records a merge commit whose parents include the reviewed feature commit. Both pre-existing src rulesets retain their separate release-branch protections and bypass actors; the default-branch ruleset also applies alongside them. Repository rulesets are available for these public repositories on GitHub Free.

The apex site repository receives its built Hugo site from //projects/alwaldend.com:deploy in the root workspace. Terraform manages the catalog-defined custom domain and Pages source. Keep all applies limited to reviewed, authorized repository and Pages changes. DNS is managed by the owning Terraform root; DNS documentation describes the workflow. Validate the public custom domain after rollout.

GitHub issues the custom-domain certificate as part of its Pages build. If a certificate must be reissued, remove the pages block from the apex catalog record in a reviewed plan, apply it, then restore it in a second plan; GitHub schedules a new certificate once the custom domain returns. Verify the pushed revision, Pages build state, DNS, and the served certificate before closing the recovery.