github

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub CLI

주의 사항 (Anti-patterns)

注意事项（反模式）

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 } }'

✅ 구체적 서브커맨드 사용 (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

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

✅ 先向用户确认再执行

"이슈를 생성할까요? 제목: 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 log --oneline


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

git log --oneline


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

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

4. 避免硬编码仓库信息

bash

undefined

bash

undefined

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

❌ 硬编码仓库信息

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

라벨로 이슈 필터링

通过标签筛选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

상태별 이슈

按状态筛选Issue

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 --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

PR CI 상태 확인

查看PR CI状态

gh pr checks 123

PR 리뷰 승인

批准PR评审

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

Merge commit

Merge提交

gh pr merge 123 --merge

Rebase merge

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 --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

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}

릴리스 목록

查看Release列表

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 --workflow ci.yml

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

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

gh run view {run-id}

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

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

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 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}

진행 중인 실행 취소

取消正在执行的任务

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]

github

Original

Translation

GitHub CLI

GitHub CLI

주의 사항 (Anti-patterns)

注意事项（反模式）

1. gh api 사용 금지

1. 禁止使用gh api

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

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

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

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

2. Write 작업 무단 수행 금지

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

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

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

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

✅ 先向用户确认再执行

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

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

→ 사용자 승인 후 실행

→ 获得用户确认后执行

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

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

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

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

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

✅ 直接在当前目录执行

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

4. 避免硬编码仓库信息

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

❌ 硬编码仓库信息

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

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

Read vs Write 명령어 분류

读取类与写入类命令分类

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

Read（安全 - 可自由执行）

Write (사용자 확인 필수)

Write（需用户确认）

이슈 관리 모범 사례

Issue管理最佳实践

이슈-PR 연결

Issue-PR关联

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

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

라벨 체계

标签体系

라벨 목록 확인

查看标签列表

라벨로 이슈 필터링

通过标签筛选Issue

이슈 검색

Issue搜索

담당자별 이슈

按负责人筛选Issue

상태별 이슈

按状态筛选Issue

조합 검색

组合搜索

Pull Request 모범 사례

Pull Request最佳实践

PR 생성

PR创建

기본 PR 생성

创建基础PR

Test Plan

测试计划

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

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

리뷰어 지정

指定评审人

PR 크기 가이드

PR大小指南

PR 리뷰

PR评审

PR 변경사항 확인

查看PR变更内容

PR CI 상태 확인

1.
`gh api`
사용 금지

1. 禁止使用
`gh api`

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

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