# 認証ガイド

## トークンの設定方法

gfo はトークンを以下の優先順位で解決します:

1. `credentials.toml`（`gfo auth login` で保存）
2. サービス別環境変数
3. `GFO_TOKEN` 環境変数（全サービス共通のフォールバック）

### 方法 1: gfo auth login（推奨）

リポジトリ内で以下を実行するとトークンが `credentials.toml` に保存されます:

```bash
gfo auth login
```

ホストを明示的に指定する場合:

```bash
gfo auth login --host github.com
```

コマンドラインでトークンを直接渡す場合（スクリプト・CI 向け）:

```bash
gfo auth login --host github.com --token ghp_xxxx
```

設定済みのトークン一覧を確認:

```bash
gfo auth status
```

### 方法 2: credentials.toml を手動編集

**ファイルパス:**
- Windows: `%APPDATA%\gfo\credentials.toml`
- Linux / macOS: `~/.config/gfo/credentials.toml`

```toml
[tokens]
"github.com" = "ghp_xxxxxxxxxxxxxxxxxxxx"
"gitlab.com" = "glpat-xxxxxxxxxxxxxxxxxxxx"
"bitbucket.org" = "user@example.com:app-password"
"dev.azure.com" = "azure-pat-string"
"gitea.example.com" = "xxxxxxxxxxxxxxxxxxxxxxxx"
"myspace.backlog.com" = "backlog-api-key"
```

### 方法 3: 環境変数

| サービス | 環境変数 |
|---|---|
| GitHub | `GITHUB_TOKEN` |
| GitLab | `GITLAB_TOKEN` |
| Bitbucket Cloud | `BITBUCKET_TOKEN` |
| Azure DevOps | `AZURE_DEVOPS_PAT` |
| Gitea / Forgejo / Gogs | `GITEA_TOKEN` |
| GitBucket | `GITBUCKET_TOKEN` |
| Backlog | `BACKLOG_API_KEY` |
| 全サービス共通 | `GFO_TOKEN` |

---

## サービス別 トークン作成手順

### GitHub

**Fine-grained Personal Access Token（推奨）**

1. GitHub にログインし、右上のアイコン → **Settings** を開く
2. 左メニュー下部 **Developer settings** → **Personal access tokens** → **Fine-grained tokens** に進む
3. **Generate new token** をクリック
4. Token name、Expiration（有効期限）を設定
5. **Repository access** で対象リポジトリを選択
6. **Repository permissions** で必要な権限を付与:
   - Contents: `Read and write`（ファイル操作に必要）
   - Issues: `Read and write`
   - Pull requests: `Read and write`
   - Metadata: `Read-only`（自動付与）
   - Commit statuses: `Read and write`（`gfo status` を使う場合）
   - Webhooks: `Read and write`（`gfo webhook` を使う場合）
7. **Generate token** をクリックしてトークンをコピー

```bash
gfo auth login --host github.com
# Token: ghp_xxxxxxxxxxxxxxxxxxxx
```

**Classic Personal Access Token**

- スコープ: `repo`（フルアクセス）
- Settings → Developer settings → Personal access tokens → Tokens (classic) から発行

---

### GitLab

1. GitLab にログインし、右上のアイコン → **Edit profile** を開く
2. 左メニュー **Access Tokens** → **Add new token** をクリック
3. Token name、Expiration date を設定
4. スコープを選択:
   - 読み取りのみ: `read_api`
   - 書き込みを含む操作（PR 作成・Issue 作成など）: `api`
5. **Create personal access token** をクリック

```bash
gfo auth login --host gitlab.com
# Token: glpat-xxxxxxxxxxxxxxxxxxxx
```

セルフホスト GitLab の場合:

```bash
gfo auth login --host gitlab.example.com
```

---

### Bitbucket Cloud

> **注意**: App Password は 2026 年 6 月に廃止予定です。Scoped API Token を使用してください。

**Scoped API Token の発行手順**

1. Bitbucket にログインし、右上のアイコン → **Settings** を開く
2. 左メニュー **Personal Bitbucket settings** の **Scoped API tokens** → **Create token** をクリック
3. Token label を設定
4. 必要な権限を付与:
   - **Repositories**: `Read` / `Write`
   - **Pull requests**: `Read` / `Write`（注: `write` は `read` を含まないので両方必要）
   - **Issues**: `Read` / `Write`（Issue Tracker 使用時）
5. **Create** をクリックしてトークンをコピー

**トークン形式**: `メールアドレス:トークン` のコロン区切りで設定します。

```bash
export BITBUCKET_TOKEN="user@example.com:ATATT-xxxxxxxxxxxxxxxxxxxx"
```

または:

```bash
gfo auth login --host bitbucket.org
# Token: user@example.com:ATATT-xxxxxxxxxxxxxxxxxxxx
```

---

### Azure DevOps

1. Azure DevOps にログインし、右上のユーザーアイコン → **Personal access tokens** を開く
2. **New Token** をクリック
3. Name、Organization（対象の組織）、Expiration を設定
4. **Scopes** で必要な権限を付与:
   - **Code**: `Read & write`
   - **Work Items**: `Read & write`（Issue/タスク操作に必要）
5. **Create** をクリックしてトークンをコピー

```bash
export AZURE_DEVOPS_PAT="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

または:

```bash
gfo auth login --host dev.azure.com
```

> `gfo init` 時に **Organization** と **Project** の入力が必要です。

---

### Backlog

1. Backlog にログインし、右上のアイコン → **個人設定** を開く
2. 左メニュー **API** に進む
3. メモ（任意）を入力し **登録** をクリック
4. 発行された API キーをコピー

> API キーはスコープ制御がなく、アカウントの全権限が付与されます。

```bash
export BACKLOG_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

または:

```bash
gfo auth login --host yourspace.backlog.com
```

> `gfo init` 時に **プロジェクトキー**（例: `MYPROJECT`）の入力が必要です。

---

### Gitea

1. Gitea にログインし、右上のアイコン → **Settings** を開く
2. 左メニュー **Applications** → **Manage Access Tokens** に進む
3. **Token Name** を入力し、必要なスコープを選択
4. **Generate Token** をクリック

```bash
gfo auth login --host gitea.example.com
```

---

### Forgejo

Gitea と同じ手順です。

1. Forgejo にログインし、右上のアイコン → **Settings** を開く
2. **Applications** → **Manage Access Tokens** に進む
3. Token Name を入力し、スコープを選択して **Generate Token** をクリック

```bash
gfo auth login --host forgejo.example.com
```

> [Codeberg](https://codeberg.org) は Forgejo ベースのため、同じ手順でトークンを発行できます。

---

### Gogs

1. Gogs にログインし、右上のアイコン → **Your Settings** を開く
2. 左メニュー **Applications** → **Generate New Token** をクリック
3. Token Name を入力し **Generate Token** をクリック

```bash
gfo auth login --host gogs.example.com
```

> Gogs は PR・ラベル・マイルストーン・リリース API を未サポートです。

---

### GitBucket

1. GitBucket にログインし、右上のアイコン → **Account Settings** を開く
2. **Personal access token** → **Generate new token** をクリック
3. Note を入力し **Generate** をクリック

> トークンは Web UI からのみ発行可能です（API 経由での発行は非対応）。

```bash
gfo auth login --host gitbucket.example.com:8080
```

ポート番号込みのホスト名を指定してください。
