Create wiki page 'Troubleshooting'

Troubleshooting.md

@@ -0,0 +1,106 @@
+# 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:
+  ```hcl
+  #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:
+
+```yaml
+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