---
title: "GitHub"
description: "連結 GitHub 以從任務建立分支並自動追蹤 Pull Request。"
---

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

# GitHub

將您的 GitHub 儲存庫連結至 Projectyl，即可直接從任務建立分支，並自動追蹤 Pull Request 的完整生命週期。

## 設定

> **Note**
>
> 只有工作空間的**擁有者**和**管理員**可以連結 GitHub。

1. 前往**設定 → 串接**
2. 點擊**連結 GitHub**
3. 您將被導向至 GitHub 以授權 Projectyl GitHub App
4. 選擇您要連結的組織或個人帳號
5. 選擇要授權存取的儲存庫（之後可以更改）
6. 確認安裝

連結完成後，串接會出現在您的設定中，顯示**啟用中**狀態。

### 連結多個帳號

您可以將多個 GitHub 組織或個人帳號連結到同一個工作空間。如果您有多個 GitHub App 安裝，授權後會出現選擇器對話框，讓您選擇要連結的帳號。

若要在初始設定後新增其他帳號：

1. 前往**設定 → 串接**
2. 在選擇器中點擊**安裝到其他帳號**，或點擊**新增 GitHub 帳號**
3. 依照 GitHub 授權流程選擇新帳號

### 管理存取權限

若要在安裝後更改 Projectyl 可以存取的儲存庫：

1. 前往**設定 → 串接**
2. 點擊 GitHub 連結旁的**管理**
3. 這會開啟該帳號的 GitHub 安裝設定頁面，您可以在此新增或移除儲存庫

### 已暫停的連結

如果您的 GitHub 連結變為**已暫停**（例如因 GitHub 端的帳務或管理員操作），請在設定 → 串接中點擊**取消暫停**。這會直接帶您前往 GitHub 安裝設定頁面以解決問題。

### 移除

若要完全斷開 GitHub 連結，請點擊連結旁的**移除**。這會移除 Projectyl 與 GitHub 安裝之間的連結，但不會刪除 GitHub 上的任何分支或 Pull Request。

## 設定偏好儲存庫

您可以為每個專案設定預設儲存庫，這樣開發人員每次建立分支時就不需要重新選擇。

1. 開啟您的專案**設定**
2. 在**偏好儲存庫**下，從下拉選單中選擇儲存庫
3. 此儲存庫將在建立分支的對話框中自動預選

## 從任務建立分支

1. 開啟任務的詳細檢視
2. 捲動至**開發**區段
3. 點擊**建立分支**
4. 在對話框中：
- **儲存庫** — 選擇儲存庫（若已設定偏好儲存庫則會自動填入）
- **來源分支** — 要從哪個分支建立（預設為儲存庫的開發分支或預設分支）
- **分支名稱** — 依據任務代號和標題自動產生（例如 `feat/PROJ-42-user-login`）。您可以在建立前編輯。
5. 點擊**建立**

分支會立即在 GitHub 上建立，開發區段中會出現**已建立分支**的指示。

## 自動追蹤 Pull Request

當 GitHub 上開啟 Pull Request 時，Projectyl 會自動偵測任務引用並將 PR 連結至對應的任務。無需手動操作。

### 任務代號的比對方式

Projectyl 會在三個位置尋找任務代號（例如 `PROJ-42`）：

- **分支名稱** — `fix/PROJ-42-login-bug`
- **PR 標題** — `feat: add login validation (PROJ-42)`
- **PR 內文** — `Fixes PROJ-42 and PROJ-43`

單一 PR 可以引用多個任務，每個任務都會自動連結。

> **Note**
>
> 任務代號區分大小寫，格式為 `前綴-編號`，需與您的專案識別碼相符（例如 `PROJ-42`、`API-15`）。

## 開發生命週期

每個已連結的分支/PR 會在任務的開發區段中顯示三階段進度指示：

| 階段 | 觸發條件 | 顯示內容 |
|------|---------|---------|
| **已建立分支** | 從 Projectyl 建立分支 | 分支名稱、儲存庫 |
| **PR 已開啟** | 在 GitHub 上開啟了引用任務的 PR | PR 編號、標題、作者 |
| **已合併** | 在 GitHub 上合併 PR | 合併日期 |

如果 PR 未合併就被關閉，階段會恢復至**已建立分支**。

## 解除連結

若要從任務中移除開發連結，請點擊連結上的解除按鈕。這只會移除 Projectyl 中的連結，不會刪除 GitHub 上的分支或 PR。

## 權限

| 操作 | 所需角色 |
|------|---------|
| 連結 / 斷開 GitHub | 擁有者或管理員 |
| 設定偏好儲存庫 | 擁有者或管理員 |
| 從任務建立分支 | 任何工作空間成員 |
| 查看開發生命週期 | 任何工作空間成員 |

Source: https://docs.projectyl.app/zh-tw/guides/github/index.mdx