> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK: GitHub からの deploy

> client.apps.deploys で GitHub から deploy します: webhook の設定、Square Cloud GitHub App を通じたリポジトリの連携、deploy 履歴の取得。

`client.apps.deploys` はアプリを GitHub に接続し、push で deploy されるようにします。方法は 2 つあります。リポジトリに追加する **webhook** と、**Square Cloud GitHub App** です。

サンプルでは、[クライアントの作成](/ja/sdks/py/client#クライアントの作成)で作成した `client` を使います。`app_id` はあなたのアプリの ID で、[`client.account.me()`](/ja/sdks/py/client#アカウント) で一覧できます。

## Webhook

`deploys.set_webhook(app_id, access_token)` は、GitHub のアクセストークン (`ghp_...` または `github_pat_...`) を使って GitHub の webhook による deploy を設定し、リポジトリに追加する webhook の URL を返します。

```python theme={"system"}
url = client.apps.deploys.set_webhook(app_id, os.environ["GITHUB_TOKEN"])

print(url)  # add it as a webhook in the repository settings
```

webhook を削除するには、トークンとして `"@"` を渡します。その場合、メソッドは `''` を返します。

```python theme={"system"}
client.apps.deploys.set_webhook(app_id, "@")
```

無効なトークンは 400 `INVALID_ACCESS_TOKEN` になります。

## GitHub App

`deploys.link_github_app(app_id, repository, branch)` は、Square Cloud GitHub App を通じてインストールされたリポジトリを連携します。`apps:deploy` スコープが必要です。

```python theme={"system"}
repo = client.apps.deploys.link_github_app(app_id, "octocat/hello-world", "main")

print(repo["id"], repo["full_name"], repo["branch"])
```

`deploys.unlink_github_app(app_id)` は連携を解除します。別のリポジトリやブランチを連携するには、先に連携を解除してください。

```python theme={"system"}
client.apps.deploys.unlink_github_app(app_id)
```

連携と連携解除は、**60 秒あたり 3 回**の制限を共有しています。

| ステータス | コード | 発生条件 |
| - | - | - |
| 400 | `GIT_ALREADY_CONFIGURED` | アプリにはすでに連携済みのリポジトリがある: 先に連携を解除してください |
| 400 | `GIT_NOT_CONFIGURED` | 何も連携されていない状態での `unlink_github_app` |
| 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | ブランチが存在しない、またはその名前が 256 文字を超えている |
| 403 | `GITHUB_NOT_CONNECTED` | アカウントに GitHub App のインストールがない |
| 403 | `REPOSITORY_NOT_AVAILABLE` | GitHub App があなたの GitHub アカウント経由でそのリポジトリにインストールされていない |
| 403 | `REPOSITORY_PERMISSION_REQUIRED` | あなたの GitHub アカウントにリポジトリへの書き込み権限がない |
| 404 | `REPOSITORY_NOT_FOUND` | リポジトリが存在しない、または見えない |
| 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 別のアプリ (アカウントを問わず) がすでにこのリポジトリとブランチを連携している。そのアプリがあなたのものである場合に限り、その ID が `message` に含まれます |
| 502 | `FAILED_TO_FETCH` | GitHub がブランチを確認しなかった: 安全にリトライできます |

## 現在の設定

`deploys.current(app_id)` は設定内容を返します。GitHub App の連携は `app`、webhook の URL は `webhook` に入ります。何も設定されていない場合は `{}` を返します。

```python theme={"system"}
current = client.apps.deploys.current(app_id)

if "app" in current:
    print(current["app"]["name"], current["app"]["branch"])  # e.g. "octocat/hello-world" "main"
if "webhook" in current:
    print(current["webhook"])
```

## Deploy 履歴

`deploys.list(app_id)` は **deploy ごとに 1 つのタイムライン**を返します。各タイムラインはイベントのリストで、古いイベントが先頭です。記録されるのは Git による deploy (webhook と GitHub App の push) のみです。

```python theme={"system"}
for timeline in client.apps.deploys.list(app_id):
    last = timeline[-1] if timeline else None
    if last is None:
        continue
    print(last["id"], last["state"], last["date"])

    if last["state"] == "error":
        print(last.get("code"), last.get("message"))
```

| フィールド | 説明 |
| - | - |
| `id` | commit の SHA |
| `state` | `pending`、`clone`、`commit`、`restarting`、`success`、`error` のいずれか |
| `date` | イベントが発生した日時 |
| `source` | 常に `"git"` |
| `branch` | `clone` イベントに含まれます |
| `files` | `commit` イベントに含まれます: `{ added, removed, modified }` |
| `code` / `message` | `error` イベントに含まれます: deploy が失敗した理由 (例: `CLONE_FAILED`) |

## 次のステップ

<CardGroup cols={3}>
  <Card title="ネットワーク" icon="globe" href="/ja/sdks/py/network">
    アナリティクス、DNS、カスタムドメイン、キャッシュ。
  </Card>

  <Card title="Deploy API リファレンス" icon="code" href="/ja/api-reference/endpoint/apps/deploy/list">
    これらのメソッドが呼び出す REST endpoint。
  </Card>

  <Card title="CLI で GitHub から deploy" icon="terminal" href="/ja/cli-reference/github-deploys">
    同じ操作をターミナルから行います。
  </Card>
</CardGroup>