GitHub 연동

GitHub를 Mattermost와 연동하면 GitHub 코드 저장소와 커뮤니케이션 플랫폼 사이를 오가며 생기는 방해 요소와 컨텍스트 전환을 줄일 수 있습니다. 커밋, 풀 리퀘스트, 이슈 등에 대한 실시간 업데이트를 Mattermost 채널에서 바로 받아 팀의 집중력과 생산성을 유지하세요.

배포

GitHub 연동을 배포하려면 Mattermost 시스템 관리자가 다음 단계를 수행해야 합니다.

연동 설치하기

1. Mattermost의 제품 메뉴에서 App Marketplace를 선택합니다.
2. GitHub를 검색하거나 목록에서 찾아 Install(설치)을 선택합니다.

연동 설정하기

GitHub 연동은 기본 제공 설정 마법사(권장)를 사용하거나 수동 설정 절차를 따라 구성할 수 있습니다.

Setup wizard (recommended) — 설정 마법사(권장)

GitHub 연동을 설정하는 권장 방법은 기본 제공 설정 마법사를 사용하는 것입니다. 이 마법사는 GitHub에서 OAuth 앱과 웹훅을 만드는 과정을 포함해 설정의 각 단계를 안내합니다.

1. Mattermost 채널에서 /github setup 슬래시 명령어를 실행합니다.
2. 대화형 안내에 따라 설정을 완료합니다.

마법사는 다음 과정을 안내합니다.

• GitHub에서 OAuth 앱 생성 및 설정
• GitHub와 Mattermost 사이의 웹훅 연결 설정
• 팀에 연동 도입 알리기

다음 하위 명령어를 사용하면 개별 설정 단계를 언제든 따로 실행할 수도 있습니다.

• /github setup oauth: GitHub에서 OAuth2 애플리케이션을 설정합니다.
• /github setup webhook: GitHub에서 Mattermost로 향하는 웹훅을 생성합니다.
• /github setup announce: 지정한 채널에 연동 사용 가능 여부를 공지합니다.

Manual configuration — 수동 설정

설정 마법사 대신 직접 연동을 설정하려면 아래 단계를 따르세요.

GitHub에서 OAuth 앱 등록하기

1. GitHub에 OAuth 앱을 등록하려면 https://github.com/settings/applications/new로 이동합니다.
2. 다음 값을 설정합니다.
   • Application name: Mattermost GitHub Plugin - <YOUR COMPANY NAME>
   • Homepage URL: https://github.com/mattermost/mattermost-plugin-github
   • Authorization callback URL: https://YOUR-MATTERMOST-URL.COM/plugins/github/oauth/complete. https://YOUR-MATTERMOST-URL.COM은 사용 중인 Mattermost URL로 바꿉니다. 이 값은 로그인에 사용하는 Mattermost 서버 URL과 일치해야 합니다.
3. 변경 사항을 저장합니다.
4. Generate a new client secret(새 클라이언트 시크릿 생성)을 선택하고 GitHub 비밀번호를 입력해 진행합니다.
5. 이어지는 화면에서 Client ID와 Client Secret을 복사합니다.
6. Mattermost에서 System Console > Plugins > GitHub(시스템 콘솔 > 플러그인 > GitHub)로 이동해 각 필드 옆의 Regenerate(재생성)를 선택해 Webhook Secret과 At Rest Encryption Key를 모두 재생성합니다. GitHub에서 웹훅을 만들려면 Webhook Secret 값의 사본이 필요합니다.

GitHub에서 웹훅 만들기

GitHub가 Mattermost로 이벤트를 보내도록 웹훅을 만듭니다. 웹훅은 다음 두 수준 중 하나에서 만들 수 있습니다.

• 조직(Organization) 수준: 조직에 속한 모든 저장소의 이벤트를 전달합니다.
• 저장소(Repository) 수준: Mattermost로 이벤트를 보내려는 저장소마다 웹훅을 하나씩 만듭니다.

1. GitHub에서 알림을 보내려는 대상(조직 또는 특정 저장소)의 Settings(설정) 페이지로 이동한 뒤 사이드바에서 Webhooks를 선택합니다.
2. Add Webhook(웹훅 추가)을 선택합니다.
3. 다음 값을 설정합니다.
   • Payload URL: https://YOUR-MATTERMOST-URL.COM/plugins/github/webhook. https://YOUR-MATTERMOST-URL.COM은 사용 중인 Mattermost URL로 바꿉니다.
   • Content Type: application/json
   • Secret: 앞서 복사해 둔 Webhook Secret 값입니다.
4. Which events would you like to trigger this webhook?(이 웹훅을 트리거할 이벤트를 선택하세요) 아래에서 Let me select individual events(개별 이벤트 직접 선택)를 선택합니다.
5. 다음 이벤트를 선택합니다.
   • Branch or Tag creation
   • Branch or Tag deletion
   • Discussions
   • Discussion comments
   • Issue comments
   • Issues
   • Pull requests
   • Pull request review
   • Pull request review comments
   • Pushes
   • Releases
   • Stars
   • Workflows
6. Add Webhook을 선택해 변경 사항을 저장합니다.

Mattermost에서 연동 설정하기

1. Mattermost 배포 환경에 github 사용자 계정이 있는지 확인합니다. 이 계정이 존재하면 기본적으로 해당 계정이 채널에 GitHub 메시지를 게시하며, 메시지에 BOT 태그가 표시되지 않습니다. 다음 방법 중 하나로 BOT 태그가 표시되도록 동작을 바꿀 수 있습니다.
   • mmctl user convert를 사용해 사용자 계정을 봇으로 전환합니다.
   • 기존 github 사용자명을 다른 이름으로 바꿉니다. 봇 계정 생성 활성화 설정이 켜져 있으면 Mattermost 서버를 재시작할 때 github라는 새 봇 계정이 생성됩니다.
2. Mattermost에서 System Console > Plugins > GitHub(시스템 콘솔 > 플러그인 > GitHub)로 이동해 다음 설정을 구성한 뒤 Save(저장)를 선택합니다.
   • 등록 과정에서 받은 GitHub OAuth Client ID와 GitHub OAuth Client Secret을 입력합니다.
   • (선택) GitHub Organization: GitHub 조직을 쉼표로 구분해 지정하면 연동을 해당 조직들로 제한합니다.
   • (GitHub Enterprise 전용) Enterprise Base URL과 Enterprise Upload URL 값을 GitHub Enterprise URL로 설정합니다(예: https://github.example.com). 두 값은 대체로 동일합니다.
   • (Mattermost 데스크톱 앱 전용) Display Notification Counters in Left Sidebar: Mattermost 사이드바에 GitHub 알림 카운터를 표시하거나 숨깁니다.
   • (선택) Enable Private Repositories: 프라이빗 저장소를 사용할 수 있도록 합니다. 프라이빗 저장소가 활성화되면 해당 사용자에게 알림이 전달되며, 프라이빗 저장소에 접근하려면 GitHub 계정을 다시 연결해야 합니다.
   • (선택) Connect to private Repositories by default: 프라이빗 저장소가 활성화된 경우 기본적으로 프라이빗 GitHub 저장소에 연결합니다.
   • (선택) Enable Code Previews: GitHub 파일 퍼머링크를 미리보기로 확장합니다. 공개 저장소만, 공개 및 프라이빗 저장소 모두, 또는 비활성화 중에서 선택할 수 있습니다.
   • (선택) Enable Webhook Event Logging: 이 옵션을 켜면 로그 레벨이 DEBUG일 때 웹훅 이벤트를 로그에 남깁니다.
   • (선택) Show Author in commit notification: GitHub 푸시 이벤트 알림에서 커미터 대신 커밋 작성자를 표시합니다.

업그레이드

새 버전이 릴리스될 때마다 이 연동을 업데이트하시기를 권장합니다. 일반적으로 업데이트는 매끄럽게 진행되며 Mattermost 사용자 경험을 방해하지 않습니다. 최신 릴리스와 제공 중인 릴리스, 호환성 고려 사항은 Releases 페이지에서 확인하세요.

활성화

연동을 설정한 뒤에는 팀원들에게 GitHub 계정을 Mattermost에 연결할 수 있다는 사실을 알리세요.

사용

GitHub 연동을 사용하려는 사용자는 GitHub 계정을 Mattermost에 연결해야 합니다.

연결하고 나면 누군가 나를 멘션하거나, 리뷰를 요청하거나, 내 풀 리퀘스트·이슈에 댓글을 달거나 수정하거나(레이블 추가나 이슈 재오픈 포함), GitHub에서 나에게 이슈를 할당할 때 Mattermost에서 GitHub 봇으로부터 다이렉트 메시지를 받게 됩니다.

GitHub 계정을 Mattermost에 연결하기

1. Mattermost 채널에서 /github connect 슬래시 명령어를 실행해 Mattermost 계정과 GitHub 계정을 연결합니다.
2. 연결한 뒤 /github help 슬래시 명령어를 실행하면 가능한 작업을 확인할 수 있습니다.

시작하기

처음 사용해 볼 만한 슬래시 명령어는 다음과 같습니다.

/github subscriptions add 슬래시 명령어를 실행하면 Mattermost 채널을 구독시켜 GitHub 저장소의 새 풀 리퀘스트, 이슈, 브랜치 생성 등에 대한 알림을 받을 수 있습니다.

예를 들어 mattermost/mattermost-server GitHub 저장소에서 Help Wanted 레이블이 붙은 이슈, 이슈 댓글, 풀 리퀘스트에 대한 알림을 게시하려면 다음과 같이 실행합니다. /github subscriptions add mattermost/mattermost-server --features issues,pulls,issue_comments,label:"Help Wanted". 지원하는 플래그는 다음과 같습니다.

• --features: 다음 중 하나 이상을 쉼표로 구분한 목록입니다. issues, pulls, pulls_merged, pulls_created, pushes, creates, deletes, issue_creations, issue_comments, pull_reviews, releases, workflow_success, workflow_failure, discussions, discussion_comments, label:"labelname". 기본값은 pulls,issues,creates,deletes입니다.
• --exclude-org-member: 조직 구성원이 트리거한 이벤트를 전달하지 않습니다. 설정된 조직으로 제한되며, 멤버십이 공개된 사용자에게만 적용됩니다. 조직 구성원과 협업자(collaborator)는 서로 다릅니다.
• --include-only-org-members: 조직 구성원이 트리거한 이벤트만 전달합니다. 플러그인 설정에 지정한 조직으로 제한되며, 멤버십이 공개된 사용자에게만 적용됩니다. 조직 구성원과 협업자는 서로 다르다는 점에 유의하세요.
• --render-style: 지정한 스타일로 알림을 전달합니다(예: 풀 리퀘스트 본문을 표시하지 않음). 지원 값은 collapsed, skip-body, default(플래그를 생략한 것과 동일)입니다.
• --exclude: mattermost/mattermost-server처럼 구독 알림에서 제외할 저장소를 쉼표로 구분한 목록입니다. 조직 단위 구독에서만 지원됩니다.

/github todo 슬래시 명령어를 실행하면 읽지 않은 메시지 목록과 내 리뷰를 기다리는 풀 리퀘스트를 포함해 GitHub에서 해야 할 일을 메시지로 받을 수 있습니다.

/github settings 슬래시 명령어를 실행하면 알림과 일일 리마인더 설정을 변경할 수 있습니다.

/github mute 슬래시 명령어를 실행하면 음소거한 GitHub 사용자를 관리할 수 있습니다. 음소거한 사용자가 내 풀 리퀘스트나 이슈에 남긴 댓글에 대해서는 알림을 받지 않습니다.

/github default-repo 슬래시 명령어를 실행하면 현재 채널의 기본 저장소를 설정할 수 있습니다. 이 저장소는 편의를 위해 Create GitHub Issue 모달에 자동으로 채워집니다.

자주 묻는 질문

조직 대신 저장소를 연결하려면 어떻게 합니까?

GitHub 웹훅을 조직이 아니라 저장소에서 설정하세요. 그러면 웹훅을 만든 저장소에 대해서만 알림과 구독이 전송됩니다. 리마인더와 /github todo는 조직 전체를 검색하지만, 나에게 할당된 항목만 표시합니다.

특정 레이블이 붙었을 때 알림을 보내려면 어떻게 합니까?

mattermost/mattermost-plugin-github 저장소의 이슈에 Severity/Critical 레이블이 붙을 때 Mattermost 채널로 알림을 보내려면 다음 슬래시 명령어를 실행해 해당 알림을 구독하세요. /github subscriptions add mattermost/mattermost-plugin-github issues,label:"Severity/Critical"

연결된 GitHub 사용자별 데이터는 어떻게 저장됩니까?

GitHub 사용자 토큰은 Mattermost에서 생성한 At Rest Encryption Key로 AES 암호화됩니다. 암호화된 토큰은 Mattermost 데이터베이스의 PluginKeyValueStore 테이블에 저장됩니다.

도움받기

Mattermost 고객은 Mattermost 지원 케이스를 열 수 있습니다. 버그를 신고하려면 Mattermost GitHub 플러그인 저장소에 GitHub 이슈를 등록해 주세요.

질문, 피드백, 도움이 필요하면 Mattermost 커뮤니티 서버의 공개 Integrations and Apps 채널에 참여하세요.

Mattermost Team Edition 및 무료 사용 고객은 Mattermost 사용자 간 문제 해결 포럼에서 전 세계 Mattermost 커뮤니티의 도움을 받을 수 있습니다.