Connecting Repositories

Learn how to connect your GitHub repositories to Controlinfra for drift monitoring.

Overview

Controlinfra integrates directly with GitHub to access your Terraform repositories. Each connected repository can be configured with:

• AWS credentials for infrastructure access
• Terraform backend settings
• Multiple workspaces (directories)
• Custom variables and var files

Adding a Repository

Step 1: Navigate to Add Repository

From your dashboard, click "Add Repository" or navigate to Repositories → Add New.

Step 2: Select Repository

You'll see a list of GitHub repositories you have access to. Select the repository containing your Terraform code.

Can't see your repository?

Make sure you've granted Controlinfra access to the repository's organization. You may need to request access from your organization admin.

Step 3: Configure Working Directory

Specify where your Terraform files are located:

Path	Use Case
/	Root of repository
/infrastructure	Common subfolder
/terraform/production	Environment-specific
/modules/vpc	Specific module

Step 4: Add AWS Credentials

Enter AWS credentials with read access to your infrastructure:

AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS Region: us-east-1

Required IAM Permissions

Your AWS credentials need read access to resources managed by Terraform. A minimal policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "s3:GetBucket*",
        "s3:ListBucket",
        "rds:Describe*",
        "iam:Get*",
        "iam:List*",
        "lambda:Get*",
        "lambda:List*"
      ],
      "Resource": "*"
    }
  ]
}

WARNING

For production use, we recommend using self-hosted runners which allow you to keep credentials within your own infrastructure.

Step 5: Configure Terraform Backend (Optional)

If your Terraform uses a remote backend, configure it so Controlinfra can access your state:

S3 Backend

bucket         = "my-terraform-state"
key            = "infrastructure/terraform.tfstate"
region         = "us-east-1"
dynamodb_table = "terraform-locks"

Terraform Cloud / Enterprise

organization = "my-org"
workspace    = "my-workspace"

Step 6: Save and Verify

Click Save Repository. Controlinfra will:

1. Verify GitHub access
2. Check AWS credentials
3. Validate Terraform configuration

Managing Multiple Workspaces

A single repository can contain multiple Terraform configurations. Add additional workspaces to monitor them all:

Example Repository Structure

terraform-infrastructure/
├── production/
│   ├── main.tf
│   ├── variables.tf
│   └── backend.tf
├── staging/
│   ├── main.tf
│   ├── variables.tf
│   └── backend.tf
└── shared/
    └── networking/
        ├── main.tf
        └── outputs.tf

Adding Workspaces

1. Navigate to your repository
2. Click "Add Workspace"
3. Enter the workspace path (e.g., staging/)
4. Configure workspace-specific settings if needed

Each workspace will be scanned independently, allowing you to:

• Track drift separately for each environment
• Use different AWS credentials per workspace
• Configure different scan schedules

Repository Settings

General Settings

Setting	Description
Display Name	Custom name for the repository
Auto-scan	Enable automatic scanning on push
Scan Schedule	Cron expression for scheduled scans

Terraform Settings

Setting	Description
Version	Terraform version to use
Var File	Path to .tfvars file
Variables	Key-value pairs for Terraform variables

Notifications

Configure alerts for:

• Scan completion
• Drift detected
• High-severity issues
• Scan failures

Removing a Repository

To remove a repository:

1. Navigate to the repository
2. Click Settings (gear icon)
3. Scroll to Danger Zone
4. Click "Remove Repository"

DANGER

Removing a repository will delete all associated scan history and drift data. This action cannot be undone.

Troubleshooting

"Repository not found" Error

• Verify you have access to the repository on GitHub
• Check if the repository is private and permissions are granted
• Re-authenticate with GitHub if needed

"Invalid AWS credentials" Error

• Double-check the Access Key ID and Secret Access Key
• Verify the IAM user has the required permissions
• Check if the credentials have been rotated or disabled

"Terraform init failed" Error

• Ensure the working directory path is correct
• Verify backend configuration matches your Terraform setup
• Check if required providers are available

Next Steps

• Configure AWS Credentials - Detailed AWS setup
• Terraform Configuration - Advanced Terraform settings
• Run Your First Scan - Start detecting drift