# github-ops

> GitHub automation patterns - issues, projects, labels. Includes smart-ops scripts and bulk issue sync.

- Author: JStaRFilms
- Repository: JStaRFilms/YouTube_Content_Engine
- Version: 20260125221746
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/JStaRFilms/YouTube_Content_Engine
- Web: https://mule.run/skillshub/@@JStaRFilms/YouTube_Content_Engine~github-ops:20260125221746

---

---
name: github-ops
description: GitHub automation patterns - issues, projects, labels. Includes smart-ops scripts and bulk issue sync.
---

# GitHub Ops Skill

Complete GitHub automation toolkit using the `gh` CLI. Covers issue management, project boards, label systems, and bulk operations.

## When to Use
- User mentions "GitHub issues", "project board", or "gh cli"
- Setting up automation for a new repo
- Bulk-creating issues from markdown specs
- Managing GitHub Projects (v2)

## Prerequisites

```bash
# Install GitHub CLI
winget install GitHub.cli   # Windows
brew install gh             # macOS

# Authenticate
gh auth login

# Verify
gh auth status
```

---

## 1. Quick Commands Reference

| Task | Command |
|------|---------|
| List issues | `gh issue list` |
| Create issue | `gh issue create --title "X" --body "Y" --label "bug"` |
| Close issue | `gh issue close 42 --comment "Fixed"` |
| List labels | `gh label list` |
| Create label | `gh label create "priority:high" --color "FF0000"` |
| List projects | `gh project list --owner OWNER` |
| View repo | `gh repo view --json owner,name,url` |

---

## 2. Bulk Issue Sync (from Markdown)

When the user has a folder like `docs/issues/` with pre-written issue specs:

### Supported Formats

The script supports **two formats** for issue metadata:

#### Format A: YAML Frontmatter (Recommended)

```markdown
---
title: "[Feature] Clear Issue Title"
labels: enhancement, priority:high, module-name
---

## User Story
As a [user], I want [feature], so that [benefit].

## Proposed Solution
Technical approach...

## Acceptance Criteria
- [ ] AC1
- [ ] AC2
```

#### Format B: Markdown Headers (Legacy)

```markdown
# GitHub Issue: FR-001 Feature Name

## Title
[Feature] Clear Issue Title

## Labels
`enhancement`, `priority:high`, `module-name`

## User Story
As a [user], I want [feature], so that [benefit].
```

### PowerShell Sync Script

See: [publish_issues.ps1](file:///C:/Users/johno/.gemini/antigravity/skills/github-ops/scripts/publish_issues.ps1)

**Modes:**
| Flag | Behavior |
|------|----------|
| (default) | Skip if issue with same title exists |
| `-Update` | Update existing issue body instead of skipping |
| `-DryRun` | Preview without making changes |

```powershell
# Dry run (always do this first)
powershell -ExecutionPolicy Bypass -File scripts/publish_issues.ps1 -DryRun

# Create new issues only (skip existing)
powershell -ExecutionPolicy Bypass -File scripts/publish_issues.ps1

# Sync local changes back to GitHub
powershell -ExecutionPolicy Bypass -File scripts/publish_issues.ps1 -Update
```

> [!TIP]
> After ticking checkboxes in your local `.md` files, run with `-Update` to sync progress to GitHub.

---

## 3. Smart Ops Scripts

Full-featured automation scripts for daily GitHub workflow.

### Features
- `start` — Scan open issues and project items
- `complete` — List issues ready for closure
- `create` — Create issue with auto-dates (start/target)
- `close` — Close issue with comment
- `progress` — Move project item to "In Progress"
- `done` — Move project item to "Done"

### Templates

| Script | Location |
|--------|----------|
| PowerShell | [smart-ops.ps1](file:///C:/Users/johno/.gemini/antigravity/skills/github-ops/scripts/smart-ops.ps1) |
| Bash | [smart-ops.sh](file:///C:/Users/johno/.gemini/antigravity/skills/github-ops/scripts/smart-ops.sh) |

### Configuration Variables

When generating scripts, replace these placeholders:

| Placeholder | Source |
|-------------|--------|
| `{{OWNER}}` | `gh repo view --json owner -q .owner.login` |
| `{{REPO}}` | `gh repo view --json name -q .name` |
| `{{PROJECT_NUMBER}}` | `gh project list --owner OWNER` |
| `{{PROJECT_ID}}` | `gh project field-list NUM --owner OWNER --format json` |
| `{{STATUS_FIELD_ID}}` | Parse from field-list JSON |
| `{{TODO_OPTION_ID}}` | Parse Status field options |
| `{{IN_PROGRESS_OPTION_ID}}` | Parse Status field options |
| `{{DONE_OPTION_ID}}` | Parse Status field options |

---

## 4. Label System Setup

Recommended label taxonomy:

```bash
# Type
gh label create "type:feature" --color "0e8a16" --description "New feature"
gh label create "type:bug" --color "d73a4a" --description "Bug fix"
gh label create "type:refactor" --color "a2eeef" --description "Code improvement"

# Priority
gh label create "priority:critical" --color "b60205" --description "P0 - Drop everything"
gh label create "priority:high" --color "d93f0b" --description "P1 - This sprint"
gh label create "priority:medium" --color "fbca04" --description "P2 - Next sprint"
gh label create "priority:low" --color "0e8a16" --description "P3 - Backlog"

# Status (if not using Projects)
gh label create "status:blocked" --color "000000" --description "Waiting on external"
gh label create "status:needs-review" --color "5319e7" --description "Ready for review"
```

---

## 5. AI Agent Protocol

### For Bulk Issue Sync
1. `gh auth status` — Verify authentication
2. `ls docs/issues/` — Confirm files exist
3. View one file to verify format
4. Run with `-DryRun` first
5. Execute for real
6. `gh issue list` — Verify creation

### For Smart Ops Setup
1. Detect OS (PowerShell vs Bash)
2. `gh repo view` — Get owner/repo
3. Ask user: "Enable GitHub Projects integration? (y/N)"
4. If yes, fetch project field IDs
5. Generate script with replaced placeholders
6. Test with `start` command

---

## 6. Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| `could not add label: 'X' not found` | Label doesn't exist | Use `Ensure-Label` function |
| `gh: command not found` | CLI not installed | Install with `winget` or `brew` |
| `no open issues` | Wrong repo context | Run `gh repo view` to verify |
| `authentication required` | Not logged in | Run `gh auth login` |
| Project commands fail | Wrong project number | Verify with `gh project list` |