ヘキサ日記 Blog

 

2017年7月4日

GitLab APIの紹介

こんにちは
ビッシーです

 

開発で GitLab を使用していますが、
GitLab には GitLab API がありHTTPリクエストを通して
GitLab のデータアクセスや操作を行うことが出来ます。

 

↓公式のドキュメントです↓
https://docs.gitlab.com/ee/api/README.html

 

GitLab API があればスクリプト等で
GitLab の操作をバッチ化することが出来ます。

 

当然 GitLab CI Runners で実行するスクリプトでも利用できるので、
GitLab 上のリソースを集計したり、処理を 自動化 するために役立てることが出来ます

 

今回はその一例として、
GitLab CI Runners のビルドスクリプト経由で、
プロジェクトの Snippets に投稿するまでの手順をご紹介したいと思います

 

 

1. プロジェクト構成

 

まずは .gitlab-ci.yml を設定したプロジェクトを用意します。
今回はサンプル用に、下記のような最低限の構成で作業していきます。

 

├ .gitlab-ci.yml
└ ci
 └ test.py

 

.gitlab-ci.yml の中身はこちら:

 

stages:
    - test

test_job:
    type: test
    script:
        - python ci/test.py

※ test.py の中身は後述します

 

これで GitLab CI の Pipelines が実行できるようになりましたが、
GitLab API をスクリプトから利用するために下準備が必要なため、
次はその準備を進めます。

 

2. Personal Access Tokenの発行と登録

 

GitLab API でProjectなどアクセス権限で保護されたリソースにアクセスする場合、
リクエストする際に 認証 が必要になります。

 

 ↓GitLab APIの認証について↓

https://gitlab.com/help/api/README.md#authentication-1

 

 

通常は、 Private TokenPersonal Access Token を利用することになります。

 

Private Token各ユーザーアカウントに1個 なのに対して、
Personal Access Token は用途ごとに複数発行することが出来るため、
基本的には Personal Access Token を利用することを推奨します。

 

Personal Access Token の発行や無効化の管理は、
ユーザープロファイルページの Access Tokens のページから行うことが出来ます。

(作成したトークンは後から再確認することは出来ないので、一連の作業が完了するまでは忘れないようにしておいてください)

 

 

20170704_001

 

 

発行した Personal Access Token は、
今回CIを実行する Project の VariablesCI_PRIVATE_TOKEN という Key で登録しておきます。
この変数はスクリプトのほうから参照して GitLab API のリクエストを作成するために使います。

 

20170704_002

 

3. HTTPリクエスト作成スクリプト

 

Personal Access Token が作成できたので、 GitLab API が使える状態になりました

 

GitLab API はHTTPリクエストが出来れば何でもよいのですが、
今回は分かりやすいPythonのスクリプトを利用して行っていきます。

 

サンプルとして、CIを実行したProjectのSnippetに新しいファイルを投稿する
GitLab API のリクエストを作成していきます。

 

下記がサンプルコードです:

 

import urllib.request
import json
import os

ci_project_id = os.environ.get("CI_PROJECT_ID")
ci_private_token = os.environ.get("CI_PRIVATE_TOKEN")

# URLは利用しているGitLabサーバーのものに読み替えてください
url = "https://url-to-gitlab/api/v3/projects/" + str(ci_project_id) + "/snippets"

data = json.dumps({
        "private_token" : ci_private_token,
        "title" : "test",  # Snippetタイトル
        "file_name" : "test.md",  # ファイル名
        "visibility_level" : 20,
        "code" : "hello, world"  # 本文
    }).encode('utf-8')

req = urllib.request.Request(url, data=data, headers={'content-type' : 'application/json'})
res = urllib.request.urlopen(req)
print(res.read().decode('utf8'))

 

↓Project SnippetsのAPIリファレンスはこちら↓

https://docs.gitlab.com/ee/api/project_snippets.html

 

手順はこれで完了です

 

 

GitLab CI Runner から GitLab API を利用する際の注意点は 2点 です。

 

その1:

 

先ほど作成した Personal Aceess Token をリポジトリ内に直接記述することは
セキュリティ上NGなので、必ずProjectの build variables 経由で渡すようにしましょう。

 

その他、CIでリポジトリ外のリソースにアクセスするような場合も、
.gitlab-ci.ymlに直接記述せず build variables を経由することを推奨します
(fork等した際にきちんと対応できるようにするため)

 

その2:

 

GitLab API からプロジェクトを操作する際に ProjectID が必要になります。

このIDは GitLab CI Variables から取得することが出来るため、
そちらを利用するようにしましょう。

 

↓GitLab CIで参照できる環境変数はこちらで確認できます ↓ https://gitlab.com/help/ci/variables/README.md

 

 

 

 

GitLab APIからほとんどのGitLab機能にアクセスできるため、
GitLab上で自動化したい作業が出来た場合、CI化させることが出来るようになりました

 

今回の紹介はこれで終了になりますが、
GitLabを使ってみたいけれどローカルに環境構築するのが面倒という方は、
GitLab.com に FreePlan があるので、ぜひ触ってみてください

 

 

それでは


ヘキサブログ ピックアップ



過去の日記はこちら

2017年9月
« 8月    
 123
45678910
11121314151617
18192021222324
252627282930