1

Troubleshooting

gitea-admin edited this page 2025-10-29 07:31:36 +00:00

Table of Contents

• Troubleshooting Guide
• Common Issues
• Pipeline Failures
• Authentication Issues
• Backend Problems
• Security Scan Issues
• Artifact Issues
• Environment & Approval Issues
• Quick Fixes
• Debug Mode
• Getting Help

Troubleshooting Guide

Common Issues

Pipeline Failures

** ❌ Terraform format check failed**

• Cause: Code not formatted correctly
• Fix: Run terraform fmt -recursive locally and commit

❌ Terraform validate failed

• Cause: Syntax errors in Terraform code
• Fix: Run terraform validate locally and fix reported errors

┌ Workflow file not found

• Cause: Workflow file in wrong location
• Fix: Must be in .gitea/workflows/terraform.yml

Authentication Issues

❌ AWP Certificates not configured

• Cause: Missing or incorrect secrets
• Fix:
  1. Go to Settings → Secrets → Actions
  2. Add: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
  3. Uncomment credentials in workflow (lines 103-104)

┌ Azure authentication failed

• Cause: Missing ARM variables
• Fix: Add all 4 secrets: ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID, ARM_TENANT_ID

❌ GCP authentication failed

• Cause: Missing or invalid GCP credentials
• Fix: Add GCP_CREDENTIALS secret with full JSON service account key

Backend Problems

❌ Backend initialization failed

• Cause: Incorrect backend configuration or credentials
• Fix:
  1. Verify backend configuration in Terraform code
  2. Check backend bucket/container exists
  3. Verify BACKEND_ACCESS_KEY and BACKEND_SECRET_KEY secrets

┌ State file locked

• Cause: Previous operation didn't release lock
• Fix: Run terraform force-unlock <LOCK_ID> (with ID from error message)

Security Scan Issues

❌ Checkov/tfsec found security issues

• Fix 1: Fix the security issue (recommended)
• Fix 2: Suppress specific check with justification:

  #checkov:skip=CKV_AWS_20:MFA delete not required for dev environment
  

• Fix 3: Set soft_fail: true in workflow (not recommended for production)

Artifact Issues

❌ Artifact not found

• Cause: Artifacts expired or plan stage failed
• Fix: Re-run plan stage

Environment & Approval Issues

❌ Environment not found

• Cause: Environment not created in Gitea
• Fix:
  1. Go to Settings → Environments
  2. Create production environment
  3. Add required reviewers
  4. Set deployment branch to main

┌ No one can approve

• Cause: No reviewers configured
• Fix: Add reviewers to environment in Settings → Environments → production

Quick Fixes

Error	Quick Fix
No valid credentials	Add provider secrets to repository
Backend init failed	Check backend configuration & credentials
State locked	Run terraform force-unlock <LOCK_ID>
Plan file stale	Re-run plan stage
Artifact not found	Re-run plan stage
Environment not found	Create environment in Settings
Formatting failed	Run terraform fmt -recursive

Debug Mode

Enable debug output in workflow:

env:
  TF_LOG: DEBUG  # TRACE, DEBUG, INFO, WARN, ERROR

Getting Help

1. Check workflow logs in Actions tab
2. Run terraform validate locally
3. Verify secrets are configured
4. Check backend access
5. Review Terraform documentation