Repositories

Manage your Terraform repositories from the command line.

List Repositories

View all configured repositories:

bash

controlinfra repos list

Output:

┌──────────┬─────────────────────────┬────────┬───────────┬─────────────┐
│ ID       │ Repository              │ Branch │ Status    │ Last Scan   │
├──────────┼─────────────────────────┼────────┼───────────┼─────────────┤
│ a1b2c3d4 │ myorg/infrastructure    │ main   │ completed │ 2 hours ago │
│ e5f6g7h8 │ myorg/terraform-modules │ main   │ pending   │ -           │
└──────────┴─────────────────────────┴────────┴───────────┴─────────────┘

Filter by Workspace

bash

controlinfra repos list --workspace <workspace-id>

Add a Repository

Connect a new repository:

bash

controlinfra repos add owner/repo

Common Options

Option	Description	Default
`--terraform-dir <path>`	Path to Terraform directory	`.`
`--workspace <id>`	Assign to workspace	-
`--cloud-provider <provider>`	Cloud provider: `aws`, `azure`, `gcp`	`aws`
`--runner-type <type>`	Runner type: `cloud`, `self-hosted`	`cloud`
`--runner-id <id>`	Runner ID (required for self-hosted)	-

AWS Authentication

Options

Option	Description	Default
`--auth-method <method>`	`credentials`, `instance_profile`, `assume_role`	`credentials`
`--region <region>`	AWS region	`us-east-1`
`--access-key <key>`	AWS Access Key ID	-
`--secret-key <key>`	AWS Secret Access Key	-
`--role-arn <arn>`	Role ARN (for assume_role)	-
`--external-id <id>`	External ID (for assume_role)	-

Examples

Using AWS Credentials

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider aws \
  --auth-method credentials \
  --access-key AKIAIOSFODNN7EXAMPLE \
  --secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  --region us-east-1 \
  --terraform-dir terraform/

Using Instance Profile (Self-Hosted Runner on EC2)

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider aws \
  --auth-method instance_profile \
  --region us-west-2 \
  --runner-type self-hosted \
  --runner-id abc123def456

Using Assume Role (Cross-Account)

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider aws \
  --auth-method assume_role \
  --role-arn arn:aws:iam::123456789012:role/ControlinfraRole \
  --external-id my-external-id \
  --region us-east-1 \
  --runner-type self-hosted \
  --runner-id abc123def456

AWS Authentication Methods

credentials: Use AWS access keys (works with cloud or self-hosted runners)
instance_profile: Use EC2 instance role (self-hosted runners only)
assume_role: Assume a role in another account (self-hosted runners only)

Azure Authentication

Options

Option	Description	Default
`--azure-auth-method <method>`	`service_principal`, `managed_identity`	`service_principal`
`--subscription-id <id>`	Azure Subscription ID	-
`--tenant-id <id>`	Azure Tenant ID	-
`--client-id <id>`	Azure Client ID (Application ID)	-
`--client-secret <secret>`	Azure Client Secret	-
`--azure-environment <env>`	`public`, `usgovernment`, `german`, `china`	`public`

Examples

Using Service Principal

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider azure \
  --azure-auth-method service_principal \
  --subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --tenant-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --client-secret your-client-secret \
  --terraform-dir infrastructure-azure/

Using Managed Identity (Self-Hosted Runner on Azure VM)

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider azure \
  --azure-auth-method managed_identity \
  --subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --runner-type self-hosted \
  --runner-id abc123def456

Using Azure Government

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider azure \
  --azure-auth-method service_principal \
  --azure-environment usgovernment \
  --subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --tenant-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --client-secret your-client-secret

Azure Authentication Methods

service_principal: Use Azure AD application credentials (works with cloud or self-hosted runners)
managed_identity: Use VM managed identity (self-hosted runners only)

GCP Authentication

Options

Option	Description	Default
`--gcp-auth-method <method>`	`service_account`, `workload_identity`	`service_account`
`--gcp-project-id <id>`	GCP Project ID	-
`--gcp-client-email <email>`	Service Account email	-
`--gcp-private-key <key>`	Service Account private key (PEM)	-
`--gcp-json-file <path>`	Path to Service Account JSON key file	-

Examples

Using Service Account JSON File (Recommended)

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider gcp \
  --gcp-auth-method service_account \
  --gcp-json-file /path/to/service-account.json \
  --terraform-dir infrastructure-gcp/

Using Service Account Credentials Directly

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider gcp \
  --gcp-auth-method service_account \
  --gcp-project-id my-project-id \
  --gcp-client-email terraform@my-project.iam.gserviceaccount.com \
  --gcp-private-key "$(cat key.pem)"

Using Workload Identity (Self-Hosted Runner on GCE/GKE)

bash

controlinfra repos add myorg/infrastructure \
  --cloud-provider gcp \
  --gcp-auth-method workload_identity \
  --gcp-project-id my-project-id \
  --runner-type self-hosted \
  --runner-id abc123def456

GCP Authentication Methods

service_account: Use JSON key file (works with cloud or self-hosted runners)
workload_identity: Use GCE/GKE attached service account (self-hosted runners only)

Assigning to Workspaces

Workspaces help organize repositories by cloud provider and environment.

bash

# Add repo to a specific workspace
controlinfra repos add myorg/infrastructure \
  --workspace <workspace-id> \
  --cloud-provider aws \
  --access-key AKIAXXXXXXXX \
  --secret-key wJalrXXXXXXXX

TIP

When using the web UI, you can only select workspaces that match the selected cloud provider.

Repository Details

Get detailed information about a repository:

bash

controlinfra repos info <repository-id>

Output:

┌──────────────────────────────────────────────────────────┐
│ Repository Details                                        │
├──────────────────────────────────────────────────────────┤
│ Name:         myorg/infrastructure                        │
│ Branch:       main                                        │
│ Terraform:    terraform/                                  │
│ Schedule:     daily                                       │
│ Status:       completed                                   │
│ Last Scan:    2 hours ago                                 │
│ Created:      3 days ago                                  │
└──────────────────────────────────────────────────────────┘

Note: You can use partial IDs (last 8 characters) for most commands.

Repository Statistics

View statistics for a repository:

bash

controlinfra repos stats <repository-id>

Output:

┌──────────────────────────────────────────────────────────┐
│ Repository Statistics                                     │
├──────────────────────────────────────────────────────────┤
│ Total Scans:      45                                      │
│ Successful:       42                                      │
│ Failed:           3                                       │
│ Total Drifts:     28                                      │
│ Open Drifts:      5                                       │
│ Resolved:         23                                      │
└──────────────────────────────────────────────────────────┘

Remove a Repository

Delete a repository configuration:

bash

controlinfra repos remove <repository-id>

You'll be prompted to confirm. Use --force to skip confirmation:

bash

controlinfra repos remove <repository-id> --force

WARNING

Removing a repository will also delete all associated scan history and drift data.

JSON Output

Get output as JSON for scripting:

bash

controlinfra repos list --json

json

[
  {
    "_id": "a1b2c3d4",
    "repository": {
      "fullName": "myorg/infrastructure",
      "owner": "myorg",
      "name": "infrastructure"
    },
    "cloudProvider": "aws",
    "branch": "main",
    "terraformDir": "terraform/",
    "lastScanStatus": "completed",
    "lastScanAt": "2024-01-15T10:30:00Z"
  }
]

Cloud Provider Comparison

Feature	AWS	Azure	GCP
Auth Methods	credentials, instance_profile, assume_role	service_principal, managed_identity	service_account, workload_identity
Credential Storage	Access Key + Secret Key	Client ID + Client Secret	JSON Key File
IAM Integration	Instance Profile, Assume Role	Managed Identity	Workload Identity
Self-Hosted Required	For instance_profile, assume_role	For managed_identity	For workload_identity

Next Steps

Workspaces - Organizing repositories
Scans - Running and managing scans
Drifts - Working with detected drifts

Repositories ​

List Repositories ​

Filter by Workspace ​

Add a Repository ​

Common Options ​

AWS Authentication ​

Options ​

Examples ​

Using AWS Credentials ​

Using Instance Profile (Self-Hosted Runner on EC2) ​

Using Assume Role (Cross-Account) ​

Azure Authentication ​

Options ​

Examples ​

Using Service Principal ​

Using Managed Identity (Self-Hosted Runner on Azure VM) ​

Using Azure Government ​

GCP Authentication ​

Options ​

Examples ​

Using Service Account JSON File (Recommended) ​

Using Service Account Credentials Directly ​

Using Workload Identity (Self-Hosted Runner on GCE/GKE) ​

Assigning to Workspaces ​

Repository Details ​

Repository Statistics ​

Remove a Repository ​

JSON Output ​

Cloud Provider Comparison ​

Next Steps ​

Repositories

List Repositories

Filter by Workspace

Add a Repository

Common Options

AWS Authentication

Options

Examples

Using AWS Credentials

Using Instance Profile (Self-Hosted Runner on EC2)

Using Assume Role (Cross-Account)

Azure Authentication

Options

Examples

Using Service Principal

Using Managed Identity (Self-Hosted Runner on Azure VM)

Using Azure Government

GCP Authentication

Options

Examples

Using Service Account JSON File (Recommended)

Using Service Account Credentials Directly

Using Workload Identity (Self-Hosted Runner on GCE/GKE)

Assigning to Workspaces

Repository Details

Repository Statistics

Remove a Repository

JSON Output

Cloud Provider Comparison

Next Steps