# terraform-github

## Note: Please do not add new github repositiories to this repo. Instead add them to [theorchard/terraform-infra](https://github.com/theorchard/terraform-infra) following [this guide](https://www.notion.so/terraform-github-b4d7845049814721a99af4286fb0336d).

## Overview

This module provides functionality to create github repositories with a configurable set of collaborator and branch settings.

### Usage

In order to use this module, specify this variable:
```
* var.github_repository_names (map of repositories to create with their configurations)
```

#### Required Provider Configuration

Before using this module, the calling root module must declare the GitHub provider with an empty `app_auth {}` block and declare the provider source in `versions.tf`.

**`main.tf`** (or wherever your provider blocks live):
```hcl
provider "github" {
  organization = var.github_organization
  app_auth {}
}
```

**`versions.tf`**:
```hcl
terraform {
  required_version = "..."
  required_providers {
    github = {
      source = "integrations/github"
    }
  }
}
```

> **Why both are required:** The `app_auth {}` block tells the provider to use GitHub App credentials (supplied via environment variables). The `required_providers` declaration in the root module is necessary so Terraform can match the root module's `provider "github"` configuration to this module's `integrations/github` requirement. Without it, Terraform treats them as different providers, instantiates a fresh unconfigured provider for the child module, and the `app_auth` credentials are never passed through — causing 401 authentication errors at plan time.
>
> The version constraint is intentionally omitted from `required_providers` in the root module — this module declares its own constraint, and Terraform will satisfy it automatically. Specifying a version in the root risks constraining to a release this module does not support.

#### Basic Usage

```hcl
module "github_repositories" {
  source = "git@github.com:theorchard/terraform-github.git//?ref=X.X.X"

  repository_name    = "my-repo"
  description        = "My repository description"
  default_code_owner = "my-team" # GitHub team slug
  application_family = "my-app-family"
}
```
You can also override default collaborator settings by specifying values for the following variables (all lists):
```
* var.github_pull_teams
* var.github_push_teams
* var.github_repository_pull_collaborators
* var.github_repository_push_collaborators
```

#### Autolink References (Jira Integration)

To automatically link Jira ticket IDs (e.g., `SYS-123`) in PR titles and descriptions to Jira, configure the `autolink_references` variable:

```hcl
module "github_repositories" {
  source = "git@github.com:theorchard/terraform-github.git//?ref=X.X.X"

  repository_name    = "my-repo"
  description        = "My repository description"
  default_code_owner = "my-team"
  application_family = "my-app-family"

  autolink_references = [
    {
      key_prefix          = "SYS-"
      target_url_template = "https://jira.example.com/browse/SYS-<num>"
    },
    {
      key_prefix          = "PROJ-"
      target_url_template = "https://jira.example.com/browse/PROJ-<num>"
    }
  ]
}
```

Each autolink reference supports:
- **key_prefix**: The prefix to match (e.g., "SYS-" for Jira project SYS)
- **target_url_template**: The URL template with `<num>` placeholder
- **is_alphanumeric**: (Optional, default: true) If true, matches alphanumeric characters; if false, matches only numeric

### Testing

Run tests using make. Make sure you have GITHUB_TOKEN set with permissions to create and delete repos and set branch protection.

```bash
make test
```

### Caveats

Currently, the Github API does not expose endpoints to configure what teams or users receive security alerts, once they are enabled. While this module _does_ enable security alerts, it does not configure these recipients. You must do this manually via the UI for the time being.