Skip to content

GitHub

The tomoda-labs org is on GitHub Free with five private repos: tomoda, devops, operations, tomoda-ios and tomoda-android. Repo settings, Actions variables, org members, teams and collaborators are managed by Terraform in infrastructure/github/. Everything else in the org is set by hand and inventoried below.

Free-plan limits apply to every private repo: no branch protection, no rulesets and no environment protection rules. PR review is the merge gate; see Terraform CI/CD.

Managed by Terraform

What Resource File
Repo settings: description, visibility, features, merge methods, squash/merge commit format, auto-delete branches github_repository (prevent_destroy, archive on destroy) infrastructure/github/repos.tf
Dependabot alerts on/off github_repository_vulnerability_alerts infrastructure/github/repos.tf
Actions enabled + allowed actions github_actions_repository_permissions infrastructure/github/repos.tf
Default GITHUB_TOKEN permissions (read, can't approve PRs) github_workflow_repository_permissions infrastructure/github/repos.tf
Repo Actions variables github_actions_variable infrastructure/github/actions.tf
Org members and roles github_membership infrastructure/github/access.tf
Teams, team members, team repo access github_team, github_team_membership, github_team_repository infrastructure/github/access.tf
Outside collaborators and direct repo grants github_repository_collaborator infrastructure/github/access.tf

State: gs://tomoda-tfstate, prefix github/state. The plan and apply workflows run this stack next to cloudflare and gcp once the tomoda-terraform App exists (Bootstrap).

Current repo merge policy:

Repo Merge methods Auto-delete branch
tomoda, devops squash only, PR title + body yes
operations squash only, "update branch" button on yes
tomoda-ios squash, merge, rebase yes
tomoda-android squash, merge, rebase no

Not managed by Terraform

Item Today Why not Terraform
Org settings (base permission, member repo creation, Actions policy) Org settings UI Not adopted yet; candidate for github_organization_settings and the org Actions permission resources
Require two-factor authentication Org settings UI No API; see Two-factor requirement
Actions secrets Repo settings UI Values would land in Terraform state; see Secrets
GitHub Apps (creation, permissions, private keys, installations) Org settings UI No API to create an App or download its key
GHCR packages: visibility, retention, "Manage Actions access", repo read links (e.g. tomoda reads tomoda-postgres) Package settings UI The provider has no package resources; the REST API has no write endpoint for package access
Environments (copilot on tomoda, infra-apply on devops) Auto-created / unused No protection rules on Free; nothing references infra-apply
Issue labels Created by people and by the Trivy issue reporter Authoritative label management would delete reporter-created due:* labels
Branch protection, rulesets Unavailable Free plan on private repos

There are no repo or org webhooks and no deploy keys. Org Actions policy: all repos, all actions, read-only default token. Self-hosted runners: the ARC scale sets (tomoda-arc, tomoda-arc-db, tomoda-arc-trusted), all in the Default group, the only group on the Free plan.

GitHub Apps installed on the org

App Repos Used by Credentials
tomoda-ci-automation selected Argo CD repo access, ARC runners, Trivy issue reporter GSM tomoda-github-app-{id,installation-id,private-key}; see Bootstrap
tomoda-release selected (tomoda, devops) Release run, deploy PRs, prod-deployed dispatch RELEASE_APP_ID variable in both repos + GSM tomoda-release-app-private-key, read through WIF on main (IAM)
tomoda-terraform all This stack (CI plan/apply) TERRAFORM_APP_ID variable on devops + GSM tomoda-github-terraform-app-private-key
cloudflare-workers-and-pages selected Docs site build Cloudflare-side
claude, google-labs-jules all / selected Coding agents Vendor-side

Secrets

Actions secrets stay out of Terraform: github_actions_secret writes the value into state, and an imported secret has no value, so the next apply would overwrite it. Set them in the repo settings UI or with gh secret set. This table is the inventory; update it when you add one. Prefer Secret Manager read through WIF for anything prod can be hurt by.

Repo Secret Source
tomoda XAVIA_DEV_UPLOAD_KEY GSM tomoda-ota-dev-upload-key
devops PAGES_DEPLOY_HOOK Cloudflare Pages deploy hook URL

There are no org-level Actions variables or secrets.

Access

Defined in infrastructure/github/access.tf; change access by PR, not in the UI. Removing a login from local.members removes that person from the org on apply.

How access is granted:

  • Org members, teams, team membership and team repo access are the members and teams maps in infrastructure/github/access.tf.
  • Teams grant at most write.
  • Repo admin comes only from the all_repo_admin org role, assigned in the org settings UI rather than by this stack.
  • Outside collaborators and direct repo grants are the collaborators map in infrastructure/github/access.tf.
  • Base repo permission for members is none.

Two-factor requirement

The org does not require 2FA, and neither the API nor the provider can turn it on. Toggle it in Org settings → Authentication security → Require two-factor authentication.

Warning

Enabling it immediately removes every member and outside collaborator without 2FA. Check first with gh api 'orgs/tomoda-labs/members?filter=2fa_disabled' and gh api 'orgs/tomoda-labs/outside_collaborators?filter=2fa_disabled', and have them enable 2FA before you flip it. After the toggle, Terraform would try to re-add removed members on the next apply, so align access.tf too.

Change a setting or add a variable

  1. Edit the repos, actions_variables, members, teams or collaborators map in infrastructure/github/.
  2. Open a PR; the plan posts as a comment. Merge applies.

Add a new repo the same way: an entry in local.repos creates it. To adopt a repo made in the UI, add an import {} block for it in the same PR.

Plan locally (read-only; your token needs repo and read:org, plus admin:org to read memberships):

task auth:gcp
cd infrastructure/github && terraform init
GITHUB_TOKEN=$(gh auth token) terraform plan

Bootstrap the tomoda-terraform App

One-time. CI skips the stack until TERRAFORM_APP_ID is set.

  1. Org settings → Developer settings → GitHub Apps → New GitHub App. Name tomoda-terraform, webhook off, installable on this account only.
  2. Permissions:
    • Repository: Administration read/write, Variables read/write, Metadata read.
    • Organization: Members read/write (org membership, teams, team repo access).
  3. Create, Generate a private key, then install it on tomoda-labs with All repositories.
  4. Store the key in GSM and delete the local file:

    # the secret itself is in infrastructure/gcp/secrets.tf
    gcloud secrets versions add tomoda-github-terraform-app-private-key \
      --project=development-485000 --data-file=<downloaded>.pem && rm -P <downloaded>.pem
    
  5. Set the App ID on the devops repo: gh variable set TERRAFORM_APP_ID -R tomoda-labs/devops --body <app-id>.

  6. Re-run the Terraform Plan workflow on an open infra PR (or push a no-op change) and check the github plan.

Why a dedicated App: the release App's key sits in GitHub secrets on two repos and is used by the app release pipeline, so adding Administration and Members to it would let any tomoda workflow change repo settings and org membership. A fine-grained PAT ties the stack to one person's account and expires. The Terraform App's key lives only in GSM, readable by the terraform-ci SA.