GithubAPI v3にどのようなAPIがあり、どのように使うのかといったリファレンスが日本語としてなかったので作成しました。
ほぼ公式のGithubAPIリファレンスのままですが、間違い等ありましたらコメントでご指摘頂ければ嬉しいです。
アクティビティ
イベント
Githubでのイベントを取得するAPI群になります。
Event自体についての詳しい内容については以下のリンク先に記載されています。
Event Types & Payloads
Publicイベントの一覧取得
GET /events
リポジトリに紐付くイベントの一覧取得
GET /repos/:owner/:repo/events
リポジトリのネットワークに紐付くpublicイベントの一覧取得
こちらのAPIですが、ネットワークが一体何を示しているのかが不明でした。
Public Repositoryに対してこのAPIを実行してみた結果、取得できたものは"リポジトリに紐付くイベントの一覧取得"と同じ一覧でした。
GET /networks/:owner/:repo/events
Organizationに紐付くpublicイベントの一覧取得
GET /orgs/:org/events
ユーザーが受け取るイベントの一覧取得
フォローしているユーザーやウォッチしているリポジトリのイベントを取得します。
Oauth2認証によって、private eventsの権限が割り当てられている場合は、
privateなイベントも取得します。
GET /users/:username/received_events
ユーザーが受け取るプライベートイベントの一覧取得
GET /users/:username/received_events/public
ユーザーのイベントの一覧取得
指定したユーザーのイベントを取得。
認証済みのユーザーはパブリック・プライベートのイベントを取得。
未認証のユーザーはパブリックのイベントのみ取得。
GET /users/:username/events
ユーザーのパブリックイベントの一覧取得
GET /users/:username/events/public
Organizationのイベントの一覧取得
指定したユーザーが指定したOrganizationに所属している場合にイベントを取得する。
GET /users/:username/events/orgs/:org
フィード
feedsはAtomフォーマットで以下を取得します。
- Githubのグローバルなパブリックタイムライン
- ユーザーのパブリックタイムライン
- 認証済みユーザーのパブリック、プライベートタイムライン
- 認証済みユーザーによって作成されたアクティビティによるプライベートタイムライン
- 認証済みユーザーが所属しているOrganizationのプライベートタイムライン
Feedsの取得
GET /feeds
お知らせ
notificationとして以下を取得します。
- Issues
- Pull Request
- Commit
- これらへのコメント
またユーザーへの関わりがあるものについても取得します。
- @を使ったmention
- Issueへのアサイン
- ユーザーが作成したIssueかCommitへのCommit
- ユーザーが積極的に参加しているディスカッション(曖昧な定義だが、これについての詳細不明)
全てのNotification APIを使用するにはnotifications
かrepo
スコープが必要になります。
また、Notificationはそれぞれthreads
として1つ1つ分けられており、threads
にはIssue/Pull Request/Commitを含みます。
例えば、https://api.github.com/notifications/threads/1
というURLでのIDが1のthreads
はIssue/Pull Request/Commitのいずれかでの通知です。
Notificationが届く理由
Notification APIのレスポンスには何故Notificationが届いたのかというreason
があります。
以下、reason
の一覧です。
Reason名 | 説明 |
---|---|
subscribed | リポジトリをwatchしていたため |
manual | IssueかPull RequestのNotificationをSubscribeしたため |
author | IssueかPull Requestを作成するなどして、threadを作成したため |
comment | コメントをしたため |
mention | @でユーザーに対してmentionが来たため |
team_mention | @でOrganizationかTeamに対してmentionが来たため |
state_change | threadのstateが変更されたため 例えばIssueがcloseされたりPull Requestがmergeされたりなど |
assign | Issueにassignされたため |
Notificationの一覧取得
GET /notifications
パラメータ:
パラメータ名 | 型 | 説明 |
---|---|---|
all | boolean | trueにした場合、既読のNotificationも取得する デフォルトはfalse |
participating | boolean | trueにした場合、Issueをsubscribeにした時やmentionが来た時などユーザーに直接関わりがあるNotificationのみ取得する デフォルトはfalse |
since | string | 指定した日時より後のNotificationを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 デフォルトはTime.now |
before | string | 指定した日時より前のNotificationを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
リポジトリに紐付くNotificationの一覧取得
GET /repos/:owner/:repo/notifications
パラメータ名 | 型 | 説明 |
---|---|---|
all | boolean | trueにした場合、既読のNotificationも取得する デフォルトはfalse |
participating | boolean | trueにした場合、Issueをsubscribeにした時やmentionが来た時などユーザーに直接関わりがあるNotificationのみ取得する デフォルトはfalse |
since | string | 指定した日時より後のNotificationを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 デフォルトはTime.now |
before | string | 指定した日時より前のNotificationを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
Notificationを既読にする
PUT /notifications
パラメータ名 | 型 | 説明 |
---|---|---|
last_read_at | string | 既読にした日時を指定できます 現在の日時よりも未来の日時は指定できません フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
リポジトリに紐付くNotificationを既読にする
PUT /repos/:owner/:repo/notifications
パラメータ名 | 型 | 説明 |
---|---|---|
last_read_at | string | 既読にした日時を指定できます 現在の日時よりも未来の日時は指定できません フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
指定したthreadを取得する
GET /notifications/threads/:id
threadを既読にする
PATCH /notifications/threads/:id
threadのwatch設定
threadに紐付くNotificationを受け取るかどうかなどの設定が出来る
PUT /notifications/threads/:id/subscription
パラメータ名 | 型 | 説明 |
---|---|---|
subscribed | boolean | 指定したthreadからNotificationを受け取るかどうか |
ignored | boolean | 指定したthreadからのNotificationをブロックするかどうか |
threadのwatchを削除
DELETE /notifications/threads/:id/subscription
スター
リポジトリをstarしたユーザーの一覧取得
GET /repos/:owner/:repo/stargazers
ユーザーがstarしたリポジトリの一覧取得
GET /users/:username/starred
パラメータ名 | 型 | 説明 |
---|---|---|
sort | string | starした順に表示するcreated か、リポジトリの最終更新日順に表示する updated の2つが選べるデフォルトは created
|
direction | string | 昇順のasc 、降順のdesc が選べるデフォルトは desc
|
認証済みユーザーがstarしたリポジトリの一覧取得
GET /user/starred
パラメータ名 | 型 | 説明 |
---|---|---|
sort | string | starした順に表示するcreated か、リポジトリの最終更新日順に表示する updated の2つが選べるデフォルトは created
|
direction | string | 昇順のasc 、降順のdesc が選べるデフォルトは desc
|
リポジトリをstarしているかどうか取得
GET /user/starred/:owner/:repo
リポジトリをstarする
PUT /user/starred/:owner/:repo
リポジトリをunstarする
DELETE /user/starred/:owner/:repo
ウォッチ
リポジトリをwatchしているユーザーを一覧取得
GET /repos/:owner/:repo/subscribers
ユーザーがwatchしているリポジトリを一覧取得
GET /users/:username/subscriptions
認証済みユーザーがwatchしているリポジトリを一覧取得
GET /user/subscriptions
リポジトリのwatch状態を取得
GET /repos/:owner/:repo/subscription
リポジトリのwatch状態を設定
PUT /repos/:owner/:repo/subscription
パラメータ名 | 型 | 説明 |
---|---|---|
subscribed | boolean | 指定したリポジトリからNotificationを受け取るかどうか |
ignored | boolean | 指定したリポジトリからのNotificationをブロックするかどうか |
リポジトリのwatchを停止する
DELETE /repos/:owner/:repo/subscription
Gist
パブリックなgistやチームの作成はトークンが無くても可能です。
ただし、gistの読み取り/書き込みにはOAuth2認証によるgist
スコープが必要です。
また、もし取得するgistが1MBを超えていた場合、truncated
キーがtrueであるならcontent
にはgistの一部しか入らないようになります。
もし、gistの全てを取得したいのならraw_url
のURLからGETリクエストしてきてください。
gistが10MBを超えるならば、git_pull_url
からcloneしてこないといけないため注意してください。
gistが300ファイルを超えた場合には、truncated
キーがtrueであるなら最初の300ファイル分しか内容が取得されないので、もし超過分のファイルの中身を参照したい場合はgit_pull_url
からcloneしてきてください。
一覧取得は以下のパラメータが共通です。
パラメータ名 | 型 | 説明 |
---|---|---|
since | string | 指定した日時より後に作成・更新されたgistを取得 フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
ユーザーのgistを一覧取得
GET /users/:username/gists
認証済みユーザーのgistを一覧取得
GET /gists
パブリックなgistの一覧取得
GET /gists/public
認証済みユーザーがstarしたgistの一覧取得
GET /gists/starred
指定したgistの取得
GET /gists/:id
指定したリビジョンのgistを取得
GET /gists/:id/:sha
gistの作成
POST /gists
インプット名 | 型 | 説明 |
---|---|---|
files | object |
必須項目 ファイル名と内容を指定します |
description | string | gistの説明 |
public | boolean | gistをパブリックにするかどうか デフォルトは false
|
- インプット例
{
"description": "the description for this gist",
"public": true,
"files": {
"file1.txt": {
"content": "String file contents"
}
}
}
gistの編集
PATCH /gists/:id
インプット名 | 型 | 説明 |
---|---|---|
files | object | ファイル名と内容を指定します |
description | string | gistの説明 |
content | string | gistの内容 |
filename | string | gist名 |
- インプット例
{
"description": "the description for this gist",
"files": {
"file1.txt": {
"content": "updated file contents"
},
"old_name.txt": {
"filename": "new_name.txt",
"content": "modified contents"
},
"new_file.txt": {
"content": "a new file"
},
"delete_this_file.txt": null
}
}
指定したgistのcommitを一覧取得
GET /gists/:id/commits
gistにstar
PUT /gists/:id/star
gistをunstar
DELETE /gists/:id/star
gistがstarしているかチェック
GET /gists/:id/star
gistをfork
POST /gists/:id/forks
gistをforkしたユーザーの一覧取得
GET /gists/:id/forks
gistの削除
DELETE /gists/:id
gistに対するコメントの一覧取得
GET /gists/:gist_id/comments
gistに対するコメントの一つを取得
GET /gists/:gist_id/comments/:id
コメントの作成
POST /gists/:gist_id/comments
インプット名 | 型 | 説明 |
---|---|---|
body | string |
必須項目 コメント内容 |
- インプット例
{
"body": "Just commenting for the sake of commenting"
}
コメントの編集
PATCH /gists/:gist_id/comments/:id
インプット名 | 型 | 説明 |
---|---|---|
body | string |
必須項目 コメント内容 |
- インプット例
{
"body": "Just commenting for the sake of commenting"
}
コメントの削除
DELETE /gists/:gist_id/comments/:id
Gitデータ
blob,tree,commitといったGitオブジェクトを操作することが出来るAPI群です。
Blobs
Blobオブジェクトの取得
GET /repos/:owner/:repo/git/blobs/:sha
レスポンスのcontent
の内容はBase64でエンコードされています。
注意点としてこのAPIでは100MBまでのblobをサポートしています。
Blobオブジェクトの作成
POST /repos/:owner/:repo/git/blobs
パラメータ名 | 型 | 説明 |
---|---|---|
content | string |
必須項目 blobオブジェクトの内容 |
encoding | string |
content のエンコーディングが選べるutf-8 とbase64 のどちらかを選択できますデフォルトは utf-8
|
- インプット例
{
"content": "Content of the blob",
"encoding": "utf-8"
}
コミット
Commitオブジェクトの取得
GET /repos/:owner/:repo/git/commits/:sha
Commitオブジェクトの生成
POST /repos/:owner/:repo/git/commits
パラメータ名 | 型 | 説明 |
---|---|---|
message | string |
必須項目 コミットメッセージ |
tree | string |
必須項目 指定したtreeオブジェクトのSHAにコミットします |
parents | array of strings |
必須項目 コミットの親となるコミットのSHAを指定する パラメータを省略、または空にした場合、コミットはルートコミットとして扱われます |
name | string | 作成者かコミッターとしての名前 |
string | 作成者かコミッターとしてのメールアドレス | |
date | string | コミット日 フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
- インプット例
{
"message": "my commit message",
"author": {
"name": "Scott Chacon",
"email": "schacon@gmail.com",
"date": "2008-07-09T16:13:30+12:00"
},
"parents": [
"7d1b31e74ee336d15cbd21741bc88a537ed063a0"
],
"tree": "827efc6d56897b048c772eb4087f854f46256132"
}
リファレンス
Referenceの取得
GET /repos/:owner/:repo/git/refs/:ref
:ref
の指定はbranch
のみの指定ではなく、heads/branch
のような形で指定してください。
例えば、skunkworkz/featureA
の指定の場合、以下の様なURLになります。
GET /repos/:owner/:repo/git/refs/heads/skunkworkz/featureA
全てのReferenceの取得
GET /repos/:owner/:repo/git/refs
URLにtags
などサブネームスペースを設定することもできます。
例.
GET /repos/:owner/:repo/git/refs/tags
Referenceの作成
POST /repos/:owner/:repo/git/refs
パラメータ名 | 型 | 説明 |
---|---|---|
ref | type |
必須項目 リファレンス名(例.refs/heads/master) 注意点として refs で始まり、/を2つ持たないとエラーになります |
sha | type |
必須項目 リファレンスのSHA1の値 |
- インプット例
{
"ref": "refs/heads/featureA",
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd"
}
Referenceの編集
PATCH /repos/:owner/:repo/git/refs/:ref
パラメータ名 | 型 | 説明 |
---|---|---|
sha | type |
必須項目 設定するSHA1の値 |
force | boolean | 強制的に変更を反映させる デフォルトは false
|
- インプット例
{
"sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
"force": true
}
Referenceの削除
DELETE /repos/:owner/:repo/git/refs/:ref
- branchを削除する時の例
DELETE /repos/octocat/Hello-World/git/refs/heads/feature-a
- tagを削除する時の例
DELETE /repos/octocat/Hello-World/git/refs/tags/v1.0
タグ
Tagの取得
GET /repos/:owner/:repo/git/tags/:sha
Tagオブジェクトの作成
もし注釈付きタグを作成する場合は、このAPIでタグを作成してからReferenceの作成でrefs/tags/[tag]
を実行してください。
POST /repos/:owner/:repo/git/tags
パラメータ名 | 型 | 説明 |
---|---|---|
tag | string | タグ名 |
message | string | タグメッセージ |
object | string | タグ付けされているGitオブジェクトのSHA |
type | string | タグ付けしているオブジェクトの種類 通常は commit ですがtree やblob を指定することもできます |
tagger | object | タグの作成者に関する情報 |
tagger
には以下のキーを設定できます。
キー名 | 型 | 説明 |
---|---|---|
name | string | 作成者名 |
string | 作成者のメールアドレス | |
date | string | タグ付けした日時 フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
- インプット例
{
"tag": "v0.0.1",
"message": "initial version\n",
"object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
"type": "commit",
"tagger": {
"name": "Scott Chacon",
"email": "schacon@gmail.com",
"date": "2011-06-17T14:53:35-07:00"
}
}
ツリー
Treeの取得
GET /repos/:owner/:repo/git/trees/:sha
Treeを再帰的に取得
GET /repos/:owner/:repo/git/trees/:sha?recursive=1
Treeの作成
POST /repos/:owner/:repo/git/trees
パラメータ名 | 型 | 説明 |
---|---|---|
tree | array of objects | 必須項目 オブジェクト(path, mode, type, sha)でツリー構造を指定する |
base_tree | string | 新しいデータで更新するtreeのSHA もし設定しない場合、コミットは一番上で作成されます |
tree
には以下のキーを設定できます。
キー名 | 型 | 説明 |
---|---|---|
path | string | treeで参照されるファイル |
mode | string | ファイルのモードを指定する100644 :ファイル(blob)100755 :実行ファイル(blob)040000 :サブディレクトリ(tree)160000 :サブモジュール(commit)120000 :シンボリックリンクのパス(blob) |
type | string |
blob ,tree ,commit のいずれか |
sha | string | tree内のオブジェクトのSHA1チェックサムID |
content | string | ファイルの内容を指定する Githubがこのblobを書き出し、SHAを使用します SHAは指定したものか tree.sha を使用します |
- インプット例
{
"base_tree": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
"tree": [
{
"path": "file.rb",
"mode": "100644",
"type": "blob",
"sha": "44b4fc6d56897b048c772eb4087f854f46256132"
}
]
}
イシュー
Issueを一覧取得
一覧取得は以下のパラメータが共通です。
パラメータ名 | 型 | 説明 |
---|---|---|
filter | string | 取得する一覧をフィルタリングしますassigned :ユーザーがアサインされているIssuecreated :ユーザーが作成したIssuementioned :ユーザーがmentionしたIssuesubscribed :subscribeしたIssueall :全てのIssueデフォルトは assigned
|
state | string | 取得するIssueの状態を指定するopen ,closed ,all のいずれかを指定デフォルトは open
|
labels | string | カンマで区切られたラベル名 例として bug ,ui ,@high など |
sort | string | ソート基準を指定するcreated ,updated ,comments のいずれかを指定デフォルトは created
|
direction | string | ソート順を指定するasc もしくはdesc を指定デフォルトは desc
|
since | string | 指定した日時より後に更新されたIssueを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
owner,member,organizationのリポジトリのIssue
GET /issues
owner,memberのリポジトリのIssue
GET /user/issues
organizationのリポジトリのIssue
GET /orgs/:org/issues
リポジトリに紐付くIssueを一覧取得
GET /repos/:owner/:repo/issues
パラメータ名 | 型 | 説明 |
---|---|---|
milestone | integer or string |
integer を指定した場合、その番号のマイルストーンを参照するstring の* を指定した場合、全てのmilestoneに紐づくIssueを取得するstring のnone を指定した場合、milestoneに紐付かないIssueを取得する |
state | string | 取得するIssueの状態を指定するopen ,closed ,all のいずれかを指定デフォルトは open
|
assignee | string | アサインされているユーザー名を指定するnone を指定すると誰もassignされていないIssueを取得する* を指定するとユーザーがアサインされている全てのIssueを取得する |
creator | string | 指定したユーザーが作成したIssueを取得する |
mentioned | string | 指定したユーザーがmentionされているIssueを取得する |
labels | string | カンマで区切られたラベル名 例として bug ,ui ,@high など |
sort | string | ソート基準を指定するcreated ,updated ,comments のいずれかを指定デフォルトは created
|
direction | string | ソート順を指定するasc もしくはdesc を指定デフォルトは desc
|
since | string | 指定した日時より後に更新されたIssueを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
一つのIssueを取得
GET /repos/:owner/:repo/issues/:number
Issueの作成
POST /repos/:owner/:repo/issues
パラメータ名 | 型 | 説明 |
---|---|---|
title | string |
必須項目 Issueのタイトル |
body | string | Issueの内容 |
assignee | string | アサインするユーザー もしアサインできないユーザーを指定した場合、エラーにならずアサインなしで処理されます |
milestone | integer | 指定した番号のマイルストーンと関連付ける もし関連付けできないマイルストーンを指定した場合、エラーにならずマイルストーンなしで処理されます |
labels | array of strings | 指定したラベルを関連付けます もし関連付けできないラベルを指定した場合、エラーにならずラベルなしで処理されます |
- 例
{
"title": "Found a bug",
"body": "I'm having a problem with this.",
"assignee": "octocat",
"milestone": 1,
"labels": [
"Label1",
"Label2"
]
}
Issueの編集
PATCH /repos/:owner/:repo/issues/:number
パラメータ名 | 型 | 説明 |
---|---|---|
title | string | Issueのタイトル |
body | string | Issueの内容 |
assignee | string | アサインするユーザー もしアサインできないユーザーを指定した場合、エラーにならずアサインなしで処理されます |
state | string | Issueの状態を指定するopen かclosed を指定する |
milestone | integer | 指定した番号のマイルストーンと関連付けるnull を指定した場合、現在関連付いているマイルストーンが外れますもし関連付けできないマイルストーンを指定した場合、エラーにならずマイルストーンなしで処理されます |
labels | array of strings | 指定したラベルを関連付けます 空の配列 [] を指定した場合、全てのLabelが外れますもし関連付けできないラベルを指定した場合、エラーにならずラベルなしで処理されます |
- 例
{
"title": "Found a bug",
"body": "I'm having a problem with this.",
"assignee": "octocat",
"milestone": 1,
"state": "open",
"labels": [
"Label1",
"Label2"
]
}
アサイン
assignできるユーザーを一覧取得
GET /repos/:owner/:repo/assignees
ユーザーがアサインされているかチェックする
GET /repos/:owner/:repo/assignees/:assignee
コメント
Issueに対するコメントのAPIで、listing
,viewing
,editing
,creating
の処理に対応しています。
Issueに対するCommentsを一覧取得
GET /repos/:owner/:repo/issues/:number/comments
コメントはIDを基準に昇順に列挙されます。
パラメータ名 | 型 | 説明 |
---|---|---|
since | string | 指定した日時より後に更新されたコメントを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
リポジトリに紐付くIssueのCommentsを一覧取得
GET /repos/:owner/:repo/issues/comments
デフォルトではコメントはIDを基準に昇順に列挙されます。
パラメータ名 | 型 | 説明 |
---|---|---|
sort | string | ソートをcreated かupdated か指定するデフォルトは created
|
direction | string | ソート順をasc かdesc か指定するsort パラメータが指定されていない場合、direction は無視されます |
since | string | 指定した日時より後に更新されたコメントを取得する フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
特定のCommentを取得
GET /repos/:owner/:repo/issues/comments/:id
Commentを作成する
POST /repos/:owner/:repo/issues/:number/comments
インプット名 | 型 | 説明 |
---|---|---|
body | string |
必須項目 commentの内容 |
- インプット例
{
"body": "Me too"
}
Commentの編集
PATCH /repos/:owner/:repo/issues/comments/:id
インプット名 | 型 | 説明 |
---|---|---|
body | string |
必須項目 commentの内容 |
- インプット例
{
"body": "Me too"
}
Commentの削除
DELETE /repos/:owner/:repo/issues/comments/:id
イベント
対応しているEventは以下になります。
- closed
- reopened
- subscribed
- merged
- referenced
- mentioned
- assigned
- unassigned
- labeled
- unlabeled
- milestoned
- demilestoned
- renamed
- locked
- unlocked
- head_ref_deleted:Pull Requestのブランチが削除された時に発生
- head_ref_restored:Pull Requestのブランチがレストアされた時に発生
Issueに対するEventsを一覧取得
GET /repos/:owner/:repo/issues/:issue_number/events
リポジトリに紐付くIssueのEventsを一覧取得
GET /repos/:owner/:repo/issues/events
特定のEventを取得
GET /repos/:owner/:repo/issues/events/:id
ラベル
リポジトリに紐付くlabelsを一覧取得
GET /repos/:owner/:repo/labels
特定のlabelを取得
GET /repos/:owner/:repo/labels/:name
labelを作成
POST /repos/:owner/:repo/labels
パラメータ名 | 型 | 説明 |
---|---|---|
name | string |
必須項目 labelの名前 |
color | string |
必須項目ffffff のようにHEXで指定 |
- 例
{
"name": "bug",
"color": "f29513"
}
labelの編集
PATCH /repos/:owner/:repo/labels/:name
パラメータ名 | 型 | 説明 |
---|---|---|
name | string |
必須項目 labelの名前 |
color | string |
必須項目ffffff のようにHEXで指定 |
- 例
{
"name": "bug",
"color": "f29513"
}
labelの削除
DELETE /repos/:owner/:repo/labels/:name
Issueのlabelsを一覧取得
GET /repos/:owner/:repo/issues/:number/labels
Issueにlabelを追加
POST /repos/:owner/:repo/issues/:number/labels
- インプット例
[
"Label1",
"Label2"
]
Issueのlabelを削除
DELETE /repos/:owner/:repo/issues/:number/labels/:name
Issueの全てのlabelを変更
PUT /repos/:owner/:repo/issues/:number/labels
- インプット例
[
"Label1",
"Label2"
]
Issueの全てのlabelを削除
DELETE /repos/:owner/:repo/issues/:number/labels
マイルストーンに紐付く全てのIssueのlabelを一覧取得
GET /repos/:owner/:repo/milestones/:number/labels
マイルストーン
リポジトリに紐付くmilestonesを一覧取得
GET /repos/:owner/:repo/milestones
パラメータ名 | 型 | 説明 |
---|---|---|
state | string | milestoneの状態をopen ,closed ,all から指定デフォルトは open
|
sort | string | ソートをdue_on ,completeness から指定デフォルトは due_on
|
direction | string | ソート順をasc ,desc から指定デフォルトは asc
|
特定のmilestoneを取得
GET /repos/:owner/:repo/milestones/:number
milestoneを作成
POST /repos/:owner/:repo/milestones
インプット名 | 型 | 説明 |
---|---|---|
title | string |
必須項目 milestoneのタイトル |
state | string | milestoneの状態をopen ,closed ,all から指定デフォルトは open
|
description | string | milestoneの説明 |
due_on | string | milestoneの期日 フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
- インプット例
{
"title": "v1.0",
"state": "open",
"description": "Tracking milestone for version 1.0",
"due_on": "2012-10-09T23:39:01Z"
}
milestoneの編集
PATCH /repos/:owner/:repo/milestones/:number
インプット名 | 型 | 説明 |
---|---|---|
title | string | milestoneのタイトル |
state | string | milestoneの状態をopen ,closed ,all から指定デフォルトは open
|
description | string | milestoneの説明 |
due_on | string | milestoneの期日 フォーマットはYYYY-MM-DDTHH:MM:SSz、規格はISO 8601 |
- インプット例
{
"title": "v1.0",
"state": "open",
"description": "Tracking milestone for version 1.0",
"due_on": "2012-10-09T23:39:01Z"
}
milestoneの削除
DELETE /repos/:owner/:repo/milestones/:number
様々なデータ
Githubで用意している絵文字やGitignore,Licenseなどのリソースにアクセスすることが出来ます。
絵文字
Emojisを一覧取得
GET /emojis
Gitignore
使用できるGitignoreテンプレートを一覧取得
GET /gitignore/templates
特定のテンプレートを取得
GET /gitignore/templates/C
ライセンス
注意:このAPIは開発者向けのプレビュー状態です。APIの仕様が変更になる可能性が高いため注意してください。
またプレビュー状態のAPIを使用するには、Accept
ヘッダーに以下を追加してください。
application/vnd.github.drax-preview+json
ライセンスを一覧取得
GET /licenses
特定のライセンスを取得
GET /licenses/:license_name
リポジトリに紐付くライセンスを取得
リポジトリにライセンスファイルが存在した場合に取得します。
GET /repos/:owner/:repo
リポジトリに紐付くライセンスファイルを取得
このAPIはカスタムメディアタイプをサポートしており、生のライセンスファイルやライセンスのHTMLを取得します。
GET /repos/:owner/:repo/license
マークダウン
マークダウンドキュメントのレンダリング
POST /markdown
パラメータ名 | 型 | 説明 |
---|---|---|
text | string |
必須項目 マークダウンのテキスト |
mode | string | レンダリングモードの指定 以下のいずれかを指定できます markdown :READMEファイルがレンダリングされるようにプレーンなマークダウンをレンダリングしますgfm :GitHub Flavored Markdown の略で、Github独自のマークダウンです(参考:翻訳 GitHub Help - GitHub Flavored Markdown)デフォルトは markdown
|
context | string | リポジトリコンテキストの指定 モードに gfm を指定した場合のみ指定する |
- 例
{
"text": "Hello world github/linguist#1 **cool**, and #1!",
"mode": "gfm",
"context": "github/gollum"
}
マークダウンドキュメントをプレーンテキストでレンダリングする
マークダウンドキュメントをtext/plain
かtext/x-markdown
で取得し、レンダリングします。
POST /markdown/raw
メタ
Github.comのサービスに関する情報を取得します。
GET /meta
- レスポンス
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
"verifiable_password_authentication": true,
"github_services_sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
"hooks": [
"127.0.0.1/32"
],
"git": [
"127.0.0.1/32"
],
"pages": [
"192.30.252.153/32",
"192.30.252.154/32"
]
}
パラメータ名 | 型 | 説明 |
---|---|---|
verifiable_password_authentication | boolean | ユーザー名とパスワードで認証されているか |
github_services_sha | string | github-servicesのデプロイされている現在のSHA |
hooks | array of strings | Github.comから発信されているIncomming WebhookのIPアドレスがCIDR形式で配列で記述 |
git | array of strings | Github.comのGitサーバのIPアドレスがCIDR形式で配列で記述 |
pages | array of strings | Github PagesのIPアドレスがCIDR形式で配列で記述 |
APIレートリミット
現在のレートリミットを取得します。
APIレートリミットについては以下を参照。
https://developer.github.com/v3/#rate-limiting
現在のレートリミットステータスを取得
GET /rate_limit
- レスポンス例
{
"resources": {
"core": {
"limit": 5000,
"remaining": 4999,
"reset": 1372700873
},
"search": {
"limit": 30,
"remaining": 18,
"reset": 1372697452
}
},
"rate": {
"limit": 5000,
"remaining": 4999,
"reset": 1372700873
}
}
resources
のcore
はAPIのリミット等を表示し、search
はSearchAPIに関するリミット等を表しています。
search
に該当するAPIは、後述のSearchの項目のAPIになります。
これらは1分ごとにremaining
がリセットされます。
rate
については廃止予定の項目で、次回のAPIのバージョンアップに合わせて削除されるようです。
オーガナイゼーション
オーガナイゼーション
認証済みユーザーのオーガナイゼーションを一覧取得
read:org
かuser
のスコープが設定されていないと取得することが出来ず、403 Forbidden
がレスポンスされますので注意してください。
GET /user/orgs
すべてのオーガナイゼーションを一覧取得
Github上で作成されたオーガナイゼーションを作成された順で表示します。
GET /organizations
パラメータ名 | 型 | 説明 |
---|---|---|
since | string | 取得し始めるIDを指定 |
特定のユーザーのオーガナイゼーションを一覧取得
特定のユーザーのパブリックとして設定されているオーガナイゼーションを取得します。
GET /users/:username/orgs
特定のオーガナイゼーションを取得
GET /orgs/:org
オーガナイゼーションの編集
PATCH /orgs/:org
インプット名 | 型 | 説明 |
---|---|---|
billing_email | string | 請求先として設定されるメールアドレス このメールアドレスは公開されません |
company | string | 会社名 |
string | 公開されるメールアドレス | |
location | string | 場所 |
name | string | 会社名の略称 |
description | string | 会社説明 |
- インプット例
{
"billing_email": "support@github.com",
"blog": "https://github.com/blog",
"company": "GitHub",
"email": "support@github.com",
"location": "San Francisco",
"name": "github",
"description": "GitHub, the company."
}
メンバー
メンバーを一覧取得
オーガナイゼーションに属するユーザーをすべて取得します。
認証済みユーザーが実行した場合、プライベート・パブリックともすべてのユーザーが取得できます。
GET /orgs/:org/members
パラメータ名 | 型 | 説明 |
---|---|---|
filter | string | 取得するユーザーをフィルタリングします 以下のいずれかを選択できます 2fa_disabled :2段階認証が有効になっているユーザーを除外します(2段階認証が無効になっている危険なユーザーを絞り込めます)all :すべてのユーザーを表示しますデフォルトは all
|
role | string | ユーザーの役割によってフィルタリングします 以下のいずれかを選択できます all :すべてのユーザーを表示しますadmin :オーナー権限を持っているユーザーのみ表示member :オーナー権限を持っていないユーザーのみ表示デフォルトは all
|
メンバーシップのチェック
ユーザーがパブリックかプライベートか、オーガナイゼーションに所属しているかを調べることが出来ます。
GET /orgs/:org/members/:username
- API実行者がメンバーで、指定ユーザーもメンバーの場合のレスポンス
Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
- API実行者がメンバーで、指定ユーザーがメンバーでない場合のレスポンス
Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
- API実行者がメンバーではなく、指定ユーザーがAPI実行者の場合のレスポンス
Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
- API実行者がメンバーではない場合のレスポンス
Status: 302 Found
Location: https://api.github.com/orgs/github/public_members/pezra
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
メンバーの削除
DELETE /orgs/:org/members/:username
パブリックなメンバーを一覧取得
GET /orgs/:org/public_members
特定のユーザーがパブリックかチェック
GET /orgs/:org/public_members/:username
- パブリックである場合のレスポンス
Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
- パブリックでない場合のレスポンス
Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
特定のユーザーをパブリックにする
指定したオーガナイゼーションで特定のユーザーをパブリックにすることができます。
PUT /orgs/:org/public_members/:username
特定のユーザーをプライベートにする
DELETE /orgs/:org/public_members/:username
特定ユーザーのメンバーシップの取得
オーナー権限を持っているユーザーのみが実行できます。
GET /orgs/:org/memberships/:username
メンバーシップの追加・更新
オーナー権限を持っているユーザーのみが実行できます。
PUT /orgs/:org/memberships/:username
パラメータ名 | 型 | 説明 |
---|---|---|
role | string |
必須項目 以下のいずれかを選択できます admin :オーナー権限member :メンバー権限 |
メンバーシップの削除
オーナー権限を持っているユーザーのみが実行できます。
メンバーシップを削除するとオーガナイゼーションからも削除されますのでご注意ください。
DELETE /orgs/:org/memberships/:username
メンバーシップを一覧取得
GET /user/memberships/orgs
パラメータ名 | 型 | 説明 |
---|---|---|
state | string | 以下のいずれかを選択できますactive :アクティブ状態のユーザーを取得pending :ペンディング状態のユーザーを取得 |
特定のオーガナイゼーションのメンバーシップを取得
GET /user/memberships/orgs/:org
特定のオーガナイゼーションのメンバーシップを編集
PATCH /user/memberships/orgs/:org
インプット名 | 型 | 説明 |
---|---|---|
state | string |
必須項目 以下のいずれかを選択できます active :アクティブ状態のユーザーを取得pending :ペンディング状態のユーザーを取得 |
マイグレーション
マイグレーションAPIにアクセスするにはAccept
ヘッダーに以下を指定してください。
application/vnd.github.wyandotte-preview+json
マイグレーションのスタート
マイグレーションアーカイブを生成します。
POST /orgs/:org/migrations
インプット名 | 型 | 説明 |
---|---|---|
repositories | array of strings |
必須項目 移行するリポジトリ名を指定 |
lock_repositories | boolean | データの移行中にリポジトリをロックするか指定 デフォルトは false
|
exclude_attachments | boolean | 添付ファイルを移行に含めるかどうか指定 デフォルトは false
|
- インプット例
{
"repositories": [
"octocat/Hello-World"
],
"lock_repositories": true
}
マイグレーションを一覧取得
GET /orgs/:org/migrations
特定のマイグレーションのステータスを取得
GET /orgs/:org/migrations/:id
ステータスには以下があります。
-
pending
:マイグレーション開始前 -
exporting
:マイグレーション中 -
exported
:マイグレーション完了 -
failed
:マイグレーション失敗
マイグレーションアーカイブのダウンロード
マイグレーションアーカイブがダウンロード出来るURLを取得します。
GET /orgs/:org/migrations/:id/archive
マイグレーションアーカイブの削除
マイグレーションアーカイブを削除出来ます。
ただしマイグレーションアーカイブは実行後、7日後に自動的に削除されます。
DELETE /orgs/:org/migrations/:id/archive
リポジトリのアンロック
移行後に不必要になったリポジトリはアンロックして削除する必要があります。
DELETE /orgs/:org/migrations/:id/repos/:repo_name/lock
チーム
チームに関するAPIを実行するには:org
スコープが必要。
取得するAPIに関してはread:org
スコープのみでも実行可能。
チームを一覧取得
GET /orgs/:org/teams
特定のチームを取得
GET /teams/:id
チームの作成
POST /orgs/:org/teams
パラメータ名 | 型 | 説明 |
---|---|---|
name | string |
必須項目 チーム名 |
description | string | チーム説明 |
repo_names | array of strings | チームに追加するリポジトリ名 指定例."organization-name/repository-name" |
privacy | string | チームのプライバシーレベルを以下から選択できますsecret :オーナーとチームメンバーにのみ表示オーガナイゼーションに所属する全メンバーに表示 デフォルトは secret
|
permission | string |
非推奨 新しく追加されたリポジトリに対するチームのパーミッションを以下から選択できます pull :pullすることのみ可能push :pullとpushすることが可能admin :pull、pushが可能で管理権限を持つことができるデフォルトは pull
|
- 例
{
"name": "new team",
"description": "team description",
"privacy": "closed"
}
チームの編集
PATCH /teams/:id
パラメータ名 | 型 | 説明 |
---|---|---|
name | string |
必須項目 チーム名 |
description | string | チーム説明 |
privacy | string | チームのプライバシーレベルを以下から選択できますsecret :オーナーとチームメンバーにのみ表示オーガナイゼーションに所属する全メンバーに表示 デフォルトは secret
|
permission | string |
非推奨 新しく追加されたリポジトリに対するチームのパーミッションを以下から選択できます pull :pullすることのみ可能push :pullとpushすることが可能admin :pull、pushが可能で管理権限を持つことができるデフォルトは pull
|
注意: permission
のパラメータについてはプレビュー状態です。仕様が変更になる可能性が高いため注意してください。
またプレビュー状態のpermission
を使用するには、Acceptヘッダーに以下を追加してください。
application/vnd.github.ironman-preview+json
- 例
{
"name": "new team name",
"description": "new team description",
"privacy": "closed"
}
チームの削除
DELETE /teams/:id
特定のチームのメンバーを一覧取得
GET /teams/:id/members
パラメータ名 | 型 | 説明 |
---|---|---|
role | string | メンバーの役割でフィルタリングしますmember :チームメンバーmaintainer :メンテナーall :全てのメンバーデフォルトは all
|
特定のチームメンバーを取得
注意:このAPIは次のバージョンアップで廃止されます。
このAPIの代わりに特定ユーザーのメンバーシップの取得を使うことを推奨します。
チームメンバーの追加
注意:このAPIは次のバージョンアップで廃止されます。
このAPIの代わりにメンバーシップの追加・更新を使うことを推奨します。
チームメンバーの削除
注意:このAPIは次のバージョンアップで廃止されます。
このAPIの代わりにメンバーシップの削除を使うことを推奨します。
チームのメンバーシップの取得
GET /teams/:id/memberships/:username
- メンバーシップがactiveの場合のレスポンス
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "active"
}
- メンバーシップがpendingの場合のレスポンス
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "pending"
}
- メンバーシップがない場合のレスポンス
Status: 404 Not Found
チームのメンバーシップの追加
追加するユーザーが既にオーガナイゼーションのメンバーである場合、何の条件もなしに追加されます。
オーガナイゼーションのメンバーでない場合は、先にオーガナイゼーションのメンバーとして追加する必要があるため、APIの実行者はオーガナイゼーションのオーナーかチームのメンテナーである必要があります。
追加するユーザーがオーガナイゼーションのメンバーでない場合は、招待のメールが届く挙動になります。
PUT /teams/:id/memberships/:username
パラメータ名 | 型 | 説明 |
---|---|---|
role | string | メンバーの役割でフィルタリングしますmember :チームメンバーmaintainer :メンテナーall :全てのメンバーデフォルトは all
|
- メンバーシップがactiveの場合のレスポンス
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "active"
}
- メンバーシップがpendingの場合のレスポンス
{
"url": "https://api.github.com/teams/1/memberships/octocat",
"role": "member",
"state": "pending"
}
- オーガナイゼーションのメンバーでない場合のレスポンス
{
"message": "Cannot add an organization as a member.",
"errors": [
{
"code": "org",
"field": "user",
"resource": "TeamMember"
}
]
}
チームのメンバーシップの削除
このAPIはadmin
権限を持っているメンバーか、オーガナイゼーションのオーナーのみ実行できます。
DELETE /teams/:id/memberships/:username
チームのリポジトリを一覧取得
GET /teams/:id/repos
特定のリポジトリをチームが管理しているかチェック
GET /teams/:id/repos/:owner/:repo
- 管理している場合のレスポンス
Status: 204 No Content
- 管理していない場合のレスポンス
Status: 404 Not Found
またAccept
ヘッダーに以下を指定することで更にそのリポジトリの情報を取得することも出来ます。
Accept: application/vnd.github.v3.repository+json
- レスポンス
{
"id": 1296269,
"owner": {
"login": "octocat",
"id": 1,
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
},
"name": "Hello-World",
"full_name": "octocat/Hello-World",
"description": "This your first repo!",
"private": false,
"fork": true,
"url": "https://api.github.com/repos/octocat/Hello-World",
"html_url": "https://github.com/octocat/Hello-World",
"archive_url": "http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
"assignees_url": "http://api.github.com/repos/octocat/Hello-World/assignees{/user}",
"blobs_url": "http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
"branches_url": "http://api.github.com/repos/octocat/Hello-World/branches{/branch}",
"clone_url": "https://github.com/octocat/Hello-World.git",
"collaborators_url": "http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
"comments_url": "http://api.github.com/repos/octocat/Hello-World/comments{/number}",
"commits_url": "http://api.github.com/repos/octocat/Hello-World/commits{/sha}",
"compare_url": "http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
"contents_url": "http://api.github.com/repos/octocat/Hello-World/contents/{+path}",
"contributors_url": "http://api.github.com/repos/octocat/Hello-World/contributors",
"deployments_url": "http://api.github.com/repos/octocat/Hello-World/deployments",
"downloads_url": "http://api.github.com/repos/octocat/Hello-World/downloads",
"events_url": "http://api.github.com/repos/octocat/Hello-World/events",
"forks_url": "http://api.github.com/repos/octocat/Hello-World/forks",
"git_commits_url": "http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
"git_refs_url": "http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
"git_tags_url": "http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
"git_url": "git:github.com/octocat/Hello-World.git",
"hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks",
"issue_comment_url": "http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
"issue_events_url": "http://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
"issues_url": "http://api.github.com/repos/octocat/Hello-World/issues{/number}",
"keys_url": "http://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
"labels_url": "http://api.github.com/repos/octocat/Hello-World/labels{/name}",
"languages_url": "http://api.github.com/repos/octocat/Hello-World/languages",
"merges_url": "http://api.github.com/repos/octocat/Hello-World/merges",
"milestones_url": "http://api.github.com/repos/octocat/Hello-World/milestones{/number}",
"mirror_url": "git:git.example.com/octocat/Hello-World",
"notifications_url": "http://api.github.com/repos/octocat/Hello-World/notifications{?since, all, participating}",
"pulls_url": "http://api.github.com/repos/octocat/Hello-World/pulls{/number}",
"releases_url": "http://api.github.com/repos/octocat/Hello-World/releases{/id}",
"ssh_url": "git@github.com:octocat/Hello-World.git",
"stargazers_url": "http://api.github.com/repos/octocat/Hello-World/stargazers",
"statuses_url": "http://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
"subscribers_url": "http://api.github.com/repos/octocat/Hello-World/subscribers",
"subscription_url": "http://api.github.com/repos/octocat/Hello-World/subscription",
"svn_url": "https://svn.github.com/octocat/Hello-World",
"tags_url": "http://api.github.com/repos/octocat/Hello-World/tags",
"teams_url": "http://api.github.com/repos/octocat/Hello-World/teams",
"trees_url": "http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
"homepage": "https://github.com",
"language": null,
"forks_count": 9,
"stargazers_count": 80,
"watchers_count": 80,
"size": 108,
"default_branch": "master",
"open_issues_count": 0,
"has_issues": true,
"has_wiki": true,
"has_pages": false,
"has_downloads": true,
"pushed_at": "2011-01-26T19:06:43Z",
"created_at": "2011-01-26T19:01:12Z",
"updated_at": "2011-01-26T19:14:43Z",
"permissions": {
"admin": false,
"push": false,
"pull": true
}
}
リポジトリをチームに追加・更新
このAPIはリポジトリのadmin
権限を持っているユーザーかつ、オーガナイゼーション上に存在するリポジトリの場合のみ実行できます。
PUT /teams/:id/repos/:org/:repo
パラメータ名 | 型 | 説明 |
---|---|---|
permission | string | 新しく追加・更新されたリポジトリに対するチームのパーミッションを以下から選択できますpull :pullすることのみ可能push :pullとpushすることが可能admin :pull、pushが可能で管理権限を持つことができるデフォルトは pull
|
リポジトリをチームから削除
このAPIはリポジトリのadmin
権限を持っているユーザーか、チームのメンテナーのみ実行できます。
DELETE /teams/:id/repos/:owner/:repo
チームのユーザーを一覧取得
GET /user/teams