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

Install GitHub CLI

winget install GitHub.cli # Windows brew install gh # macOS

Authenticate

gh auth login

Verify

gh auth status

1. Bulk Issue Sync (publish_issues.ps1)

Location: $env:USERPROFILE.gemini\antigravity\skills\github-ops\scripts\publish_issues.ps1

[!TIP] The script auto-detects the repository from the current working directory. Just cd to your project folder before running.

Features

Feature Description

Smart Sync Only processes files that changed since last run (uses .issue-sync-state.json )

Auto-Close Closes issue when all checkboxes (- [x] ) are ticked

Auto-Archive Moves completed .md files to closed/ subfolder

Natural Sort Processes Issue_1, Issue_2... Issue_10 (not 1, 10, 11)

Date Sync Sets Start/Target dates on GitHub Projects

Required Flags

Flag Required? Description

(none)

Creates new issues only (skips existing)

-Update

For sync Updates existing issues

-AutoArchive

Optional Moves completed issues to closed/ folder

-DryRun

Optional Preview mode - no changes made

-Force

Optional Bypass change detection, sync all files

Project Date Sync Flags (ALL required with -SyncDates)

Flag Description How to Get

-SyncDates

Enable date sync Just add the flag

-ProjectNumber

Project board number gh project list --owner USERNAME

-ProjectId

Project node ID See below

-StartDateFieldId

Start Date field ID See below

-TargetDateFieldId

Target Date field ID See below

How to Get Project IDs

1. List projects to get project number

gh project list --owner USERNAME

2. Get field IDs (replace NUMBER with project number)

gh project field-list NUMBER --owner USERNAME --format json

Look for "Start Date" and "Target Date" in the JSON output. If they don't exist:

gh project field-create NUMBER --owner USERNAME --name "Start Date" --data-type DATE gh project field-create NUMBER --owner USERNAME --name "Target Date" --data-type DATE

Agent Protocol: Before Running This Script

ALWAYS ask the user:

"Do you want to sync to a GitHub Project with dates?"

• If YES → Need all project IDs

• If NO → Skip -SyncDates flag

"Should completed issues be archived to a closed/ subfolder?"

• If YES → Add -AutoArchive

"First run or update existing?"

• First run → No flags needed (or just -AutoArchive )

• Update → Add -Update

ALWAYS run with -DryRun first to preview changes.

Example Commands

Basic: Create new issues only

powershell -ExecutionPolicy Bypass -File .agent/skills/github-ops/scripts/publish_issues.ps1

Dry run preview

powershell -ExecutionPolicy Bypass -File .agent/skills/github-ops/scripts/publish_issues.ps1 -Update -DryRun

Update + archive completed

powershell -ExecutionPolicy Bypass -File .agent/skills/github-ops/scripts/publish_issues.ps1 -Update -AutoArchive

Full sync with project dates

powershell -ExecutionPolicy Bypass -File .agent/skills/github-ops/scripts/publish_issues.ps1 -Update -AutoArchive -SyncDates -ProjectNumber 7 -ProjectId "PVT_xxx" -StartDateFieldId "PVTF_xxx" ` -TargetDateFieldId "PVTF_yyy"

2. Bulk Add Issues to Project

To quickly add all existing issues to a project (faster than using the sync script):

Get issue numbers first

$issues = gh issue list --repo OWNER/REPO --state all --limit 500 --json number | ConvertFrom-Json

Add each to project

$issues | ForEach-Object { gh project item-add PROJECT_NUMBER --owner OWNER --url "https://github.com/OWNER/REPO/issues/$($_.number)" }

3. 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"

Delete issue gh issue delete 42 --yes

List labels gh label list

Create label gh label create "priority:high" --color "FF0000"

List projects gh project list --owner OWNER

Get project fields gh project field-list NUMBER --owner OWNER --format json

Add to project gh project item-add NUMBER --owner OWNER --url ISSUE_URL

4. Supported Issue Markdown Formats

Format A: YAML Frontmatter (Recommended)

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

Acceptance Criteria

• AC1
• AC2

Format B: Bold Markdown

Title: [Feature] Clear Issue Title Labels: enhancement, priority-high

Acceptance Criteria

• AC1

Format C: Markdown Headers

Title

[Feature] Clear Issue Title

Labels

enhancement, priority-high

5. Label System Setup

Priority

gh label create "priority-critical" --color "b60205" gh label create "priority-high" --color "d93f0b" gh label create "priority-medium" --color "fbca04" gh label create "priority-low" --color "0e8a16"

Type

gh label create "type-feature" --color "0e8a16" gh label create "type-bug" --color "d73a4a" gh label create "type-refactor" --color "a2eeef"

Scope

gh label create "MUS" --color "5319e7" --description "Minimum Usable Scope" gh label create "future-scope" --color "bfdadc"

6. Troubleshooting

Issue Cause Solution

gh: command not found

CLI not installed winget install GitHub.cli

authentication required

Not logged in gh auth login

Quote errors in titles Special chars Script auto-replaces " with '

"No files changed" Already synced Use -Force flag

Project commands fail Wrong IDs Run gh project field-list

Rate limiting Too many API calls Wait or use -DryRun