이 문서가 필요한 경우
- QA 보드, 운영 요청, 고객 피드백을 Notion 데이터베이스에서 관리하는 경우
- 이슈스티커에서 생성하는 이슈를 Notion 페이지로 한 번에 관리하고 싶은 경우
시작하기 전에
이슈를 받을 데이터베이스를 먼저 정하세요. 기존 버그 보드가 있으면 그대로 쓰고, 없다면 제목, 상태, 담당자, 링크 정도만 있는 데이터베이스로 시작하면 됩니다.
연결에는 해당 데이터베이스에 접근할 수 있는 Notion 계정이 필요합니다.
끝나면 확인할 것
- 이슈를 받을 Notion 데이터베이스를 정했습니다.
- 이슈 생성 화면에 노출할 속성을 골랐습니다.
- 이슈를 생성하면 Notion 페이지가 자동으로 함께 생성되고, Notion에서 바뀐 값은
필드 동기화로 가져올 수 있습니다.
1. OAuth 연결하기
관리자 콘솔의 프로젝트 설정에서 Notion 연동을 시작합니다. Notion 권한 화면이 열리면 사용할 워크스페이스를 고르고, 이슈스티커가 접근할 페이지나 데이터베이스를 허용합니다.
여기서 허용하지 않은 데이터베이스는 다음 단계 목록에 나오지 않습니다.
2. 데이터베이스 선택하기
접근 가능한 데이터베이스 목록에서 이슈를 모을 곳을 선택하면 이슈스티커가 속성 목록을 읽어옵니다.
3. 연동할 필드 정하기
선택한 데이터베이스의 속성을 그대로 읽어옵니다. 이슈 생성 화면에 노출할 속성만 켜세요. 입력 형식은 Notion에 설정된 속성 타입을 그대로 따릅니다.
제목, 상태, 담당자, 우선순위 정도면 시작하기에 충분합니다. 나머지는 Notion에서 후속 정리하도록 두세요.
4. 페이지 생성 확인하기
Extension이나 SDK에서 이슈를 만들면 선택한 데이터베이스에 페이지가 생성됩니다. 페이지 본문에는 이슈스티커에 작성한 설명이 제목, 목록, 굵게, 표 같은 서식을 유지한 채 들어갑니다. 설명 외에 환경 정보, 발견된 페이지, 스크린샷, 화면 녹화, 콘솔 오류, 실패한 네트워크 요청, 선택한 요소, 보고자, 세션 리플레이 링크, 이슈스티커 링크도 페이지 본문의 섹션에 들어갑니다. 어느 섹션에 무엇이 들어갈지는 다음 단계에서 정합니다.
콘솔 오류는 오류 항목만 최근 20건, 네트워크 요청은 실패한 요청만 최근 20건이 들어갑니다. 콘솔 메시지의 비밀 값은 가려지고, 네트워크 요청은 메서드, 상태 코드, URL만 넣으며 URL의 쿼리에 든 비밀 값은 제거합니다.
5. 섹션별로 들어갈 내용 정하기
Notion 템플릿을 선택하면 이슈스티커가 템플릿의 섹션 제목과 안내 문구를 한 번 분석해 어느 섹션에 어떤 데이터를 넣을지 정합니다. 분석에는 OpenAI 모델을 사용하고 일시적으로 실패하면 Anthropic 모델로 대신합니다. 모델에 보내는 것은 템플릿의 섹션 제목과 안내 문구뿐이며 이슈 내용은 보내지 않습니다. 템플릿 저장은 분석을 기다리지 않으므로 결과는 잠시 뒤에 나타납니다.
관리자는 연동 설정의 Notion 화면에 있는 '섹션별로 들어갈 내용' 영역에서 현재 배정을 확인하고 바꿀 수 있습니다. 템플릿의 섹션을 고친 뒤에는 「다시 분석」을 클릭해 결과를 새로 받으세요.
- 설명 섹션에는 설명만 넣을 수 있습니다. 같은 섹션에 다른 데이터를 두면 설명과 함께 동기화되기 때문입니다.
- 어느 섹션에도 배정하지 않은 데이터는 페이지 끝의 '이슈스티커 세부사항' 섹션에 들어갑니다.
- 템플릿을 쓰지 않는 페이지에는 설명, 환경, 스크린샷, 로그 섹션과 페이지 끝의 '이슈스티커 세부사항' 섹션이 기본으로 만들어집니다.
- 설명 섹션의 제목은 Notion에서 이름을 바꿔도 됩니다. 다만 제목 블록을 지우면 설명 동기화가 멈추고, 이슈스티커의 설명 편집 화면에 잠금 안내가 표시됩니다. 지운 제목을 Notion에서 되살리면(실행 취소 또는 휴지통에서 복원) 동기화가 다시 시작됩니다. 같은 이름으로 제목을 새로 만들어서는 풀리지 않습니다.
6. 동기화되는 범위 확인하기
제목은 양방향으로 동기화됩니다. 이슈스티커에서 제목을 고치면 Notion 페이지의 제목 속성이 바뀌고, Notion에서 제목 속성을 고치면 이슈스티커 제목이 바뀝니다.
설명은 양방향으로 동기화됩니다. 이슈스티커에서 설명을 고치면 Notion 페이지의 설명 섹션에 반영되고, Notion에서 설명 섹션을 고치면 이슈스티커 설명에 반영됩니다. 이슈스티커에서 고치지 않은 블록과 설명 섹션 밖의 다른 섹션은 그대로 남습니다. 이미지, 파일, 콜아웃, 북마크 같은 블록은 Notion에서만 고칠 수 있습니다. 이슈스티커에서 그 블록을 바꾸거나 지우거나 옮기면 설명이 저장되지 않으니, 원래대로 되돌린 뒤 다시 저장하세요. Notion에서 설명이 먼저 바뀌었다면 이슈스티커가 최신 내용을 불러오고 저장을 멈추므로, 내용을 확인한 뒤 다시 저장하세요. 번호 목록의 시작 번호는 Notion으로 보내지 않습니다. Notion API가 시작 번호 쓰기를 받지 않기 때문입니다. Notion에서 정한 시작 번호는 이슈스티커로 가져옵니다.
제목, 목록, 체크박스, 인용, 코드블록, 수식(블록과 문장 안), 밑줄, 토글, 굵게·기울임·링크 같은 서식은 양쪽 방향 모두 유지됩니다. Notion에서 하위 항목을 들여써서 계층을 만들면 그 구조도 그대로 들어옵니다. 다만 Notion 페이지 안에 따로 만든 하위 페이지의 내용은 설명에 포함되지 않습니다. 설명으로 읽어오는 범위는 설명 섹션뿐입니다. 환경이나 로그 같은 다른 섹션과 템플릿의 다른 내용은 설명에 들어오지 않습니다. Notion에서 설명 섹션 안에 제목이나 내용을 새로 추가하면 그 내용은 설명에 들어옵니다. 섹션 배정 기능이 생기기 전에 템플릿에서 설명 위치를 정하지 않고 만든 페이지는 본문 전체를 설명으로 읽습니다.
Notion에서 무엇을 바꾸든 제목, 속성, 설명이 함께 최신 값으로 맞춰집니다. 상태나 담당자만 바꿔도 그 시점의 페이지 본문을 다시 읽어 설명에 반영합니다. 반영이 바로 보이지 않는다면 이슈 팝오버의 Notion 연동 영역에서 필드 동기화를 누르세요. 그 자리에서 Notion의 최신 값을 다시 읽어옵니다.
문제가 생겼을 때 먼저 확인할 것
- 데이터베이스가 보이지 않으면 Notion 연결 권한을 다시 열고 해당 데이터베이스를 포함합니다.
- 담당자 값이 들어가지 않으면 Notion 사용자와 이슈스티커 멤버가 같은 이메일로 연결되어 있는지 확인합니다.
- 값이 계속 비어 있으면 해당 속성이 켜져 있는지와 권한 범위를 확인합니다.