Discord Infrastructure as Code

Manage your entire Discord server (Helmáč) as declarative Terraform configuration. Add, modify, or remove divisions, channels, roles, and permissions through code—everything syncs automatically to Discord.

Quick Start

To configure new divisions or teams: Simply edit divisions.tf.json and open a pull request. The rest is automated.

All channels, roles, permissions, and onboarding flows are generated automatically from the division definitions.

How It Works

This project uses Terraform to manage:

• Shared channels with full permission setup
• Individual division channels (teams) with dedicated channels, roles, and permissions
• Automated onboarding for new members to self-select divisions
• Role hierarchy with member and manager roles per division
• Channel permissions configured declaratively
• CI/CD pipeline with encrypted state management

Architecture

divisions.tf.json (single source of truth)
    ↓
    ├─→ channels.tf    - Creates text channels + permissions
    ├─→ roles.tf       - Creates member & manager roles
    └─→ onboarding.tf  - Generates self-service onboarding

Setup

Prerequisites

For contributing:

1. Gain access to ENCRYPTION_KEY and add it to .env.

2. Terraform 1.0+

For applying changes manually:

1. Discord Bot with Admin permissions

   • Create at Discord Developer Portal
   • Copy bot token and server ID (enable Developer Mode in Discord) to .env

2. Terraform 1.0+

Installation

# 1. Configure credentials
cp .env.example .env
# Edit .env with ENCRYPTION_KEY
source .env

# 2. Install Discord provider
./scripts/setup.sh

# 3. Download latest available shared state
./scripts/download-state.sh

# 3. Initialize Terraform
terraform init

Usage

Adding a New Division

Edit divisions.tf.json and add to the locals.divize array:

{
  "name": "new-team",
  "color": {
    "clen": 2067276,
    "garant": 3066993
  },
  "onboarding": {
    "description": "Help with new team tasks",
    "emoji_name": "🆕",
    "title": "New Team"
  }
}

Note: Terraform cannot handle HEX colors, use decimal values instead.

This automatically creates:

• Text channel #new-team
• Role Člen - new-team (Member)
• Role Garant - new-team (Manager)
• Channel permissions for both roles
• Onboarding prompt for self-assignment

Deploy Changes

! This will only work if you have access to following secrets:

DISCORD_BOT_TOKEN DISCORD_SERVER_ID

# Preview changes
terraform plan

# Apply to Discord
terraform apply

Import Existing Resources

Helper scripts are provided for importing existing Discord infrastructure:

# Import division roles
./scripts/import-division.sh garant hospoda ROLE_ID

# Import channel permissions
./scripts/import-channel-permission.sh info INFO_ID

# Import division channel permissions
./scripts/import-division-channel-permission.sh

CI/CD

GitHub Actions automatically:

1. Decrypts Terraform state (GPG encrypted)
2. Builds Discord provider from source
3. Plans changes on every push to main
4. Re-encrypts and stores state

Required secrets:

• DISCORD_BOT_TOKEN
• DISCORD_SERVER_ID
• ENCRYPTION_KEY (GPG passphrase)

Project Structure

File	Purpose
divisions.tf.json	Division definitions (edit this to add/modify teams)
channels.tf	Channel creation and permission overrides
roles.tf	Role definitions (global + division roles)
permissions.tf	Reusable permission datasets
onboarding.tf	Server onboarding flow configuration
server.tf	Main server resource
provider.tf	Discord provider authentication
variables.tf	Input variable definitions
versions.tf	Terraform and provider version constraints

Important Notes

• Never commit .env, terraform.tfvars, or terraform.tfstate (contains sensitive data)
• Test first - Always run terraform plan before terraform apply
• Encrypted state - CI/CD uses GPG-encrypted state for security
• Provider source - Built from tumido/terraform-provider-discord (branch: my-release)