Back to Details

github

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub CLI

GitHub CLI

주의 사항 (Anti-patterns)

注意事项（反模式）

1. 
gh api
사용 금지

1. 禁止使用
gh api

bash
undefined
bash
undefined

❌ gh api - 임의의 REST/GraphQL 엔드포인트 호출 가능 (권한 제어 불가)

❌ gh api - 可调用任意REST/GraphQL端点（无法控制权限）

gh api repos/{owner}/{repo}/issues gh api graphql -f query='{ viewer { login } }'
gh api repos/{owner}/{repo}/issues gh api graphql -f query='{ viewer { login } }'

✅ 구체적 서브커맨드 사용 (allowed-tools로 권한 제한 가능)

✅ 使用具体子命令（可通过allowed-tools限制权限）

gh issue list gh pr list gh release list

`gh api`는 모든 GitHub API 엔드포인트에 접근할 수 있어 `allowed-tools`로 특정 동작만 허용하는 것이 불가능하다. `gh issue`, `gh pr` 등 구체적 서브커맨드를 사용하면 `Bash(gh issue:*)` 형태로 세밀한 권한 제어가 가능하다.
gh issue list gh pr list gh release list

`gh api`可以访问所有GitHub API端点，无法通过`allowed-tools`仅允许特定操作。使用`gh issue`、`gh pr`等具体子命令时，可以通过`Bash(gh issue:*)`的形式实现精细的权限控制。

2. Write 작업 무단 수행 금지

2. 禁止擅自执行写入操作

bash
undefined
bash
undefined

❌ 사용자 확인 없이 Write 작업 수행

❌ 未经用户确认执行写入操作

gh issue create --title "Bug fix" --body "Fixed it" gh pr merge 123 gh issue close 456
gh issue create --title "Bug fix" --body "Fixed it" gh pr merge 123 gh issue close 456

✅ 사용자에게 먼저 확인 후 수행

✅ 先向用户确认再执行

"이슈를 생성할까요? 제목: Bug fix, 본문: Fixed it"

"是否创建Issue？标题: Bug fix，内容: Fixed it"

→ 사용자 승인 후 실행

→ 获得用户确认后执行

gh issue create --title "Bug fix" --body "Fixed it"

이슈 생성, PR 병합, 코멘트 작성 등 외부에 영향을 미치는 Write 작업은 반드시 사용자에게 내용을 보여주고 확인을 받은 뒤 수행한다.
gh issue create --title "Bug fix" --body "Fixed it"

创建Issue、合并PR、添加评论等会对外界产生影响的写入操作，必须先向用户展示内容并获得确认后再执行。

3. 현재 디렉토리에서 불필요한 
git -C
사용

3. 当前目录下避免不必要的
git -C
使用

bash
undefined
bash
undefined

❌ 현재 디렉토리가 대상 레포지토리인데 -C 옵션 사용

❌ 当前目录就是目标仓库却使用-C选项

git -C /path/to/current/repo log --oneline
git -C /path/to/current/repo log --oneline

✅ 현재 디렉토리에서 바로 실행

✅ 直接在当前目录执行

git log --oneline

현재 디렉토리가 작업 대상 레포지토리와 동일하면 `git -C` 옵션은 불필요한 중복이다. 다른 경로의 레포지토리를 대상으로 할 때만 사용한다.
git log --oneline

如果当前目录与操作目标仓库一致，`git -C`选项属于多余的重复。仅当操作其他路径的仓库时才使用该选项。

4. 하드코딩된 레포지토리 정보

4. 避免硬编码仓库信息

bash
undefined
bash
undefined

❌ 레포지토리 정보 하드코딩

❌ 硬编码仓库信息

gh issue list --repo DaleStudy/skills
gh issue list --repo DaleStudy/skills

✅ 현재 디렉토리의 Git 원격 정보 활용 (기본값)

✅ 利用当前目录的Git远程信息（默认行为）

gh issue list

`gh` CLI는 현재 디렉토리의 Git 원격 정보를 자동으로 감지한다. `--repo` 플래그는 다른 레포지토리를 대상으로 할 때만 사용한다.
gh issue list

`gh` CLI会自动识别当前目录的Git远程信息。仅当操作其他仓库时才使用`--repo`参数。

Read vs Write 명령어 분류

读取类与写入类命令分类

Read (안전 - 자유롭게 실행 가능)

Read（安全 - 可自由执行）

명령어설명
gh issue list
이슈 목록 조회
gh issue view {number}
이슈 상세 조회
gh issue view {number} --comments
이슈 코멘트 조회
gh issue status
관련 이슈 상태 요약
gh pr list
PR 목록 조회
gh pr view {number}
PR 상세 조회
gh pr view {number} --comments
PR 코멘트 조회
gh pr status
관련 PR 상태 요약
gh pr diff {number}
PR 변경사항 조회
gh pr checks {number}
PR CI 상태 확인
gh release list
릴리스 목록 조회
gh release view {tag}
릴리스 상세 조회
gh label list
레이블 목록 조회
gh repo view
레포지토리 정보 조회
gh search issues {query}
이슈 검색
gh search prs {query}
PR 검색
gh run list
워크플로우 실행 목록 조회
gh run view {run-id}
워크플로우 실행 상세 조회
gh run view {run-id} --log
워크플로우 실행 로그 조회
gh run view {run-id} --log-failed
실패한 스텝 로그만 조회
gh workflow list
워크플로우 목록 조회
gh workflow view {name|id}
워크플로우 상세 조회
命令说明
gh issue list
查看Issue列表
gh issue view {number}
查看Issue详情
gh issue view {number} --comments
查看Issue评论
gh issue status
查看相关Issue状态摘要
gh pr list
查看PR列表
gh pr view {number}
查看PR详情
gh pr view {number} --comments
查看PR评论
gh pr status
查看相关PR状态摘要
gh pr diff {number}
查看PR变更内容
gh pr checks {number}
查看PR CI状态
gh release list
查看Release列表
gh release view {tag}
查看Release详情
gh label list
查看标签列表
gh repo view
查看仓库信息
gh search issues {query}
搜索Issue
gh search prs {query}
搜索PR
gh run list
查看工作流执行列表
gh run view {run-id}
查看工作流执行详情
gh run view {run-id} --log
查看工作流执行日志
gh run view {run-id} --log-failed
仅查看失败步骤的日志
gh workflow list
查看工作流列表
gh workflow view {name|id}
查看工作流详情

Write (사용자 확인 필수)

Write（需用户确认）

명령어설명
gh issue create
이슈 생성
gh issue close {number}
이슈 닫기
gh issue reopen {number}
이슈 다시 열기
gh issue edit {number}
이슈 수정
gh issue comment {number}
이슈에 코멘트 작성
gh pr create
PR 생성
gh pr merge {number}
PR 병합
gh pr close {number}
PR 닫기
gh pr reopen {number}
PR 다시 열기
gh pr edit {number}
PR 수정
gh pr comment {number}
PR에 코멘트 작성
gh pr review {number}
PR 리뷰 제출
gh release create {tag}
릴리스 생성
gh release delete {tag}
릴리스 삭제
gh label create {name}
레이블 생성
gh label edit {name}
레이블 수정
gh label delete {name}
레이블 삭제
gh run rerun {run-id}
워크플로우 재실행
gh run cancel {run-id}
워크플로우 실행 취소
gh workflow run {name|id}
워크플로우 수동 실행 (workflow_dispatch)
gh workflow disable {name|id}
워크플로우 비활성화
gh workflow enable {name|id}
워크플로우 활성화
命令说明
gh issue create
创建Issue
gh issue close {number}
关闭Issue
gh issue reopen {number}
重新打开Issue
gh issue edit {number}
修改Issue
gh issue comment {number}
为Issue添加评论
gh pr create
创建PR
gh pr merge {number}
合并PR
gh pr close {number}
关闭PR
gh pr reopen {number}
重新打开PR
gh pr edit {number}
修改PR
gh pr comment {number}
为PR添加评论
gh pr review {number}
提交PR评审
gh release create {tag}
创建Release
gh release delete {tag}
删除Release
gh label create {name}
创建标签
gh label edit {name}
修改标签
gh label delete {name}
删除标签
gh run rerun {run-id}
重新执行工作流
gh run cancel {run-id}
取消工作流执行
gh workflow run {name|id}
手动执行工作流（workflow_dispatch）
gh workflow disable {name|id}
禁用工作流
gh workflow enable {name|id}
启用工作流

이슈 관리 모범 사례

Issue管理最佳实践

이슈-PR 연결

Issue-PR关联

bash
undefined
bash
undefined

PR 본문에 키워드로 이슈 자동 연결 (PR 병합 시 이슈 자동 닫힘)

在PR正文中通过关键字自动关联Issue（PR合并时自动关闭Issue）

gh pr create --title "Fix login bug" --body "Closes #123"

**연결 키워드:** `Closes`, `Fixes`, `Resolves` (대소문자 무관)
gh pr create --title "Fix login bug" --body "Closes #123"

**关联关键字：** `Closes`、`Fixes`、`Resolves`（大小写不敏感）

라벨 체계

标签体系

bash
undefined
bash
undefined

라벨 목록 확인

查看标签列表

gh label list
gh label list

라벨로 이슈 필터링

通过标签筛选Issue

gh issue list --label bug gh issue list --label "good first issue"
undefined
gh issue list --label bug gh issue list --label "good first issue"
undefined

이슈 검색

Issue搜索

bash
undefined
bash
undefined

담당자별 이슈

按负责人筛选Issue

gh issue list --assignee @me
gh issue list --assignee @me

상태별 이슈

按状态筛选Issue

gh issue list --state open gh issue list --state closed
gh issue list --state open gh issue list --state closed

조합 검색

组合搜索

gh issue list --label bug --assignee @me --state open
undefined
gh issue list --label bug --assignee @me --state open
undefined

Pull Request 모범 사례

Pull Request最佳实践

PR 생성

PR创建

bash
undefined
bash
undefined

기본 PR 생성

创建基础PR

gh pr create --title "Add user authentication" --body "## Summary
  • JWT 기반 인증 구현
  • 로그인/로그아웃 API 추가
gh pr create --title "Add user authentication" --body "## 摘要
  • 实现基于JWT的认证
  • 添加登录/登出API

Test Plan

测试计划

  • 로그인 성공/실패 테스트
  • 토큰 만료 시 갱신 테스트"
  • 登录成功/失败测试
  • 令牌过期时的刷新测试"

Draft PR 생성 (리뷰 준비가 안 된 경우)

创建Draft PR（未准备好评审时）

gh pr create --draft --title "WIP: Add user authentication"
gh pr create --draft --title "WIP: Add user authentication"

리뷰어 지정

指定评审人

gh pr create --reviewer user1,user2 --title "Add feature"
undefined
gh pr create --reviewer user1,user2 --title "Add feature"
undefined

PR 크기 가이드

PR大小指南

  • 변경된 파일 수: 10개 이하 권장
  • 변경된 라인 수: 400줄 이하 권장
  • 하나의 PR은 하나의 목적만 달성
  • 크면 나누기: 리팩토링과 기능 추가를 별도 PR로 분리
  • 修改的文件数量：建议不超过10个
  • 修改的代码行数：建议不超过400行
  • 单个PR仅实现一个目标
  • 拆分大型PR：将重构与功能添加拆分为单独的PR

PR 리뷰

PR评审

bash
undefined
bash
undefined

PR 변경사항 확인

查看PR变更内容

gh pr diff 123
gh pr diff 123

PR CI 상태 확인

查看PR CI状态

gh pr checks 123
gh pr checks 123

PR 리뷰 승인

批准PR评审

gh pr review 123 --approve
gh pr review 123 --approve

PR 리뷰 코멘트

添加PR评审评论

gh pr review 123 --comment --body "전반적으로 좋습니다. 몇 가지 제안사항이 있습니다."
gh pr review 123 --comment --body "整体很好，有一些建议。"

PR 변경 요청

请求PR修改

gh pr review 123 --request-changes --body "인증 로직에 보안 문제가 있습니다."
undefined
gh pr review 123 --request-changes --body "认证逻辑存在安全问题。"
undefined

PR 병합

PR合并

bash
undefined
bash
undefined

Squash merge (커밋 히스토리 정리, 권장)

Squash合并（整理提交历史，推荐）

gh pr merge 123 --squash
gh pr merge 123 --squash

Merge commit

Merge提交

gh pr merge 123 --merge
gh pr merge 123 --merge

Rebase merge

Rebase合并

gh pr merge 123 --rebase
gh pr merge 123 --rebase

병합 후 로컬/원격 브랜치 자동 삭제

合并后自动删除本地/远程分支

gh pr merge 123 --squash --delete-branch
undefined
gh pr merge 123 --squash --delete-branch
undefined

릴리스 관리

Release管理

시맨틱 버저닝

语义化版本

  • MAJOR (v2.0.0): 하위 호환성이 깨지는 변경
  • MINOR (v1.1.0): 하위 호환 가능한 기능 추가
  • PATCH (v1.0.1): 하위 호환 가능한 버그 수정
  • MAJOR（v2.0.0）：不兼容的变更
  • MINOR（v1.1.0）：兼容的功能新增
  • PATCH（v1.0.1）：兼容的Bug修复

릴리스 생성

创建Release

bash
undefined
bash
undefined

릴리스 노트 자동 생성

自动生成Release说明

gh release create v1.0.0 --generate-notes
gh release create v1.0.0 --generate-notes

제목과 본문 지정

指定标题和内容

gh release create v1.0.0 --title "v1.0.0" --notes "첫 번째 안정 릴리스"
gh release create v1.0.0 --title "v1.0.0" --notes "第一个稳定版本"

프리릴리스

创建预发布版本

gh release create v2.0.0-beta.1 --prerelease --generate-notes
gh release create v2.0.0-beta.1 --prerelease --generate-notes

Draft 릴리스 (바로 공개하지 않음)

创建Draft版本（不立即公开）

gh release create v1.0.0 --draft --generate-notes
undefined
gh release create v1.0.0 --draft --generate-notes
undefined

릴리스 조회

查看Release

bash
undefined
bash
undefined

최신 릴리스 확인

查看最新Release

gh release view --repo {owner}/{repo}
gh release view --repo {owner}/{repo}

릴리스 목록

查看Release列表

gh release list
gh release list

특정 릴리스 상세

查看特定Release详情

gh release view v1.0.0
undefined
gh release view v1.0.0
undefined

워크플로우 실행 및 결과 조회

工作流执行及结果查看

실행 결과 확인

查看执行结果

bash
undefined
bash
undefined

최근 워크플로우 실행 목록

查看最近的工作流执行列表

gh run list
gh run list

특정 워크플로우만 필터링

仅筛选特定工作流

gh run list --workflow ci.yml
gh run list --workflow ci.yml

실행 상세 정보 (상태, 소요 시간, 트리거 등)

查看执行详情（状态、耗时、触发器等）

gh run view {run-id}
gh run view {run-id}

실패한 스텝의 로그만 확인 (디버깅에 유용)

仅查看失败步骤的日志（便于调试）

gh run view {run-id} --log-failed
gh run view {run-id} --log-failed

전체 로그 확인

查看完整日志

gh run view {run-id} --log
undefined
gh run view {run-id} --log
undefined

워크플로우 수동 실행

手动执行工作流

bash
undefined
bash
undefined

workflow_dispatch 이벤트가 설정된 워크플로우 실행

执行配置了workflow_dispatch事件的工作流

gh workflow run ci.yml
gh workflow run ci.yml

입력 파라미터 전달

传递输入参数

gh workflow run deploy.yml -f environment=staging -f version=1.2.0
gh workflow run deploy.yml -f environment=staging -f version=1.2.0

특정 브랜치에서 실행

在特定分支执行

gh workflow run ci.yml --ref feature/my-branch
undefined
gh workflow run ci.yml --ref feature/my-branch
undefined

실패 대응

处理失败

bash
undefined
bash
undefined

실패한 job만 재실행

仅重新执行失败的Job

gh run rerun {run-id} --failed
gh run rerun {run-id} --failed

전체 재실행

重新执行全部内容

gh run rerun {run-id}
gh run rerun {run-id}

진행 중인 실행 취소

取消正在执行的任务

gh run cancel {run-id}
undefined
gh run cancel {run-id}
undefined

주요 
gh
서브커맨드 레퍼런스

主要
gh
子命令参考

gh issue

gh issue

bash
gh issue list [--state open|closed|all] [--label name] [--assignee handle]
gh issue view {number} [--comments]
gh issue create --title "제목" --body "본문" [--label name] [--assignee handle]
gh issue close {number} [--reason completed|not_planned]
gh issue reopen {number}
gh issue edit {number} [--title "새 제목"] [--add-label name] [--remove-label name]
gh issue comment {number} --body "코멘트"
gh issue status
bash
gh issue list [--state open|closed|all] [--label name] [--assignee handle]
gh issue view {number} [--comments]
gh issue create --title "标题" --body "内容" [--label name] [--assignee handle]
gh issue close {number} [--reason completed|not_planned]
gh issue reopen {number}
gh issue edit {number} [--title "新标题"] [--add-label name] [--remove-label name]
gh issue comment {number} --body "评论"
gh issue status

gh pr

gh pr

bash
gh pr list [--state open|closed|merged|all] [--label name] [--author handle]
gh pr view {number} [--comments]
gh pr create --title "제목" --body "본문" [--draft] [--reviewer handle]
gh pr merge {number} [--squash|--merge|--rebase] [--delete-branch]
gh pr close {number}
gh pr reopen {number}
gh pr edit {number} [--title "새 제목"] [--add-label name] [--add-reviewer handle]
gh pr comment {number} --body "코멘트"
gh pr review {number} [--approve|--comment|--request-changes] [--body "리뷰"]
gh pr diff {number}
gh pr checks {number}
gh pr status
bash
gh pr list [--state open|closed|merged|all] [--label name] [--author handle]
gh pr view {number} [--comments]
gh pr create --title "标题" --body "内容" [--draft] [--reviewer handle]
gh pr merge {number} [--squash|--merge|--rebase] [--delete-branch]
gh pr close {number}
gh pr reopen {number}
gh pr edit {number} [--title "新标题"] [--add-label name] [--add-reviewer handle]
gh pr comment {number} --body "评论"
gh pr review {number} [--approve|--comment|--request-changes] [--body "评审意见"]
gh pr diff {number}
gh pr checks {number}
gh pr status

gh release

gh release

bash
gh release list
gh release view {tag}
gh release create {tag} [--title "제목"] [--notes "노트"] [--generate-notes]
gh release delete {tag} [--yes]
bash
gh release list
gh release view {tag}
gh release create {tag} [--title "标题"] [--notes "说明"] [--generate-notes]
gh release delete {tag} [--yes]

gh label

gh label

bash
gh label list
gh label create {name} [--color hex] [--description "설명"]
gh label edit {name} [--name "새이름"] [--color hex] [--description "설명"]
gh label delete {name} [--yes]
bash
gh label list
gh label create {name} [--color hex] [--description "描述"]
gh label edit {name} [--name "新名称"] [--color hex] [--description "描述"]
gh label delete {name} [--yes]

gh repo

gh repo

bash
gh repo view [--web]
gh repo clone {owner}/{repo}
bash
gh repo view [--web]
gh repo clone {owner}/{repo}

gh run

gh run

bash
gh run list [--workflow name] [--status completed|in_progress|failure|success]
gh run view {run-id} [--log] [--log-failed]
gh run rerun {run-id} [--failed]
gh run cancel {run-id}
gh run watch {run-id}
bash
gh run list [--workflow name] [--status completed|in_progress|failure|success]
gh run view {run-id} [--log] [--log-failed]
gh run rerun {run-id} [--failed]
gh run cancel {run-id}
gh run watch {run-id}

gh workflow

gh workflow

bash
gh workflow list
gh workflow view {name|id}
gh workflow run {name|id} [-f key=value] [--ref branch]
gh workflow disable {name|id}
gh workflow enable {name|id}
bash
gh workflow list
gh workflow view {name|id}
gh workflow run {name|id} [-f key=value] [--ref branch]
gh workflow disable {name|id}
gh workflow enable {name|id}

gh search

gh search

bash
gh search issues {query} [--repo owner/repo] [--state open|closed]
gh search prs {query} [--repo owner/repo] [--state open|closed|merged]
bash
gh search issues {query} [--repo owner/repo] [--state open|closed]
gh search prs {query} [--repo owner/repo] [--state open|closed|merged]