0. 總覽
本文爲大家提供一種使用 GitHub API 更新 GitHub 倉庫的方法。通常我們會使用 Git 客戶端 Commit 然後 Push 到 GitHub,但 GitHub 爲我們提供了相關 API,在某些情況下可以直接通過 API 更新倉庫。
在此之前有一些前置知識點,你需要了解 git 的儲存原理。碰巧最近掘金有一篇很火的文章有提到相關知識。
使用 GitHub API 更新倉庫只需六步。雖然對於第一次接觸的新手來說可能會有點複雜,但是理清關係之後思路便會很清晰了。
- 獲取 Ref:Ref 指 Git 的引用。如果要發起 Commit,必須知道你的 Commit 要提交到什麼地方去(Commit 是一個接一個的鏈狀關係,所以需要知道上一個 Commit 的信息),這一步做的就是這件事。
- 獲取 Commit:用於獲取當前 Commit 的 tree 的 sha。
- 生成 Blob:相當於正常本地提交的 add 操作,可以參考這裏的解釋。
- 生成 Tree:構建一個新的 tree,把上一步生成的 Blob 放到合適的位置。這裏需要用到的參數 base_tree 就是來自第二步的 Commit 信息。
- 生成 Commit:提交你的 tree,這步跟正常 commit 很接近,不過要你手動找到此次提交的上一次提交,借哈希值把新的 Commit 接起來。
- 更新 Ref:使 master 的指針指到你最新提交的版本。
注意:訪問 POST 方法的接口必須帶 token,雖然 GET 可以不帶,但是會限制訪問頻率,所以建議都帶上。相關文檔:https://developer.github.com/v3/#authentication
1. 獲取 Ref
1.1 文檔地址
https://developer.github.com/v3/git/refs/#get-a-reference
1.2 請求地址
GET https://api.github.com/repos/ssshooter/test/git/refs/heads/master
1.3 返回數據
{
"ref": "refs/heads/master",
"node_id": "MDM6UmVmMTY0Nzk4NDczOm1hc3Rlcg==",
"url": "https://api.github.com/repos/ssshooter/test/git/refs/heads/master",
"object": {
"sha": "cda66de943082033f4b761639df77728d7bca4f0",
"type": "commit",
"url": "https://api.github.com/repos/ssshooter/test/git/commits/cda66de943082033f4b761639df77728d7bca4f0"
}
}
2. 獲取 Commit
2.1 文檔地址
https://developer.github.com/v3/git/commits/#get-a-commit
2.2 請求地址
GET https://api.github.com/repos/ssshooter/test/git/commits/cda66de943082033f4b761639df77728d7bca4f0
2.3 返回數據
{
"sha": "cda66de943082033f4b761639df77728d7bca4f0",
"node_id": "MDY6Q29tbWl0MTY0Nzk4NDczOmNkYTY2ZGU5NDMwODIwMzNmNGI3NjE2MzlkZjc3NzI4ZDdiY2E0ZjA=",
"url": "https://api.github.com/repos/ssshooter/test/git/commits/cda66de943082033f4b761639df77728d7bca4f0",
"html_url": "https://github.com/ssshooter/test/commit/cda66de943082033f4b761639df77728d7bca4f0",
"author": {
"name": "DeJavuJo",
"email": "[email protected]",
"date": "2019-01-09T06:02:07Z"
},
"committer": {
"name": "GitHub",
"email": "[email protected]",
"date": "2019-01-09T06:02:07Z"
},
"tree": {
"sha": "d7a57d28ace0db12773c7d70675f94a48da6421f",
"url": "https://api.github.com/repos/ssshooter/test/git/trees/d7a57d28ace0db12773c7d70675f94a48da6421f"
},
"message": "Create readme.md",
"parents": [
],
"verification": {
"verified": true,
"reason": "valid",
"signature": "-----BEGIN PGP SIGNATURE-----\n\nwsBcBAABCAAQBQJcNY5fCRBK7hj4Ov3rIwAAdHIIABh8I89hATqg1mSYtpx1aY\nJt/woDobMO7FGE5qXO0NNrCMqwF6mdPJOMMMZvVWF1ULTm8ZJ52GAh5xAnPMZEnQ\n8tTjj/Qc0eZCm5B1xO66rgx+7eKkeGUPJj5bX7Lf0i9Se70Ff0jaCdH94RgiSL2d\nclDLhNyM4u6AH//k7S3Ud1O6ezXd4+99381Xa331PDLhJttUAbRFRCThszbcxRUT\nPvyhPNvXB5ug4J+tAMaZJvZEaED0c1k2Yx1+TYkLvPjOlqXvqaDVpMZieluD5l+f\nu13NAoCnLfBe0Skak/8MxRDbMcJYNW78ll60HAa6jJtElD8Vkek8WoVAZ8p3iIE=\n=xI87\n-----END PGP SIGNATURE-----\n",
"payload": "tree d7a57d28ace0db12773c7d70675f94a48da6421f\nauthor DeJavuJo 1547013727 +0800\ncommitter GitHub 1547013727 +0800\n\nCreate readme.md"
}
}
3. 生成 Blob
3.1 文檔地址
https://developer.github.com/v3/git/blobs/#create-a-blob
3.2 請求地址
POST https://api.github.com/repos/ssshooter/test/git/blobs
3.3 請求參數
{
"content": "Content of the blob",
"encoding": "utf-8"
}
3.4 返回數據
{
"sha": "929246f65aab4d636cb229c790f966afc332c124",
"url": "https://api.github.com/repos/ssshooter/test/git/blobs/929246f65aab4d636cb229c790f966afc332c124"
}
4. 生成 tree
4.1 文檔地址
https://developer.github.com/v3/git/trees/#create-a-tree
4.2 請求地址
POST https://api.github.com/repos/ssshooter/test/git/trees
4.3 請求參數
注意:tree.path 可以寫深層目錄,如 deep/deep/newFile.md(前面不用寫斜槓)
{
"base_tree": "d7a57d28ace0db12773c7d70675f94a48da6421f", // commit tree 的 sha
"tree": [
{
"path": "apiCommitFile.md", // 文件路徑
"mode": "100644", // 類型,詳情看文檔
"type": "blob",
"sha": "929246f65aab4d636cb229c790f966afc332c124" // 剛纔生成的 blob 的 sha
}
]
}
4.4 返回數據
{
"sha": "2b3a65095ceb7cf4425f52d59ca5974d826cff80",
"url": "https://api.github.com/repos/ssshooter/test/git/trees/2b3a65095ceb7cf4425f52d59ca5974d826cff80",
"tree": [
{
"path": "readme.md",
"mode": "100644",
"type": "blob",
"sha": "b1b716105590454bfc4c0247f193a04088f39c7f",
"size": 5,
"url": "https://api.github.com/repos/ssshooter/test/git/blobs/b1b716105590454bfc4c0247f193a04088f39c7f"
},
{
"path": "tree",
"mode": "040000",
"type": "tree",
"sha": "91d8d59147e395effaeacd01c9d8553b37cf77c5",
"url": "https://api.github.com/repos/ssshooter/test/git/trees/91d8d59147e395effaeacd01c9d8553b37cf77c5"
}
],
"truncated": false
}
5. 生成 Commit
5.1 文檔地址
https://developer.github.com/v3/git/commits/#create-a-commit
5.2 請求地址
POST https://api.github.com/repos/ssshooter/test/git/commits
5.3 請求參數
{
"message": "a Commit with GitHub api",
"parents": [
"cda66de943082033f4b761639df77728d7bca4f0" // 上次 commit 的sha
],
"tree": "2b3a65095ceb7cf4425f52d59ca5974d826cff80"
}
5.4 返回數據
{
"sha": "45c58a9358b67fc81e4034cb36c5196d791686ef",
"node_id": "MDY6Q29tbWl0MTY0Nzk4NDczOjQ1YzU4YTkzNThiNjdmYzgxZTQwMzRjYjM2YzUxOTZkNzkxNjg2ZWY=",
"url": "https://api.github.com/repos/ssshooter/test/git/commits/45c58a9358b67fc81e4034cb36c5196d791686ef",
"html_url": "https://github.com/ssshooter/test/commit/45c58a9358b67fc81e4034cb36c5196d791686ef",
"author": {
"name": "ssshooter",
"email": "[email protected]",
"date": "2019-01-09T10:24:10Z"
},
"committer": {
"name": "ssshooter",
"email": "[email protected]",
"date": "2019-01-09T10:24:10Z"
},
"tree": {
"sha": "2b3a65095ceb7cf4425f52d59ca5974d826cff80",
"url": "https://api.github.com/repos/ssshooter/test/git/trees/2b3a65095ceb7cf4425f52d59ca5974d826cff80"
},
"message": "a Commit with GitHub api",
"parents": [
{
"sha": "cda66de943082033f4b761639df77728d7bca4f0",
"url": "https://api.github.com/repos/ssshooter/test/git/commits/cda66de943082033f4b761639df77728d7bca4f0",
"html_url": "https://github.com/ssshooter/test/commit/cda66de943082033f4b761639df77728d7bca4f0"
}
],
"verification": {
"verified": false,
"reason": "unsigned",
"signature": null,
"payload": null
}
}
6. 更新 Ref
6.1 文檔地址
https://developer.github.com/v3/git/refs/#update-a-reference
6.2 請求地址
https://api.github.com/repos/ssshooter/test/git/refs/heads/master
6.3 請求參數
{
"sha":"45c58a9358b67fc81e4034cb36c5196d791686ef",
"force":true
}
6.4 返回數據
{
"ref": "refs/heads/master",
"node_id": "MDM6UmVmMTY0Nzk4NDczOm1hc3Rlcg==",
"url": "https://api.github.com/repos/ssshooter/test/git/refs/heads/master",
"object": {
"sha": "45c58a9358b67fc81e4034cb36c5196d791686ef",
"type": "commit",
"url": "https://api.github.com/repos/ssshooter/test/git/commits/45c58a9358b67fc81e4034cb36c5196d791686ef"
}
}
7. node.js 實踐代碼
var updateGitHubRes = function(blob, path) {
var commitSha
var commitTreeSha
return getRef()
.then(({ data }) => {
commitSha = data.object.sha
return getCommit(commitSha)
})
.then(({ data }) => {
commitTreeSha = data.tree.sha
return createBlob(blob)
})
.then(({ data }) => {
var blobSha = data.sha
return createTree(commitTreeSha, path, blobSha)
})
.then(({ data }) => {
var treeSha = data.sha
return createCommit(commitSha, treeSha)
})
.then(({ data }) => {
var newCommitSha = data.sha
return updataRef(newCommitSha)
})
.catch(err => {
console.log(err)
})
}
var getRef = function() {
return axios.get(`/${owner}/${repo}/git/refs/heads/master`)
}
var getCommit = function(commitSha) {
return axios.get(`/${owner}/${repo}/git/commits/${commitSha}`)
}
var createBlob = function(content) {
return axios.post(`/${owner}/${repo}/git/blobs`, {
content,
encoding: 'utf-8'
})
}
var createTree = function(base_tree, path, sha) {
return axios.post(`/${owner}/${repo}/git/trees`, {
base_tree, // commit tree 的 sha
tree: [
{
path, // 文件路徑
mode: '100644', // 類型,詳情看文檔
type: 'blob',
sha // 剛纔生成的 blob 的 sha
}
]
})
}
var createCommit = function(parentCommitSha, tree, message = 'update post') {
return axios.post(`/${owner}/${repo}/git/commits`, {
message,
parents: [parentCommitSha],// 上次 commit 的sha
tree
})
}
var updataRef = function(newCommitSha) {
return axios.post(`/${owner}/${repo}/git/refs/heads/master`, {
sha: newCommitSha,
force: true
})
}
參考文獻
https://int128.hatenablog.com/entry/2017/09/05/161641
https://juejin.im/post/5c33f49de51d45523070f7bb
https://git-scm.com/book/zh/v2/Git-內部原理-Git-引用