Jira 티켓, GitHub PR, 기술 스펙, 코드 예시를 한 페이지에서 연결하는 실전 가이드
이 문서는 단순히 외부 링크를 모으는 방법이 아니라, Jira·GitHub의 최신 상태를 Notion 데이터베이스로 동기화하고 기술 스펙 안에서 코드까지 바로 검토할 수 있는 구조를 만드는 방법을 설명합니다.
1. 완성된 구조를 먼저 살펴보기
Before — 정보가 도구마다 흩어진 상태
기술 스펙은 공유 폴더의 Word 파일에 있고, Jira 티켓에는 “첨부파일 참고”라고만 적혀 있습니다. 구현 코드는 이미지로 붙어 있어 복사할 수 없고, 리뷰어는 PR 상태를 확인하려고 GitHub를 별도로 열어야 합니다.
After — Notion이 기술 문서의 허브가 된 상태
기술 스펙
배경, 범위, API 계약, 의사결정, 테스트 기준을 한 문서에서 관리합니다.
Jira Sync
프로젝트와 작업 항목의 상태·담당자·우선순위를 문서 옆에서 확인합니다.
GitHub 연결
관련 이슈와 PR을 표시하고, PR 진행에 따라 Notion 작업 상태를 자동 변경합니다.
구성 요소 | Notion에서 보이는 정보 | 원본을 수정하는 곳 |
Jira Sync | 프로젝트, 작업 항목, 상태, 담당자, 우선순위 | 기본은 Jira / Enterprise 양방향 설정 시 일부 필드는 Notion에서도 편집 가능 |
GitHub Synced Database | 이슈·PR 제목, 상태, 번호, 작성자, 리뷰어, 생성·병합·종료 시각 | GitHub |
GitHub Pull Requests 속성 | Notion 작업과 연결된 PR 및 진행 상태 | GitHub 또는 Notion의 연결 속성 |
코드 블록 | 요청·응답 JSON, SQL, Shell, 코드 예시 | Notion 문서 |
2. 예시 시나리오: ‘결제 API 리팩터링’ 스펙
기술 스펙 페이지를 다음 순서로 구성한다고 가정하겠습니다.
- 상단에는 목표·범위·담당자·출시 예정일을 배치합니다.
- Jira 작업 항목 뷰에는
PAY프로젝트 중 이번 리팩터링과 관련된 티켓만 표시합니다.
- GitHub PR 뷰에는
payment-api저장소의 열린 PR과 리뷰 대기 PR을 표시합니다.
- 본문에는 엔드포인트, 요청·응답 형식, 오류 코드, 마이그레이션 순서를 코드 블록으로 기록합니다.
- 하단에는 미해결 질문과 배포 전 체크리스트를 둡니다.
핵심 원칙
Notion에는 ‘업무를 이해하는 데 필요한 맥락’을 두고, 실제 이슈와 코드는 Jira·GitHub에서 관리합니다. Synced Database는 원본을 복제하는 용도가 아니라, 문서를 읽는 사람이 최신 개발 상태를 함께 확인하도록 만드는 창으로 사용하세요.
3. Jira 연결: 링크 미리보기와 Jira Sync 구분하기
어떤 연결을 선택해야 하나요?
필요한 기능 | 권장 방식 | 설정 위치 |
문서에서 Jira 링크를 카드처럼 표시 | Jira 연결 | Settings → Connections |
Jira 링크를 짧은 멘션으로 표시 | Jira 연결 | 페이지에 Jira URL 붙여넣기 → Mention |
여러 프로젝트와 작업 항목을 DB로 지속 동기화 | Jira Sync | Settings → Import → Jira Sync |
Notion에서 Jira 일부 필드를 직접 수정 | Jira Sync 양방향 동기화 | Enterprise 플랜 + 사용자별 Jira 인증 |
Jira Sync 최초 설정
필요 권한
최초 연결은 Notion 워크스페이스 소유자가 Jira Admin API 토큰으로 설정해야 합니다. 이후에는 각 멤버가 자신이 Jira에서 접근할 수 있는 프로젝트를 동기화에 추가할 수 있습니다.
- Jira 관리자 계정에서 API 토큰을 생성합니다.
- 토큰 생성 시 Create API token을 선택합니다.
- 안정적인 동기화를 위해 Create API token with scopes가 아닌 scopeless 토큰이 권장됩니다.
- 토큰 만료일은 조직의 보안 정책이 허용하는 범위에서 충분히 길게 설정합니다.
- Notion 사이드바에서
Settings→Import→Jira Sync로 이동합니다.
Get started를 누르고 Jira 관리자 이메일, Jira 사이트 URL, API 토큰을 입력합니다.
- 연결할 사이트를 선택한 뒤
Create a new sync를 선택합니다.
Select projects to sync에서 프로젝트를 고르고,Select properties to sync에서 필요한 속성만 선택합니다.
Jira Sync는 어떤 데이터베이스를 만들까요?
- Projects 데이터베이스: 프로젝트명, 상태, 담당자, 일정, 완료율 등을 보여줍니다.
- Work items 데이터베이스: Epic, Bug, Task, Subtask, Story를 작업 단위로 보여줍니다.
- 두 데이터베이스는 Relation으로 연결되어 프로젝트별 작업 항목을 추적할 수 있습니다.
- 기본적으로 Active, Timeline, Board, All, By Project, By Epic, Mine 등의 뷰가 생성됩니다.
단방향과 양방향 동기화
일반 동기화
Jira에서 변경한 내용이 Notion에 반영됩니다. 원본 수정은 Jira에서 진행하는 것이 기본입니다.
Enterprise 양방향 동기화
Notion에서 상태, 담당자, 우선순위, 첨부파일, 댓글 등 지원되는 필드를 수정할 수 있습니다. 사용자마다 Jira 인증이 필요합니다.
공유 범위를 꼭 확인하세요
Jira Synced Database는 Notion 페이지 권한을 따릅니다. 비공개 Jira 프로젝트를 동기화한 페이지를 넓게 공유하면, Jira에서 해당 프로젝트 권한이 없는 사람도 Notion에서 동기화된 내용을 볼 수 있습니다.
4. GitHub 연결: 세 가지 활용 방식
A. 이슈·PR을 문서에 미리보기로 넣기
GitHub 이슈나 PR URL을 페이지에 붙여넣고
Paste as preview를 선택합니다. 기술 스펙의 특정 문단과 연결된 이슈 하나를 보여줄 때 적합합니다.B. 저장소의 이슈·PR을 Synced Database로 만들기
- GitHub에서 이슈 또는 PR URL을 복사합니다.
- Notion 페이지에 URL을 붙여넣습니다.
Paste as database를 선택합니다.
- 처음 사용하는 경우 GitHub 계정을 인증합니다.
- 테이블이 생성되면 동기화가 끝날 때까지 기다립니다.
지원되는 주요 정보는 제목, 담당자, 설명, 상태, 이슈·PR 번호, 작성자, 생성·수정·병합·종료 시각, 리뷰어입니다. 현재 GitHub Labels와 Tags는 Synced Database 속성으로 지원되지 않습니다.
C. Notion 작업과 GitHub PR 연결하기
Notion의 작업 데이터베이스에
GitHub Pull Requests 속성을 추가하면 PR 진행 상태를 작업과 연결할 수 있습니다.- 작업 데이터베이스 상단의
+를 눌러 속성을 추가합니다.
GitHub Pull Requests를 검색해 선택합니다.
- 데이터베이스에
Unique ID속성이 있는지 확인합니다. 없다면 함께 추가됩니다.
- PR URL을 해당 속성에 붙여넣거나, PR 설명에 Notion 작업 ID를 작성합니다.
- 속성의
Edit property→Auto-update에서 PR 단계별 작업 상태를 지정합니다.
예를 들어 PR 설명에 아래처럼 작성하면
PAY-142 작업이 PR과 연결됩니다.fixes PAY-142
fixes, closes, resolves, completes처럼 완료를 의미하는 표현을 사용하면 PR 병합 시 연결된 Notion 작업을 완료 상태로 바꿀 수 있습니다. 단순 참조만 필요하다면 ref, related to, part of 등을 사용하세요.5. 코드 블록으로 기술 스펙을 실행 가능한 문서로 만들기
코드 블록 추가 방법
- 새 줄에서
/code를 입력하고Enter를 누릅니다.
- 코드를 입력하거나 붙여넣습니다.
- 블록 왼쪽 위의 언어명을 클릭해 JSON, JavaScript, Python, SQL 등 실제 언어를 선택합니다.
- 긴 줄이 가로로 잘리면 오른쪽 위의
Wrap code를 켭니다.
- 실행 환경이나 주의사항은
Caption에 기록합니다.
- 코드를 가져갈 때는 오른쪽 위의
Copy를 누릅니다.
페이지를
Can view 권한으로 보는 사용자에게는 코드 블록의 일부 조작 버튼이 표시되지 않을 수 있습니다. 외부 공유 문서라면 실제 공유 권한에서 화면을 한 번 확인하세요.요청 예시
{ "order_id": "ORD-2026-0915", "amount": 49000, "currency": "KRW", "payment_method": "card" }
응답 예시
{ "payment_id": "PAY-8F31A2", "status": "authorized", "authorized_at": "2026-09-20T14:30:00Z" }
코드 블록 Caption 예시
스테이징 환경 기준 예시입니다. 운영 환경에서는payment_id와 토큰 값을 로그에 그대로 남기지 마세요.
코드가 일반 텍스트로 붙어 문법 강조가 되지 않는다면
- 붙여넣은 내용을 잘라냅니다.
/code로 코드 블록을 먼저 생성합니다.
- 코드 블록 안에 다시 붙여넣습니다.
- 왼쪽 위 언어 선택기가
Plain Text로 되어 있다면 실제 언어로 변경합니다.
6. 스펙 페이지를 실제로 조립하는 순서
기술 스펙 상단에 목표, 범위, 오너, 출시 예정일을 작성합니다.
Jira Sync에서 필요한 프로젝트와 속성만 선택합니다.
페이지에는 전체 Jira DB가 아니라 이번 기능에 맞게 필터링한 연결된 뷰를 배치합니다.
GitHub PR 또는 이슈를
Paste as database로 추가합니다.Notion 작업 DB에
GitHub Pull Requests 속성을 연결합니다.요청·응답·SQL·Shell 명령을 각각 별도 코드 블록으로 작성합니다.
각 코드 블록 Caption에 환경, 버전, 보안 주의사항을 남깁니다.
읽기 권한 사용자 화면에서 Jira·GitHub 데이터가 어디까지 보이는지 확인합니다.
권장 페이지 목차
순서 | 섹션 | 포함할 내용 |
1 | 배경과 목표 | 해결할 문제, 성공 기준, 제외 범위 |
2 | 담당자와 일정 | 오너, 리뷰어, 출시일, 주요 마일스톤 |
3 | Jira 작업 | 관련 Epic·Task·Bug, 상태, 우선순위 |
4 | API 계약 | 엔드포인트, 인증, 요청·응답, 오류 코드 |
5 | GitHub 구현 | 관련 이슈·PR, 리뷰 상태, 병합 여부 |
6 | 배포 계획 | 마이그레이션, 롤백, 모니터링 |
7 | 미해결 질문 | 의사결정 필요 항목과 담당자 |
7. 여러 프로젝트를 Dashboard로 모으기
Dashboard view는 Business·Enterprise 플랜에서 사용할 수 있습니다. 여러 데이터베이스의 테이블, 보드, 차트, 타임라인을 하나의 화면에 위젯으로 배치할 수 있습니다.
추천 대시보드 구성
1행 — 전체 현황
- 상태별 Jira 작업 차트
- 열린 GitHub PR 수
2행 — 실행 항목
- 담당자 없는 Jira 작업
- 리뷰 대기 PR
3행 — 일정
- 주요 프로젝트 타임라인
- 이번 주 마감 작업
4행 — 위험 요소
- 차단 상태 작업
- 오래 열린 PR
Dashboard에서 필터 아이콘 →
Filter multiple sources를 선택하면 여러 위젯에 전역 필터를 적용할 수 있습니다. 다만 전역 필터는 각 위젯의 기반 뷰에 동일한 관련 속성이 있을 때만 적용됩니다. 예를 들어 Jira DB와 Notion 작업 DB 모두 담당자 속성을 포함해야 담당자 = 나 필터가 두 위젯에 함께 작동합니다.성능 팁
Dashboard는 최대 12개 위젯, 한 행에 최대 4개 위젯을 지원합니다. 큰 테이블을 필터 없이 여러 개 배치하기보다, 요약 차트와 우선순위가 높은 작업 뷰부터 보여주세요.
8. 자주 발생하는 문제
Jira에 Sync failed가 표시됩니다
Sync failed가 표시됩니다- Jira API 토큰이 만료되지 않았는지 확인합니다.
- 웹훅과 데이터 접근에 필요한 권한이 있는지 확인합니다.
- scoped 토큰을 사용했다면 권장 방식인 scopeless Admin API 토큰으로 다시 연결합니다.
- 프로젝트에 비정상적인 데이터나 접근 제한이 없는지 확인합니다.
Jira에 Sync stopped가 표시됩니다
Sync stopped가 표시됩니다토큰이 유효하지 않거나 연결이 해제된 상태일 수 있습니다. 데이터베이스 상단에서
Re-authenticate를 선택해 다시 인증합니다. 이 작업은 워크스페이스 소유자가 진행해야 합니다.GitHub 저장소나 속성이 보이지 않습니다
- GitHub Workspace 연결은 하나의 GitHub 조직을 하나의 Notion 워크스페이스에만 연결할 수 있습니다.
- 최초 조직 연결에는 Notion 워크스페이스 소유자와 GitHub 조직 관리자 권한이 필요합니다.
- 연결 시 선택한 저장소 접근 범위를 확인합니다.
- GitHub PR 속성이 목록에 없다면
Settings→More Settings→Connections에서 GitHub Pull Request 연결을 추가합니다.
동기화된 DB에서 수정했는데 원본에 반영되지 않습니다
일반 Synced Database는 기본적으로 외부 도구에서 Notion으로 들어오는 단방향 구조입니다. Jira의 일부 필드를 Notion에서 수정하려면 Enterprise 플랜의 Jira 양방향 동기화를 활성화하고, 각 사용자가 Jira 계정을 인증해야 합니다.
최종 점검
- Jira는 링크 미리보기용 연결과 데이터베이스용 Jira Sync를 구분합니다.
- Jira Sync에는 안정적인 연결을 위해 scopeless Admin API 토큰이 권장됩니다.
- GitHub는
Paste as preview,Paste as database,GitHub Pull Requests속성을 목적에 따라 선택합니다.
- 코드는
/code블록에 넣고 언어, 줄바꿈, Caption을 설정합니다.
- 동기화 DB를 공유하기 전에 Notion 페이지 권한과 외부 도구의 정보 공개 범위를 확인합니다.
- 여러 데이터 소스를 한 화면에서 볼 때는 Dashboard의 공통 속성 기반 전역 필터를 사용합니다.