skills.rest
learntocloud
learntocloudOFFICIAL
Explore all skills by this author →
Websiteđť•Ź@learntocloudGitHub

debug-deploy

Diagnose GitHub Actions deployment, Terraform, and Azure authorization failures.

801|25|Updated Jan 10, 2026
Search Tags:#Azure#terraform#Deployment#Debugging#OIDC#ci/CD#GitHub actions
One-click install
npx skills add https://github.com/learntocloud/learn-to-cloud-app --skill debug-deploy
Or copy as Structured Prompt for Agentâ–Ľ
Please help me install this Agent Skill.
Skill: debug-deploy
Source: https://github.com/learntocloud/learn-to-cloud-app/tree/main/.github/skills/debug-deploy
Command: npx skills add https://github.com/learntocloud/learn-to-cloud-app --skill debug-deploy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deployment pipelines fail for many reasons—Terraform state locks, Azure OIDC authorization errors, drift between configuration and cloud resources, failing migration jobs, or quota limits—and finding the root cause is slow and error-prone. This Skill provides a structured diagnostic workflow for the deploy.yml GitHub Actions pipeline so failures are resolved from evidence rather than guesswork.

Core Features & Use Cases

  • Failed Run Inspection: Uses gh run list and gh run view --log-failed to gather evidence from the failing step before any code or infrastructure change.
  • Targeted Diagnostic Paths: Covers Terraform locks, Azure/OIDC authorization and RBAC, configuration drift, Container Apps migration jobs, failing tests, and Azure quota or platform issues.
  • Safe Remediation Guardrails: Requires explicit confirmation before force-unlocking state, applying Terraform, mutating state, or changing production access.
  • Use Case: A deploy.yml run fails with a Terraform state lock error. The Skill guides you to identify the lock owner and active workflows, confirm the lock is stale with the user, and only then unlock the exact lock ID.

Quick Start

Ask the assistant to diagnose why the latest deploy.yml GitHub Actions run failed and identify the root cause.

Frequently Asked Questions about debug-deploy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a failed GitHub Actions deployment workflow?â–Ľ

Use `gh run list --workflow=deploy.yml` to find the relevant run, then inspect it with `gh run view <id> --log-failed`. Diagnose the evidence from the failed step before changing any code or infrastructure.

How do I resolve a Terraform state lock error in a pipeline?â–Ľ

First identify the lock owner and check for active workflows that may legitimately hold it. Never force-unlock until the user confirms the lock is stale and authorizes the exact lock ID.

Why does Azure OIDC authentication fail in GitHub Actions?â–Ľ

OIDC failures usually come from misconfigured repository variables or secrets, an incorrect federated credential subject, missing Azure RBAC role assignments, or insufficient Microsoft Graph permissions. Verify each of these against the error evidence.

How do I troubleshoot a failed database migration job on Azure Container Apps?â–Ľ

Inspect the Container Apps Job execution and its logs, then verify the container image, command, managed identity, PostgreSQL role mapping, and environment variables. Each of these is a common failure point for migration jobs.

When is it safe to rerun a failed deployment without changes?â–Ľ

Rerun unchanged code only for a demonstrated transient failure, such as a confirmed Azure platform or quota issue. Otherwise fix the root cause, run the relevant local gate, and push the fix through a PR.

What should I do when Terraform reports drift or resources not found?â–Ľ

Compare the configuration, state file, and actual Azure resources to understand the discrepancy. Do not refresh, import, or recreate resources speculatively, as that can destroy or orphan infrastructure.

Related Skills

Explore More Software Engineering Skills→
ivegamsftivegamsft

environment-bootstrap

Automate Azure environment setup for CI/CD pipelines with OIDC federation.

Community
Advanced
GenEducationGenEducation

land-and-deploy

Merge a pull request, wait for CI and deployment, and verify production health with canary checks.

Official
Advanced
qprjack86qprjack86

azure-diagnostics

Diagnose Azure Container Apps and Function Apps failures using KQL, Azure Monitor, and resource health checks.

Community
Advanced
nsuberinsuberi

debug-workflow

Diagnose GitHub Actions workflow failures using gh run logs and local reproduction commands.

Community
Advanced