Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
<!--
PR body rules:
- One paragraph per section, no hard-wrap (GitHub flows the text).
- Explain the shipped feature shape, not every implementation detail.
- No design rationale narration here — link out to a contributor doc instead.
- No file-by-file changelog (use the diff). No full check list (use CI output).
- Every Verify-locally command is copy-pasteable and states its expected
outcome when a bare exit code does not disambiguate pass from fail.
- Drop the headings you do not need. "Related pull requests" is only when the
PR spans multiple repos (for example coordinated parity changes across the
github-terraform repos). "Behavior changes" is only when it adds signal
beyond "What ships". "Not included" is only when scope boundaries or
deferred work are useful to call out.
-->

## Related pull requests

<When this PR is part of a coordinated set spanning multiple repositories, list every PR here — just the link, no description. Drop this section entirely when the PR stands alone.>

- <https://github.com/org/repo/pull/N>

## Summary

<One paragraph answering: what is this pull request for? Name the shipped change to organization or repository management, who runs it, and how it changes their flow. Keep this short.>

## What ships

<Feature-level bullets grouped by operator-visible outcome: repositories onboarded, policy enforced, provider or wiring changes, documentation changes. Avoid resource names and file lists — the diff already shows those.>

- <Capability or policy that now exists>
- <Configuration, documentation, or workflow change operators can rely on>

## Behavior changes

<Operator-visible deltas: changed required checks, changed merge settings, changed token or permission requirements, changed runbook steps. Drop this section when it would only repeat "What ships".>

- <Existing behavior that changes>

## What this addresses

<Bullets naming the practical problem, drift, or operational pain now resolved. Name the issue when one exists.>

- <Problem or gap addressed>

## Not included

<Scope boundaries and deferred work: repositories not yet onboarded, follow-up PRs, policy left unchanged deliberately. Drop this section entirely when nothing meaningful is excluded.>

- <Out-of-scope behavior or deferred follow-up>

## Verify locally

### Checkout

```sh
gh pr checkout <PR_NUMBER>
```

### Static checks

<The format and validate gates, exactly as CI runs them in the tofu-workspace job. Expected: `tofu validate` prints "Success! The configuration is valid.">

```sh
tofu fmt -check -recursive
tofu init -backend=false -input=false -lockfile=readonly
tofu validate -no-color
```

### Smoke

<Include when the PR changes plan-visible behavior: repositories, rulesets, providers. Drop when the PR only touches docs or comments. Requires GITHUB_TOKEN exported with Administration: write on every managed repository.>

```sh
tofu plan -no-color
```

Expected: <the plan renders with no provider or permission errors; name the key actions the reviewer should see, or "No changes" when the PR is already applied>.

## Migration notes

<One paragraph naming what operators must do — token permission changes, state moves, re-imports. "None." is fine. Drop the section when it would only say that.>
29 changes: 25 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,46 @@ settings plus `protect-main` and `protect-tags` rulesets.
- `variables.tf` — `repository_policies` inventory (single source of truth).
- `locals.tf` — `check_templates` copy-paste source for check lists.
- `repositories.tf` — `module.repository_policy` wiring.
- `organization.tf` — organization settings and Actions/workflow permissions.
- `modules/repository-policy/` — shared policy module (identical across orgs).
- `checks.tf` — invariant guards (no scripts).
- `imports.tf` — bootstrap import triples (one per repo: settings + 2 rulesets).
- `providers.tf`, `versions.tf`, `outputs.tf` — provider, pins, outputs.

## Authentication

Run tofu with `GITHUB_TOKEN` exported in the shell, or via the mise tasks
`mise run tofu:plan` / `mise run tofu:apply`, which inject the organization
token from 1Password. The token needs Administration: write on every managed
repository. It also needs org admin on `jackin-project` for the organization
settings and Actions policies in `organization.tf`.

## Adding a repository

1. Add one entry to `repository_policies` in `variables.tf`, copying a check
list from `locals.tf` (`standard` = `["Required", "DCO"]`,
`policy` = `["Policy"]`); bespoke checks inline with a comment citing the
producing workflow. Repos with no CI use `required_checks = []` plus a
non-empty `no_ci_reason` and extend the allowlist check in `checks.tf`.
list from `locals.tf` (`standard` = `["Required", "DCO"]`, `policy` =
`["Policy"]`); bespoke checks inline with a comment citing the producing
workflow. Repos with no CI use `required_checks = []` plus a non-empty
`no_ci_reason` and extend the allowlist check in `checks.tf`. Always add
the name to the mandatory list in `mandatory_target_repositories_present`
in `checks.tf` (updating its count and message).
2. Add one import triple (settings + `protect_main` + `protect_tags`) to
`imports.tf` using the live numeric ruleset IDs.

## Organization overlays

- `organization.tf` manages the org profile (`github_organization_settings`),
Actions availability/allow policy (`github_actions_organization_permissions`),
and default `GITHUB_TOKEN` workflow permissions
(`github_actions_organization_workflow_permissions`).

## Verification

```sh
tofu fmt -check -recursive
tofu init -backend=false -input=false -lockfile=readonly
tofu validate -no-color
```

OpenTofu is pinned via `mise.toml` (opentofu 1.13.1); existing repos are
imported via `imports.tf` on first apply.
15 changes: 15 additions & 0 deletions imports.tf
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,21 @@
# Adopt the existing GitHub resources into the default local state before managing them.
# These stable IDs prevent a fresh state from planning duplicate repositories or rulesets.

import {
to = github_organization_settings.jackin_project
id = "273541039"
}

import {
to = github_actions_organization_permissions.jackin_project
id = "jackin-project"
}

import {
to = github_actions_organization_workflow_permissions.jackin_project
id = "jackin-project"
}

import {
to = module.repository_policy.github_repository.managed_settings["homebrew-tap"]
id = "homebrew-tap"
Expand Down
22 changes: 22 additions & 0 deletions mise.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,25 @@ opentofu = "1.13.1"
python = "3.14"
uv = "0.11.29"
"pipx:reuse" = { version = "6.2.0", extras = "charset-normalizer", depends = ["python"] }

[tasks."tofu:plan"]
description = "Run tofu plan"
run = """
set -eu
export OP_ACCOUNT='zhokhov.1password.com'
GITHUB_TOKEN="$(op read 'op://Private/hq3g4pvryg4iise4vxwhk6p5jy/jackin-project-opentofu')" || { echo "op read failed, refusing to run" >&2; exit 1; }
export GITHUB_TOKEN
[ -n "${GITHUB_TOKEN:-}" ] || { echo "GITHUB_TOKEN is empty, refusing to run" >&2; exit 1; }
exec tofu plan "$@"
"""

[tasks."tofu:apply"]
description = "Run tofu apply"
run = """
set -eu
export OP_ACCOUNT='zhokhov.1password.com'
GITHUB_TOKEN="$(op read 'op://Private/hq3g4pvryg4iise4vxwhk6p5jy/jackin-project-opentofu')" || { echo "op read failed, refusing to run" >&2; exit 1; }
export GITHUB_TOKEN
[ -n "${GITHUB_TOKEN:-}" ] || { echo "GITHUB_TOKEN is empty, refusing to run" >&2; exit 1; }
exec tofu apply "$@"
"""
50 changes: 50 additions & 0 deletions organization.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# SPDX-FileCopyrightText: 2026 Alexey Zhokhov
# SPDX-License-Identifier: Apache-2.0

# Organization-wide policy. Actions permissions and workflow defaults match the
# live baseline (tightening waits for per-repo workflow audits). New-repository
# security defaults are intentionally hardened (detection-only, future repos).

resource "github_organization_settings" "jackin_project" {
billing_email = "alexey@zhokhov.com"

name = ""
description = ""
blog = ""
email = "jackin@tailrocks.com"
location = "Singapore"

has_organization_projects = true
has_repository_projects = true
default_repository_permission = "read"
members_can_create_repositories = true

members_can_create_public_repositories = true
members_can_create_private_repositories = true

members_can_create_pages = true
members_can_create_public_pages = true
members_can_create_private_pages = true

members_can_fork_private_repositories = false
web_commit_signoff_required = false

dependabot_alerts_enabled_for_new_repositories = true
dependabot_security_updates_enabled_for_new_repositories = true
dependency_graph_enabled_for_new_repositories = true
secret_scanning_enabled_for_new_repositories = true
secret_scanning_push_protection_enabled_for_new_repositories = true
}

resource "github_actions_organization_permissions" "jackin_project" {
enabled_repositories = "all"
allowed_actions = "all"
sha_pinning_required = false
}

resource "github_actions_organization_workflow_permissions" "jackin_project" {
organization_slug = var.github_organization

default_workflow_permissions = "write"
can_approve_pull_request_reviews = false
}
4 changes: 4 additions & 0 deletions outputs.tf
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# SPDX-FileCopyrightText: 2026 Alexey Zhokhov
# SPDX-License-Identifier: Apache-2.0

output "organization" {
value = var.github_organization
}

output "managed_repositories" {
description = "Set of managed repository names (inventory keys)"
value = module.repository_policy.managed_repositories
Expand Down