참고: 만료된 사용자 토큰은 현재 선택적 기능이며 변경될 수 있습니다. 사용자-서버 토큰 만료 기능을 옵트인하거나 옵트아웃하려면 “앱에 선택적 기능 활성화”를 참조하세요. 자세한 내용은 “GitHub 앱에 대한 사용자-서버 액세스 토큰 만료”를 참조하세요.
GitHub 앱이 사용자를 대신하여 작동하면 사용자-서버 요청을 수행합니다. 해당 요청은 사용자의 액세스 토큰을 사용하여 권한을 부여받아야 합니다. 사용자-서버 요청은 특정 사용자에게 표시할 리포지토리를 결정하는 것과 같은 사용자에 대한 데이터 요청을 포함합니다. 해당 요청에는 빌드 실행과 같이 사용자가 트리거하는 작업도 포함됩니다.
사용자-서버 액세스 토큰의 보안을 유지하기 위해 8시간 후에 만료되는 액세스 토큰과 새 액세스 토큰으로 교환할 수 있는 새로 고침 토큰을 사용할 수 있습니다. 자세한 내용은 “사용자-서버 액세스 토큰 새로 고침”을 참조하세요.
사이트에서 사용자 식별
사용자에게 브라우저에서 실행되는 표준 앱에 대한 권한을 부여하려면 웹 애플리케이션 흐름을 사용합니다.
CLI 도구 또는 Git 자격 증명 관리자와 같이 브라우저에 직접 액세스하지 않고 헤드리스 앱에 대해 사용자에게 권한을 부여하려면 디바이스 흐름을 사용합니다. 디바이스 흐름은 OAuth 2.0 디바이스 권한 부여를 사용합니다.
웹 애플리케이션 흐름
웹 애플리케이션 흐름을 사용하여 사이트에서 사용자를 식별하는 프로세스는 다음과 같습니다.
- 사용자는 GitHub ID를 요청하도록 리디렉션됩니다.
- GitHub가 사용자를 사이트로 다시 리디렉션합니다.
- GitHub 앱이 사용자의 액세스 토큰을 사용하여 API에 액세스합니다.
앱을 만들거나 수정할 때 설치 중에 OAuth(사용자 권한 부여 요청) 를 선택하면 앱 설치 중에 1단계가 완료됩니다. 자세한 내용은 “설치하는 동안 사용자에게 권한 부여”를 참조하세요.
1. 사용자의 GitHub ID 요청
브라우저에서 다음 URL로 사용자를 안내합니다.
GET http(s)://HOSTNAME/login/oauth/authorize
GitHub 앱이 login
매개 변수를 지정하면 앱에 로그인하고 권한을 부여하는 데 사용할 수 있는 특정 계정을 사용자에게 표시합니다.
매개 변수
이름 | Type | 설명 |
---|---|---|
client_id | string | 필수 사항입니다. GitHub 앱의 클라이언트 ID입니다. 앱을 선택할 때 GitHub 앱 설정에서 찾을 수 있습니다. 참고: 앱 ID와 클라이언트 ID는 동일하지 않으며 서로 교환할 수 없습니다. |
redirect_uri | string | 권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. 이는 GitHub 앱을 설정할 때 콜백 URL로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다. |
state | string | 위조 공격으로부터 보호하기 위해 임의 문자열을 포함해야 하며 다른 임의 데이터를 포함할 수 있습니다. |
login | string | 앱에 로그인하고 권한을 부여하는 데 사용할 특정 계정을 제안합니다. |
allow_signup | string | 인증되지 않은 사용자에게 OAuth 흐름 중에 GitHub에 등록하는 옵션이 제공될지 여부입니다. 기본값은 true 입니다. 정책에서 등록을 금지할 때 false 를 사용합니다. |
참고: 권한 부여 요청에 범위를 제공할 필요가 없습니다. 기존 OAuth와 달리 권한 부여 토큰은 GitHub 앱 및 사용자의 권한과 연결된 권한으로 제한됩니다.
2. GitHub가 사용자를 사이트로 다시 리디렉션
사용자가 요청을 수락하면 GitHub는 state
매개 변수의 이전 단계에서 제공한 상태뿐만 아니라 코드 매개 변수의 임시 code
와 함께 사이트로 다시 리디렉션합니다. 상태가 일치하지 않으면 요청이 타사에 의해 만들어졌으며 프로세스를 중단해야 합니다.
참고: 앱을 만들거나 수정할 때 설치 중에 OAuth(사용자 권한 부여 요청) 를 선택하는 경우 GitHub에서 액세스 토큰을 교환해야 하는 임시 code
를 반환합니다. 앱을 설치하는 동안 GitHub에서 OAuth 흐름을 시작할 때 state
매개 변수가 반환되지 않습니다.
이 code
를 액세스 토큰으로 교환합니다. 만료 토큰을 사용하도록 설정하면 액세스 토큰은 8시간 후에 만료되고 새로 고침 토큰은 6개월 후에 만료됩니다. 토큰을 새로 고칠 때마다 새 새로 고침 토큰이 발생합니다. 자세한 내용은 “사용자-서버 액세스 토큰 새로 고침”을 참조하세요.
만료된 사용자 토큰은 현재 선택적 기능이며 변경될 수 있습니다. 사용자-서버 토큰 만료 기능을 옵트인하려면 “앱에 선택적 기능 활성화”를 참조하세요.
다음 엔드포인트에 액세스 토큰을 받도록 요청합니다.
POST http(s)://HOSTNAME/login/oauth/access_token
매개 변수
이름 | Type | 설명 |
---|---|---|
client_id | string | 필수 사항입니다. GitHub 앱의 클라이언트 ID입니다. |
client_secret | string | 필수 사항입니다. GitHub 앱의 클라이언트 암호입니다. |
code | string | 필수 사항입니다. 1단계에 대한 응답으로 받은 코드입니다. |
redirect_uri | string | 권한 부여 후에 사용자를 보낼 애플리케이션의 URL입니다. 이는 GitHub 앱을 설정할 때 콜백 URL로 제공한 URL 중 하나와 정확히 일치해야 하며 추가 매개 변수를 포함할 수 없습니다. |
응답
기본적으로 응답은 다음 형식을 사용합니다. 응답 매개 변수 expires_in
, refresh_token
, refresh_token_expires_in
은 만료되는 사용자-서버 액세스 토큰을 사용하도록 설정할 때만 반환됩니다.
{
"access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
"expires_in": 28800,
"refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
"refresh_token_expires_in": 15811200,
"scope": "",
"token_type": "bearer"
}
3. GitHub 앱이 사용자의 액세스 토큰을 사용하여 API에 액세스
사용자의 액세스 토큰을 사용하면 GitHub 앱이 사용자를 대신하여 API에 요청할 수 있습니다.
Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user
예를 들어 curl에서 다음과 같이 인증 헤더를 설정할 수 있습니다.
curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user
디바이스 흐름
참고: 디바이스 흐름은 퍼블릭 베타 상태이며 변경될 수 있습니다.
디바이스 흐름을 사용하면 CLI 도구 또는 Git 자격 증명 관리자와 같은 헤드리스 앱의 사용자에게 권한을 부여할 수 있습니다.
디바이스 흐름을 사용하여 사용자를 식별하고 권한을 부여하려면 먼저 앱 설정에서 사용하도록 설정해야 합니다. 디바이스 흐름을 사용하도록 설정하는 방법에 대한 자세한 내용은 “GitHub 앱 수정”을 참조하세요. 디바이스 흐름을 사용하여 사용자에게 권한을 부여하는 방법에 대한 자세한 내용은 “OAuth 앱 권한 부여”를 참조하세요.
사용자가 액세스할 수 있는 설치 리소스 확인
사용자에 대한 OAuth 토큰이 있으면 사용자가 액세스할 수 있는 설치를 확인할 수 있습니다.
Authorization: Bearer OAUTH-TOKEN
GET /user/installations
설치를 위해 사용자가 액세스할 수 있는 리포지토리를 확인할 수도 있습니다.
Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories
자세한 내용은 사용자 액세스 토큰에 액세스할 수 있는 앱 설치 나열 및 사용자 액세스 토큰에 액세스할 수 있는 목록 리포지토리에서 찾을 수 있습니다.
철회한 GitHub 앱 권한 부여 처리
사용자가 GitHub 앱의 권한 부여를 철회하면 앱은 기본적으로 github_app_authorization
웹후크를 받습니다. GitHub 앱은 이 이벤트에서 구독을 취소할 수 없습니다. 누구나 GitHub 계정 설정 페이지에서 GitHub 앱의 권한 부여를 취소할 수 있습니다. GitHub 앱의 권한 부여를 취소해도 GitHub 앱이 제거되지 않습니다. 이 웹후크를 받으면 토큰을 철회한 사용자를 대신하여 API 호출을 중지하도록 GitHub 앱을 프로그래밍해야 합니다. GitHub 앱이 철회한 액세스 토큰을 계속 사용하는 경우 401 Bad Credentials
오류가 발생합니다.
사용자 수준 권한
GitHub 앱에 사용자 수준 권한을 추가하여 사용자 권한 부여 흐름의 일부로 개별 사용자가 부여한 사용자 메일과 같은 사용자 리소스에 액세스할 수 있습니다. 사용자 수준 권한은 조직 또는 개인 계정에 설치할 때 부여되는 리포지토리 및 조직 수준 권한과 다릅니다.
사용 권한 및 웹후크 페이지의 사용자 권한 섹션의 GitHub 앱의 설정 내에서 사용자 수준 권한을 선택할 수 있습니다. 사용 권한 선택에 대한 자세한 내용은 “GitHub 앱 사용 권한 편집”을 참조하세요.
사용자가 자신의 계정에 앱을 설치하면 설치 프롬프트에 앱이 요청하는 사용자 수준 권한이 나열되고 앱이 개별 사용자에게 사용 권한을 요청할 수 있음을 설명합니다.
사용자 수준 권한은 개별 사용자별로 부여되므로 업그레이드하라는 메시지가 표시되지 않아도 기존 앱에 추가할 수 있습니다. 그러나 사용자 권한 부여 흐름을 통해 기존 사용자를 보내 새 권한을 부여하고 해당 요청에 대한 새 사용자-서버 토큰을 가져와야 합니다.
사용자-서버 요청
대부분의 API 상호 작용은 서버 간 설치 액세스 토큰을 사용하여 발생해야 하지만 특정 엔드포인트를 사용하면 사용자 액세스 토큰을 사용하여 API를 통해 작업을 수행할 수 있습니다. 앱은 GraphQL 또는 REST 엔드포인트를 사용하여 다음 요청을 수행할 수 있습니다.
지원되는 엔드포인트
실행 확인
체크 스위트
사용 규정
배포 상태
배포
이벤트
피드
Git Blob
Git 커밋
Git 참조
Git 태그
Git 트리
Gitignore 템플릿
설치
문제 담당자
문제 주석
문제 이벤트
문제 타임라인
문제
레이블
- 문제에 대한 레이블 나열
- 문제에 레이블 추가
- 문제에 대한 레이블 설정
- 문제에서 모든 레이블 제거
- 문제에서 레이블 제거
- 리포지토리의 레이블 나열
- 레이블 만들기
- 레이블 가져오기
- 레이블 업데이트
- 레이블 삭제
- 마일스톤의 모든 문제에 대한 레이블 가져오기
라이선스
Markdown
Meta
마일스톤
조직 후크
조직 구성원
- 조직 구성원 나열
- 사용자의 조직 멤버 자격 확인
- 조직 구성원 제거
- 사용자의 조직 멤버 자격 가져오기
- 사용자의 조직 멤버 자격 설정
- 사용자의 조직 멤버 자격 제거
- 퍼블릭 조직 구성원 나열
- 사용자의 퍼블릭 조직 멤버 자격 확인
- 인증된 사용자의 퍼블릭 조직 멤버 자격 설정
- 인증된 사용자의 퍼블릭 조직 멤버 자격 제거
조직 외부 협력자
조직 사전 수신 후크
조직 팀 프로젝트
조직 팀 리포지토리
조직 팀
- 팀 나열
- 팀 만들기
- 이름으로 팀 가져오기
- 팀 업데이트
- 팀 삭제
- 팀 구성원 나열
- 사용자의 팀 멤버 자격 가져오기
- 사용자의 팀 멤버 자격 추가 또는 업데이트
- 사용자의 팀 멤버 자격 제거
- 자식 팀 나열
- 인증된 사용자의 팀 나열8
조직
- 조직 나열
- 조직 가져오기
- 조직 업데이트
- 인증된 사용자의 조직 멤버 자격 나열
- 인증된 사용자의 조직 멤버 자격 가져오기
- 인증된 사용자의 조직 멤버 자격 업데이트
- 인증된 사용자의 조직 나열
- 사용자의 조직 나열
프로젝트 협력자
프로젝트
- 조직 프로젝트 나열
- 조직 프로젝트 만들기.
- 프로젝트 가져오기
- 프로젝트 업데이트
- 프로젝트 삭제
- 프로젝트 열 나열
- 프로젝트 열 만들기
- 프로젝트 열 가져오기
- 프로젝트 열 업데이트
- 프로젝트 열 삭제
- 프로젝트 카드 나열
- 프로젝트 카드 만들기
- 프로젝트 열 이동
- 프로젝트 카드 가져오기
- 프로젝트 카드 업데이트
- 프로젝트 카드 삭제
- 프로젝트 카드 이동
- 리포지토리 프로젝트 나열
- 리포지토리 프로젝트 만들기
끌어오기 주석
- 끌어오기 요청에 대한 검토 주석 나열
- 끌어오기 요청에 대한 검토 주석 만들기
- 리포지토리의 검토 주석 나열
- 끌어오기 요청에 대한 검토 주석 가져오기
- 끌어오기 요청에 대한 검토 주석 업데이트
- 끌어오기 요청에 대한 검토 주석 삭제
끌어오기 요청 검토 이벤트
끌어오기 요청 검토 요청
끌어오기 요청 검토
끌어오기
- 끌어오기 요청 나열
- 끌어오기 요청 만들기
- 끌어오기 요청 가져오기
- 끌어오기 요청 업데이트
- 끌어오기 요청에 대한 커밋 나열
- 끌어오기 요청 파일 나열
- 끌어오기 요청이 병합되었는지 확인
- 끌어오기 요청 병합(병합 단추)
반응
- 반응 삭제
- 커밋 주석에 대한 반응 나열
- 커밋 주석에 대한 반응 만들기
- 문제에 대한 반응 나열
- 문제에 대한 반응 만들기
- 문제 주석에 대한 반응 나열
- 문제 주석에 대한 반응 만들기
- 끌어오기 요청 검토 주석에 대한 반응 나열
- 끌어오기 요청 검토 주석에 대한 반응 만들기
- 팀 토론 댓글에 대한 반응 나열
- 팀 토론 댓글에 대한 반응 만들기
- 팀 토론에 대한 반응 나열
- 팀 토론에 대한 반응 만들기
- 커밋 메모 반응 삭제
- 문제 반응 삭제
- 커밋 주석에 대한 반응 삭제
- 끌어오기 요청 주석 반응 삭제
- 팀 토론 반응 삭제
- 팀 토론 주석 반응 삭제
리포지토리
- 조직 리포지토리 나열
- 인증된 사용자에 대한 리포지토리 만들기
- 리포지토리 가져오기
- 리포지토리 업데이트
- 리포지토리 삭제
- 두 커밋 비교
- 리포지토리 참가자 나열
- 포크 나열
- 포크 만들기
- 리포지토리 언어 나열
- 리포지토리 태그 나열
- 리포지토리 팀 나열
- 리포지토리 전송
- 퍼블릭 리포지토리 나열
- 인증된 사용자의 리포지토리 나열
- 사용자를 위한 리포지토리 나열
- 리포지토리 템플릿을 사용하여 리포지토리 만들기
리포지토리 작업
- 별을 준 사람들 나열
- 감시자 나열
- 사용자가 별표 표시한 리포지토리 나열
- 인증된 사용자가 리포지토리를 별표로 표시했는지 확인
- 인증된 사용자에 대한 리포지토리 별표 표시
- 인증된 사용자에 대한 리포지토리 별표 표시 해제
- 사용자가 보는 리포지토리 나열
리포지토리 분기
- 분기 나열
- 분기 가져오기
- 분기 보호 가져오기
- 분기 보호 업데이트
- 분기 보호 삭제
- 관리자 분기 보호 가져오기
- 관리자 분기 보호 설정
- 관리자 분기 보호 삭제
- 끌어오기 요청 검토 보호 가져오기
- 끌어오기 요청 검토 보호 업데이트
- 끌어오기 요청 검토 보호 삭제
- 커밋 서명 보호 가져오기
- 커밋 서명 보호 만들기
- 커밋 서명 보호 삭제
- 상태 검사 보호 가져오기
- 상태 검사 보호 업데이트
- 상태 검사 보호 제거
- 모든 상태 검사 컨텍스트 가져오기
- 모든 상태 검사 컨텍스트 추가
- 모든 상태 검사 컨텍스트 설정
- 모든 상태 검사 컨텍스트 제거
- 액세스 제한 가져오기
- 액세스 제한 삭제
- 보호된 분기에 액세스할 수 있는 팀 나열
- 팀 액세스 제한 추가
- 팀 액세스 제한 설정
- 팀 액세스 제한 제거
- 보호된 분기의 사용자 제한 나열
- 사용자 액세스 제한 추가
- 사용자 액세스 제한 설정
- 사용자 액세스 제한 제거
- 분기 병합
리포지토리 협력자
리포지토리 커밋 주석
리포지토리 커밋
리포지토리 커뮤니티
리포지토리 콘텐츠
리포지토리 이벤트 디스패치
리포지토리 후크
- 리포지토리 웹후크 나열
- 리포지토리 웹후크 만들기
- 리포지토리 웹후크 가져오기
- 리포지토리 웹후크 업데이트
- 리포지토리 웹후크 삭제
- 리포지토리 웹후크 Ping
- 푸시 리포지토리 웹후크 테스트
리포지토리 초대
리포지토리 키
리포지토리 페이지
- GitHub Pages 사이트 가져오기
- GitHub Pages 사이트 만들기
- GitHub Pages 사이트에 대한 정보 업데이트
- GitHub Pages 사이트 삭제
- GitHub Pages 빌드 나열
- GitHub Pages 빌드 요청
- GitHub Pages 빌드 가져오기
- 최신 페이지 빌드 가져오기
리포지토리 사전 수신 후크
리포지토리 릴리스
- 릴리스 목록
- 릴리스 만들기
- 릴리스 가져오기
- 릴리스 업데이트
- 릴리스 삭제
- 릴리스 자산 나열
- 릴리스 자산 가져오기
- 릴리스 자산 업데이트
- 릴리스 자산 삭제
- 최신 릴리스 가져오기
- 태그 이름으로 릴리스 가져오기
리포지토리 통계
Root
검색
상태
팀 토론
토픽
사용자 전자 메일
사용자 팔로워
사용자 Gpg 키
- 인증된 사용자의 GPG 키 나열
- 인증된 사용자에 대한 GPG 키 만들기
- 인증된 사용자에 대한 GPG 키 가져오기
- 인증된 사용자에 대한 GPG 키 삭제
- 사용자에 대한 gpg 키 나열
사용자 퍼블릭 키
- 인증된 사용자의 퍼블릭 SSH 키 나열
- 인증된 사용자의 퍼블릭 SSH 키 만들기
- 인증된 사용자의 퍼블릭 SSH 키 가져오기
- 인증된 사용자의 퍼블릭 SSH 키 삭제
- 사용자의 퍼블릭 키 나열