# Github Actions Debugging

> Debug and fix GitHub Actions CI/CD failures Use when this capability is needed.

- Skill: `tomevault-io/github-actions-debugging` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/github-actions-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/github-actions-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/github-actions-debugging

---


# GitHub Actions Debugging Skill

## Overview

Diagnose and fix GitHub Actions workflow failures with systematic checks.

## Usage

```
/github-actions-debugging
```

## Identity
**Role**: DevOps Engineer
**Objective**: Analyze failed workflow runs and implement fixes to get the build Green.

## Diagnostic Playbook

### Step 1: Log Retrieval
**Action**: If run locally, replicate the failure. If remote, read the `gh run view` logs.
**Keywords to Search**:
- `Process completed with exit code 1`
- `npm ERR!`
- `Module not found`
- `Permission denied`

### Step 2: Context Analysis
- **Env**: Is the Runner Ubuntu-latest? Node version mismatch?
- **Secrets**: Are secrets missing? (Logs show `***` or empty values).
- **Paths**: Is the working directory correct? (`working-directory: ./frontend`).

### Step 3: Local Reproduction
Do not code blindly. Try to run the exact command locally.
- If `npm test` failed in CI -> Run `npm test` locally.
- If it works locally but fails in CI -> Check **Node Versions** or **Missing Artifacts** (unaccounted generated files).

## Common Fixes

### 1. Dependency Caching
**Issue**: Build slow or failing on install.
**Fix**:
```yaml
- uses: actions/setup-node@v3
  with:
    cache: 'npm'
```

### 2. Flaky Tests
**Issue**: Test fails randomly.
**Fix**: Mark as flaky, improve wait logic, or increase timeout.

### 3. Missing Perms
**Issue**: `403` on Push/Release.
**Fix**: `permissions: write-all` or specific scopes in YAML.

## Workflow
**Command**: `/debug-action <run-id>`
1.  Read logs.
2.  Hypothesize root cause.
3.  Propose YAML fix or Code fix.
4.  Commit with message `ci: fix workflow failure`.

## Outputs

- CI/CD failure analysis and remediation summary.

## Related Skills

- `/deploy` - Deployment workflow checks

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/etroxtaran) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->