gh-cli.md
1 # 📋 GitHub CLI Commands for Project Management 2 3 This document provides a quick reference for essential GitHub CLI (`gh`) commands used to manage issues, workflows, and interact with the repository. These commands are particularly useful for maintaining project health, tracking progress, and automating tasks. 4 5 ## 🔑 Authentication & Authorization 6 7 Before using `gh` commands that interact with private repositories or require elevated permissions (like adding issues to projects), ensure you are properly authenticated. 8 9 * **Refresh Authorization Scopes**: 10 11 ```bash 12 gh auth refresh -s project 13 ``` 14 *Purpose*: Updates your GitHub CLI authentication to include the `project` scope, necessary for managing issues within GitHub Projects. 15 16 ## 📝 Issue Management 17 18 GitHub Issues are used for tracking bugs, features, and tasks. Effective issue management is crucial for project organization and collaboration. 19 20 ### List & View Issues 21 22 * **List Issues by Status and Labels**: 23 24 ```bash 25 gh issue list --state open --label bug 26 gh issue list --state open --label "status: needs-verification" 27 gh issue list --state open --label enhancement 28 gh issue list --state all --label "P1: High" 29 ``` 30 *Purpose*: Filter issues to quickly find relevant items. 31 32 * **View Specific Issue Details**: 33 34 ```bash 35 gh issue view <issue_number> # Basic details 36 gh issue view <issue_number> --comments # Include comments 37 gh issue view <issue_number> --web # Open in browser 38 gh issue view <issue_number> --json body # View raw body content (useful for grooming) 39 ``` 40 *Purpose*: Get comprehensive information about an issue. 41 42 * **Search Issues**: 43 44 ```bash 45 gh issue list --search "is:open label:ci-cd" 46 gh issue list --assignee @me 47 ``` 48 *Purpose*: Perform advanced searches across issue titles, bodies, and metadata. 49 50 * **List Available Labels**: 51 52 ```bash 53 gh label list 54 ``` 55 *Purpose*: See all predefined labels in the repository for consistent tagging. 56 57 ### Create & Update Issues 58 59 * **Create New Issues**: 60 61 ```bash 62 # Basic creation 63 gh issue create --title "fix: Critical CI failure" --body "Description" --label bug,ci-cd 64 65 # Using a template 66 gh issue create --template bug_report.md 67 68 # Using a body file for complex descriptions (recommended for grooming) 69 gh issue create --title "feat: New Feature" --body-file /path/to/temp/issue_body.txt --label "enhancement,P1: High" 70 ``` 71 *Purpose*: Log new bugs, features, or tasks. 72 73 * **Update Existing Issues**: 74 75 ```bash 76 # Add/remove labels 77 gh issue edit <issue_number> --add-label "status: in-progress" 78 gh issue edit <issue_number> --remove-label "status: needs-verification" 79 80 # Assign/unassign people 81 gh issue edit <issue_number> --assignee @me 82 gh issue edit <issue_number> --remove-assignee monalisa 83 84 # Set milestone 85 gh issue edit <issue_number> --milestone "v2.1" 86 87 # Update issue body from file (useful for grooming) 88 gh issue edit <issue_number> --body-file /path/to/temp/updated_body.txt 89 ``` 90 *Purpose*: Modify issue details, status, and assignments. 91 92 * **Comment on Issues**: 93 94 ```bash 95 # Simple comment 96 gh issue comment <issue_number> --body "Working on this fix" 97 98 # Comment with content from a file (recommended for detailed updates) 99 gh issue comment <issue_number> --body-file /path/to/temp/comment_text.txt 100 ``` 101 *Purpose*: Provide updates, ask questions, or add context to an issue. 102 103 * **Close Issues**: 104 105 ```bash 106 gh issue close <issue_number> --reason "completed" --comment "Resolved in PR #X" 107 # Reasons: completed | not planned 108 ``` 109 *Purpose*: Mark an issue as resolved or no longer relevant. 110 111 ## 🚀 Workflow & CI Commands 112 113 These commands help monitor and manage GitHub Actions workflows, which automate the CI/CD pipeline. 114 115 * **Check Workflow Status**: 116 117 ```bash 118 gh workflow list 119 gh run list --limit 10 120 gh run view <run-id> --log 121 ``` 122 *Purpose*: Monitor the status and logs of CI/CD runs. 123 124 * **Trigger Workflows**: 125 126 ```bash 127 gh workflow run cv-enhancement.yml 128 gh workflow run activity-tracker.yml --ref main 129 ``` 130 *Purpose*: Manually trigger workflows for testing or on-demand execution. 131 132 * **Cancel Failed Runs**: 133 134 ```bash 135 gh run cancel <run-id> 136 ``` 137 *Purpose*: Stop a running or queued workflow run.