# 静的な API キーによるボット認証機能をリリース

Shisho Cloud ボットに対応する、静的な API キーが払い出せるようになりました。

これまでボット認証は、静的な認証情報を一切持たず、GitHub Actions や GitLab CI でのキーレス認証（OpenID Connect ベース）による認証のみをサポートしてきました。
本リリースにより、静的な API キーが払い出せるようになることで、さらに広いプラットフォームからの Shisho Cloud へのアクセスが可能となります。

Jenkins や GitHub Enterprise Server 等、現在 Shisho Cloud が「信頼関係」機能でサポートしているプラットフォーム以外をご利用の方は、ぜひ本機能をご利用ください。

![eyecatch](/docs/ja/_md-assets/0beac7f8a4-eyecatch.png)

## 概要

API キーによるボット認証機能は、Shisho Cloud から、`shishoctl` CLI で利用できる静的な認証情報（APIキー）を払い出せる機能です。
これにより、APIキーさえ保管できる環境であれば、どこからでもボットとして認証して `shishoctl` CLI を利用いただけます。

### 認証方式の比較

Shisho Cloud では、環境に応じて以下の認証方式を推奨しています。

| 環境                | 推奨される認証方式 |
| ------------------- | ------------------ |
| GitHub Actions      | 信頼条件（OIDC）   |
| GitLab CI           | 信頼条件（OIDC）   |
| その他の CI/CD 環境 | API キー           |

## 利用開始方法

### ステップ 1: ボットを作成して API キーを発行する

APIキーはボットに紐づく概念です。
そのため、ボットを未だ作成していない場合は、まずボットを作成しましょう。
具体的な手順は以下です。

1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする
2. 「ボットの追加」ボタンから、新しいボットを作成する

作成できたら、以下の手順でAPIキーが発行できます。

1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする。
2. 作成したボットの名前をクリックし、個別ページを開く。
3. APIキータブで、「APIキーの作成」を押下し、ボットの API キーを新規作成する。

:::warning 重要
API キーは作成時に一度しか表示されません。あとからの再確認は不可能なので、作成時に控え、安全な場所に保存してください。
:::

### ステップ 2: API キーでサインインする

以下のコマンドで API キーを使って認証してください:

```shell
shishoctl auth signin:bot \
  --bot <ボット ID> \
  --api-key-json "$(cat api-key.json)"
```

`api-key.json` ファイルの内容は以下の形式です:

```json
{
  "api_key": "shisho_apikey_..."
}
```

または、API キーを直接指定することもできます:

```shell
shishoctl auth signin:bot \
  --bot <ボット ID> \
  --api-key-json '{"api_key":"shisho_apikey_..."}'
```

### ステップ 3: shishoctl を使い始める

認証が完了したら、通常通り `shishoctl` コマンドを使用してください:

```shell
shishoctl workflow list -o <organization-id>
```

## セキュリティのベストプラクティス

一般的な SaaS の API キーと同様に、ボットの API キーが漏れると、Shisho Cloud 上のでデータが侵害される可能性があります。
安全に扱うため、以下にご留意ください。

- API キーを外部公開しない。特に、GitHub 等の公開リポジトリにコミットしない。
- 非公開領域に API キーを保管する場合も、極力安全な場所を利用する。例えば、GitHub リポジトリ内に直接含めるよりは、GitHub Actions のシークレット管理機能を利用する。
- 不要になった API キーは速やかに削除する。

## 関連リソース

ボット認証と `shishoctl` の使い方の詳細については、以下をご参照ください:

- [shishoctl CLI から操作する](https://shisho.dev/docs/ja/g/getting-started/accessing-via-shishoctl-cli)
- [検査ルールを Git リポジトリで管理する](https://shisho.dev/docs/ja/g/category/deploy-policies-with-git-repositories)