メインコンテンツまでスキップ

ワークフローを Git で管理する

本チュートリアルでは、ワークフローの git を用いた管理を始める方法を紹介します。

概要​

本チュートリアルでは、以下の 4 つのステップを通してワークフローをローカル端末にエクスポートした後、git を用いた管理を始めることを目指します:

  1. 作業ディレクトリを作成する
  2. shishoctl コマンドを用いて、ワークフローをエクスポートする
  3. git コマンドを用いてバージョン管理を始める
  4. Shisho Cloud 公式の Rego ライブラリを git リポジトリ中に submodule として追加する
note

以降では、shishoctl コマンドの導入が完了していることを前提としています。 同コマンドの導入方法に関しては このページ をご参照ください。

作業ディレクトリを作成する​

まずは以下のコマンドで、以降でワークフロー等を格納するためのディレクトリを用意してください:

mkdir shisho-cloud-workflows

ワークフローをエクスポートする​

作業ディレクトリが用意できたら、以下のコマンドを用いて Shisho Cloud 組織中に登録されたワークフローを ./shisho-cloud-workflows 内にエクスポートしましょう:

cd shisho-cloud-workflows

# in your ./shisho-cloud-workflows
# (need to set the ID of your Shisho Cloud organization to $YOUR_ORG_ID)
shishoctl workflow export \
    -o $YOUR_ORG_ID \
    --path ./ \
    --structured

コマンドが適切に動作すると、./shisho-cloud-workflows 以下に各種ファイルが格納されます。 格納される各ファイルの役割は以下の通りです:

  • <workflow ID>/manifest.yaml: ワークフローのマニフェストル
  • <workflow ID>/<job ID>/{decide,notify}/input.graphql: ワークフローの各ジョブ内で、検査/監査するデータを取得するための GraphQL クエリ
  • <workflow ID>/<job ID>/{decide,notify}/policy.rego: ワークフローの各ジョブ内で、取得したデータを実際に検査/監査するポリシー
  • <workflow ID>/<job ID>/{decide,notify}/policy_test.rego: OPA を用いたポリシーテスト の定義

以下に生成されるディレクトリ構造の例を示します:

./shisho-cloud-workflows
├── prebundle-workflow-github-configurations
│   ├── manifest.yaml
│   ├── notify
│   │   ├── decide
│   │   │   ├── input.graphql
│   │   │   ├── policy.rego
│   │   │   └── policy_test.rego
│   │   └── notify
│   │       ├── input.graphql
│   │       ├── policy.rego
│   │       └── policy_test.rego
│   ├── review-2fa-setup
│   │   └── decide
│   │       ├── input.graphql
│   │       ├── policy.rego
│   │       └── policy_test.rego
│   ├── review-branch-protection-rule
│   │   └── decide
│   │       ├── input.graphql
│   │       ├── policy.rego
│   │       └── policy_test.rego
│   ├── review-org-default-permissions
│   │   └── decide
│   │       ├── input.graphql
│   │       ├── policy.rego
│   │       └── policy_test.rego
│   └── review-org-owners-number
│       └── decide
│           ├── input.graphql
│           ├── policy.rego
│           └── policy_test.rego
...

git によるバージョン管理を始める​

以下のコマンドを実行し、./shisho-cloud-workflows 内のファイルのバージョン管理を始めましょう:

# in your ./shisho-cloud-workflows
git init

echo "# Workflows for Shisho Cloud" > README.md
git add .

git commit -m ":seedling: init"

ライブラリを管理する​

生成された policy.rego ファイル郡を見ると、そのうちのいくつかが data.shisho を import していることが分かります:

package policy.github.config.review_org_default_permissions

import data.shisho

# default permission on organizations' repository
default_repository_permission_allowlist := [
  "none",
  "read",
]

...

これは data.shisho 以下に格納された、Shisho Cloud 公式の Rego ライブラリ を利用するための記述です。 今後ワークフローの開発を進める際、とりわけローカルでテストを実行する際には、同 Rego ライブラリを利用する機会がしばしば登場します。

そこで、以下のコマンドを実行し、./shisho-cloud-workflows で管理された git リポジトリ以下に同ライブラリを git submodule として追加しておきましょう:

# in your ./shisho-cloud-workflows

git submodule add git@github.com:flatt-security/shisho-cloud-rego-libraries ./lib
git commit -m "chore: include official Rego packages"

ワークフローのカスタマイズを始める​

上記のステップを通して、ワークフローを自由に編集・作成し、Shisho Cloud で実行できるような準備が整いました。 他のチュートリアルを確認し、ぜひワークフローをカスタマイズしてみてください。

参考: OPA コマンドでテストを実行する​

上記のステップすべてが完了している場合、Open Policy Agent (OPA) を用いて、ローカルでポリシーのテストを実行することが出来ます。 ./shisho-cloud-workflows で以下のコマンドを実行し、実際にテストが動作するかを確かめてみましょう:

# in your ./shisho-cloud-workflows
opa test ./
info

Open Policy Agent (OPA) のインストール方法については、OPA の公式ドキュメント を参照してください。

補足: ワークフローのデプロイを自動化する​

info

いくつかのチュートリアルで示されているように、ワークフローのデプロイは shishoctl workflow apply コマンドで実行できるようになっています。 現在、このコマンドを GitHub Actions 等から実行できるようにするための機能の開発が進められており、同機能のリリース後は本チュートリアルで作成した git リポジトリ（や GitHub 等）からワークフローをよりシームレスにデプロイできるようになる予定です。

この機能の進行状況は以下の GitHub Issue でトラックされています: