github-actions-terraform

用途

GitHub Actions Terraform Debugging Skill 是一个用于调试和修复失败的 Terraform GitHub Actions 工作流的技能，主要针对 Azure 基础设施部署场景。当 CI/CD 流水线出现失败、Terraform 管道出现问题或需要排查认证与 plan/apply 流程故障时，可以使用该技能。

适用场景

调试失败的 Terraform CI/CD 流水线
排查 GitHub Actions 中的认证问题
修复 plan/apply 工作流失败
优化 Terraform 工作流性能
搭建新的 Terraform 流水线

常见工作流失败与修复

1. 认证失败

推荐使用 OIDC/联合凭据方式登录 Azure，示例配置使用 azure/login@v2，并传入 client-id、tenant-id、subscription-id 三个 secrets。

常见问题包括：联合凭据配置缺失或错误、audience 设置错误、仓库/分支限制不匹配。

修复方式为创建联合凭据，示例命令：

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. 状态后端错误

状态锁错误（Error acquiring the state lock）可通过以下命令修复：

terraform force-unlock <LOCK_ID>

状态访问被拒绝时，需要检查：存储账户是否存在、RBAC 权限（Storage Blob Data Contributor）、容器是否存在、网络访问（如使用私有终结点）。

3. Provider 初始化失败

当出现 Failed to query available provider packages 错误时，可使用 hashicorp/setup-terraform@v3 并指定 terraform_version，然后执行 terraform init -upgrade，同时可设置环境变量 ARM_SKIP_PROVIDER_REGISTRATION 为 true。

4. Plan/Apply 失败

资源已存在时，可使用 terraform import 导入资源，例如：

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

调试步骤

启用调试日志：设置环境变量 TF_LOG 为 DEBUG，TF_LOG_PATH 为 terraform.log。
检查 Azure 上下文：运行 az account show 和 az account list-locations -o table。

最佳实践

使用 OIDC，避免长期有效的密钥
固定版本：Terraform、Provider、Actions
使用 environments 实现审批门禁
缓存 Provider 以加速运行
将 plan 作为 artifact，确保 apply 使用完全一致的 plan
最小权限：为服务主体分配最小权限

限制

资料中未提供该技能的具体安装方式、支持的平台范围、收费或价格信息，也未提供完整的参考指南内容。