prUrlTemplate 설정으로 PR 배지 링크 커스텀하기 | Playbook Tip

Claude Code로 작업하다 보면 푸터에 PR 배지가 뜨는 걸 본 적 있을 거예요. 기본값은 github.com 링크인데, GitLab 셀프호스티드나 Bitbucket을 쓰는 팀이라면 그 링크가 아무 의미 없이 뜨는 상황이 생겨요. v2.1.119에서 prUrlTemplate 설정이 추가되면서 이걸 바꿀 수 있게 됐어요.

설정 자체는 단순해요. ~/.claude/settings.json에 필드 하나 추가하면 끝이에요. 프로젝트마다 다르게 쓰고 싶다면 프로젝트 루트의 .claude/settings.json에 넣어도 되고, 둘 다 있으면 프로젝트 설정이 우선 적용돼요.

준비물

Claude Code v2.1.119 이상
~/.claude/settings.json 파일 (없으면 직접 만들어요)
사내 코드 리뷰 툴의 PR URL 패턴

1단계: settings.json 위치 확인

파일이 이미 있는지 확인해요. 없으면 새로 만들면 돼요.

ls ~/.claude/settings.json

없다고 나오면 디렉토리부터 만들어요.

mkdir -p ~/.claude && touch ~/.claude/settings.json

2단계: prUrlTemplate 추가

settings.json을 열고 prUrlTemplate 필드를 넣어요. URL 안에서 PR 번호가 들어갈 자리는 자신의 코드 리뷰 툴이 쓰는 경로 형식 그대로 쓰면 돼요. 릴리스 노트는 prUrlTemplate 키만 명시하고 PR 번호 플레이스홀더의 정확한 변수명은 공개하지 않았으니, 적용 후 한 번 테스트해서 어떻게 치환되는지 확인하는 게 좋아요.

GitLab 셀프호스티드 예시:

{
  "prUrlTemplate": "https://gitlab.<YOUR_COMPANY>.com/<YOUR_GROUP>/<YOUR_REPO>/-/merge_requests/{prNumber}"
}

Bitbucket Server 예시:

{
  "prUrlTemplate": "https://bitbucket.<YOUR_COMPANY>.com/projects/<PROJECT_KEY>/repos/<REPO_SLUG>/pull-requests/{prNumber}"
}

이미 다른 설정이 있다면 기존 JSON 객체에 필드만 추가하면 돼요.

{
  "theme": "dark",
  "editorMode": "vim",
  "prUrlTemplate": "https://gitlab.<YOUR_COMPANY>.com/<YOUR_GROUP>/<YOUR_REPO>/-/merge_requests/{prNumber}"
}

3단계: 설정 반영 확인

v1.0.90부터 settings.json 변경은 hot-reload로 자동 감지돼요. 파일을 저장하면 실행 중인 세션에 그대로 반영되니까 재시작은 보통 필요하지 않아요. 일부 설정 항목은 재시작 후에만 적용되는 경우가 있는데, 그럴 땐 한 번 껐다 켜면 돼요.

# 필요할 때만
claude

확인 방법

Claude Code가 PR 번호를 감지하는 상황이 되면 푸터 배지 링크가 바뀐 URL로 뜨는 걸 확인할 수 있어요. 터미널에서 링크를 Cmd+클릭(macOS) 또는 Ctrl+클릭(Linux)하면 설정한 리뷰 툴로 바로 열려요.

스크린샷 필요

Claude Code 터미널 푸터에 PR 배지가 표시된 상태, 링크가 커스텀 URL로 연결되는 모습

id: pr-badge-footer

응용

프로젝트마다 다른 리포지토리를 쓴다면 글로벌 설정 대신 프로젝트별로 관리하는 게 더 깔끔해요.

# 프로젝트 루트에서
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "prUrlTemplate": "https://gitlab.<YOUR_COMPANY>.com/<YOUR_GROUP>/<THIS_REPO>/-/merge_requests/{prNumber}"
}
EOF

이 파일을 레포에 커밋해두면 팀원 전체가 별도 설정 없이 같은 리뷰 URL을 쓸 수 있어요.

트러블슈팅

배지 링크가 여전히 github.com으로 열려요. 설정 파일 경로가 맞는지 확인해요. ~/.claude/settings.json인지, JSON 문법 오류는 없는지 체크해요. cat ~/.claude/settings.json | python3 -m json.tool로 파싱이 되는지 바로 확인할 수 있어요.

가 URL에 그대로 나와요. Claude Code가 현재 브랜치에서 PR 번호를 감지하지 못한 상태예요. PR이 실제로 열려 있는 브랜치에서 작업 중인지 확인해요.

프로젝트 설정이 글로벌 설정을 덮어쓰지 않아요. .claude/settings.json 파일이 프로젝트 루트에 있는지 확인해요. Claude Code를 실행하는 디렉토리 기준으로 탐색하기 때문에 하위 디렉토리에서 실행하면 인식 못할 수 있어요.

이 설정 하나로 PR 배지가 실제로 쓸 수 있는 링크로 바뀌어요.

준비물

1단계: settings.json 위치 확인

2단계: prUrlTemplate 추가

3단계: 설정 반영 확인

확인 방법

응용

트러블슈팅

참고 출처