GitHub Actions Terraform Debugging Skill

This skill helps you debug and fix failing Terraform GitHub Actions workflows for Azure infrastructure deployments.

When to Use This Skill

• Debugging failing Terraform CI/CD pipelines
• Troubleshooting authentication issues in GitHub Actions
• Fixing plan/apply workflow failures
• Optimizing Terraform workflow performance
• Setting up new Terraform pipelines

Common Workflow Failures

1. Authentication Failures

OIDC/Federated Credentials (Recommended)

- name: Azure Login
  uses: azure/login@v2
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Common Issues:

• Missing or incorrect federated credential configuration
• Wrong audience setting
• Repository/branch restrictions not matching

Fix:

# Create federated credential
az ad app federated-credential create \
  --id <app-object-id> \
  --parameters '{
    "name": "github-actions",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:org/repo:ref:refs/heads/main",
    "audiences": ["api://AzureADTokenExchange"]
  }'

2. State Backend Errors

State Lock Errors

Error: Error acquiring the state lock

Fix:

terraform force-unlock <LOCK_ID>

State Access Denied

Fixes:

• Verify storage account exists
• Check RBAC permissions (Storage Blob Data Contributor)
• Verify container exists
• Check network access (if private endpoint)

3. Provider Initialization Failures

Error: Failed to query available provider packages

Fixes:

- name: Setup Terraform
  uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: "1.6.0"
    
- name: Terraform Init
  run: terraform init -upgrade
  env:
    ARM_SKIP_PROVIDER_REGISTRATION: "true"

4. Plan/Apply Failures

Resource Already Exists

Fix:

terraform import azurerm_resource_group.main /subscriptions/.../resourceGroups/rg-name

Debugging Steps

1. Enable Debug Logging

env:
  TF_LOG: DEBUG
  TF_LOG_PATH: terraform.log

2. Check Azure Context

- name: Debug Azure Context
  run: |
    az account show
    az account list-locations -o table

Best Practices

1. Use OIDC - Avoid long-lived secrets
2. Pin versions - Terraform, providers, actions
3. Use environments - For approval gates
4. Cache providers - Speed up runs
5. Artifact plans - Ensure apply uses exact plan
6. Minimal permissions - Least privilege for service principal

Additional Resources

For complete workflow templates and detailed debugging guides, see the [reference guide](references/REFERENCE.md).