메뉴
Debug GitHub Actions workflow failures and Terraform errors. Use when deployment failed, Terraform state lock, CI/CD pipeline errors, or troubleshooting deploy.yml.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Undo local submissions for DevOps and Verify Journal API Implementation so you can re-test verification flows. Also supports custom requirement slugs and user scoping. Use when user says "reset local submissions", "undo local verification", "reset phase X locally", or "let me re-test verification".
Reset verification submissions for a user in production. Use when user says "reset prod submissions", "reset phase X in prod", "undo prod verification", or "reset prod for <username>".
Check Azure production health: app status, errors, latency, database, dependencies. Use when user says "check prod", "how's prod", "hows prod doing", "is prod up", "prod status", "health check", "any errors?", "how's the app doing?", or "check Azure".
Query production PostgreSQL with Entra ID auth, for investigating users, debugging duplicates, or ad-hoc queries. Use when user says "query prod db", "check prod database", "look up a user in prod", "run a query against production", or "investigate prod data".
Review comments on an active pull request and decide whether to accept, iterate, or reject the changes suggested in each comment. Use when user says "review PR comments", "address review comments", "go through the PR feedback", or "handle the comments on my PR".
Run the quality gate (lint, type-check, tests), resolve issues, commit, push, open a PR to main, then monitor the deploy workflow after merge and resolve any deploy failures. Use when user says "ship it", "commit and deploy", "push and deploy", or "land this".
| name | debug-deploy |
| description | Debug GitHub Actions workflow failures and Terraform errors. Use when deployment failed, Terraform state lock, CI/CD pipeline errors, or troubleshooting deploy.yml. |
This skill helps diagnose and fix issues with the GitHub Actions deploy workflow for the Learn to Cloud app.
gh run list --workflow=deploy.yml --limit 5
gh run view <run-id> --log-failed
Or use the debug script in this skill's folder:
.github/skills/debug-deploy/scripts/debug-deploy.sh logs
Look for these common patterns in the logs:
Pattern: Error acquiring the state lock or state blob is already locked
Cause: Previous workflow was cancelled mid-execution, leaving the state locked.
Fix:
efd4cede-d5a2-61c3-31db-462852989510)cd infra && terraform force-unlock -force <lock-id>gh run rerun <run-id>Pattern: AuthorizationFailed, AADSTS, unauthorized
Fix: Check the OIDC deployment configuration: AZURE_CLIENT_ID and AZURE_TENANT_ID secrets, plus the AZURE_SUBSCRIPTION_ID repository variable. The federated credential or Azure RBAC assignment may need updating.
Pattern: ResourceNotFound or does not exist
Fix: Resource was deleted outside Terraform. Run terraform refresh or re-import.
Pattern: QuotaExceeded
Fix: Request quota increase in Azure portal or clean up unused resources.
Pattern: Run database migrations fails, /ready returns 503 after deploy, or Alembic reports a database error.
Cause: The Azure Container Apps migration job failed before the API image was updated. Common causes are missing PostgreSQL role mapping, migration SQL errors, or job image/env override issues.
Fix:
migration_identity_principal_id is mapped to the Terraform migration_postgres_role output in PostgreSQL.az containerapp job start passes the SHA image, alembic upgrade head, DB env vars, AZURE_CLIENT_ID, and --registry-identity.alembic/env.py still uses psycopg2 and acquires the advisory lock before migrations.Pattern: FAILED, pytest, AssertionError
Fix: Run tests locally: (cd api && uv run pytest tests/ -v) and (cd packages/learn-to-cloud-shared && uv run pytest tests/ -v)
Pattern: ruff, lint error
Fix: Run linter locally: (cd api && uv run ruff check . ../packages/learn-to-cloud-shared)
After fixing the issue:
gh run rerun <run-id>
Or watch the progress:
gh run watch <run-id>
| Command | Description |
|---|---|
./.github/skills/debug-deploy/scripts/debug-deploy.sh status | Show recent workflow runs |
./.github/skills/debug-deploy/scripts/debug-deploy.sh logs | View and analyze failed logs |
./.github/skills/debug-deploy/scripts/debug-deploy.sh logs <id> | View specific run's failed logs |
./.github/skills/debug-deploy/scripts/debug-deploy.sh unlock | Fix Terraform state lock |
./.github/skills/debug-deploy/scripts/debug-deploy.sh rerun | Re-run most recent failed workflow |
./.github/skills/debug-deploy/scripts/debug-deploy.sh watch | Watch running workflow |
The debug-deploy.sh script automates the debugging process with automated issue detection.
The workflows are configured with these safeguards:
cancel-in-progress: true - Cancels in-progress runs when a new push arrives (in deploy.yml)-lock-timeout=120s - Waits for locks instead of failing immediately (in deploy.yml terraform job)