本頁面由 Cloud Translation API 翻譯而成。

使用生成式 AI 導入 JIRA 使用者故事

1. 總覽

在本研究室中，您將建立解決方案，透過生成式 AI 自動執行 JIRA 使用情境故事。

學習目標

本實驗室分為幾個主要部分：

部署 Cloud Run 應用程式，以便整合 Gemini API
建立及部署 JIRA 專用的 Atlassian Forge 應用程式
用於自動化 GitLab 工作任務的 LangChain ReAct Agent

必要條件

本實驗室假設您已熟悉 Cloud 控制台和 Cloud Shell 環境。

2. 設定和需求

Cloud 專案設定

登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。

「Project name」是這個專案參與者的顯示名稱。這是 Google API 不會使用的字元字串。您隨時可以更新。
專案 ID 在所有 Google Cloud 專案中都是不重複的值，且無法變更 (設定後即無法變更)。Cloud 控制台會自動產生專屬字串，您通常不需要特別在意。在大多數程式碼研究室中，您都需要參照專案 ID (通常會以 PROJECT_ID 表示)。如果您不喜歡系統產生的 ID，可以隨機產生另一個 ID。或者，您也可以自行嘗試，看看是否可用。這項設定在這個步驟後就無法變更，並會在整個專案期間維持不變。
提醒您，有些 API 會使用第三個值「專案編號」。如要進一步瞭解這三個值，請參閱說明文件。

接下來，您需要在 Cloud 控制台中啟用帳單功能，才能使用 Cloud 資源/API。執行這個程式碼研究室不會產生太多費用，甚至可能完全不會產生費用。如要關閉資源，避免在本教學課程結束後繼續產生費用，您可以刪除建立的資源或專案。Google Cloud 新使用者可享有價值 $300 美元的免費試用期。

環境設定

開啟 Gemini 對話。

或者，在搜尋列中輸入「Ask Gemini」。

啟用 Cloud AI Companion API：

按一下「Start chatting」，然後按照其中一個範例問題操作，或自行輸入提示，即可試用這項功能。

建議提示：

以 5 個重點說明 Cloud Run。
您是 Google Cloud Run 產品經理，請向學生解釋 Cloud Run 的 5 個重點。
您是 Google Cloud Run 產品經理，向 Kubernetes 認證開發人員解釋 Cloud Run 的 5 大重點。
您是 Google Cloud Run 產品經理，請向資深開發人員說明在哪些情況下應使用 Cloud Run 而非 GKE，並以 5 個重點說明。

詳情請參閱提示指南，進一步瞭解如何撰寫更優質的提示。

Gemini for Google Cloud 如何使用您的資料

Google 的隱私權承諾

Google 是第一間發表 AI/機器學習隱私權承諾的公司，該文提到我們的信念：除了極致的安全性之外，客戶也應該對儲存在雲端的自家資料保有最大的掌控權。

您提交及收到的資料

您向 Gemini 提出的問題，包括您提交給 Gemini 以便分析或完成的任何輸入資訊或程式碼，都稱為提示。您從 Gemini 收到的答案或程式碼完成作業稱為回覆。Gemini 不會將您的提示或回覆內容做為模型訓練資料。

提示訊息加密

向 Gemini 提交提示時，您的資料會在傳輸過程中經過加密，並做為輸入內容傳送至 Gemini 中的基礎模型。

由 Gemini 產生的節目資料

Gemini 是根據第一方 Google Cloud 程式碼和精選第三方程式碼進行訓練。您必須負責程式碼的安全性、測試和效能，包括 Gemini 提供的任何程式碼完成、產生或分析功能。

進一步瞭解 Google 如何處理提示。

3. 測試提示的選項

您可以透過多種方式測試提示。

Vertex AI Studio

Vertex AI Studio 是 Google Cloud Vertex AI 平台的一部分，專門用於簡化及加速生成式 AI 模型的開發與使用。

Google AI Studio

Google AI Studio 是網頁式工具，可用於設計原型，並透過提示設計和 Gemini API 進行實驗。

Gemini 網頁應用程式 (gemini.google.com)

Google Gemini 網頁應用程式 (gemini.google.com) 是一項網頁式工具，可協助您探索並運用 Google Gemini AI 模型的強大功能。

Android 版和 iOS 版的 Google Gemini 行動應用程式

4. (選用章節) 建立服務帳戶

這些步驟會在實驗室設定期間執行，因此您不需要執行這些步驟。

這些步驟說明如何設定服務帳戶和 IAM 角色。

返回 Google Cloud 控制台，然後按一下搜尋列右側的圖示，啟用 Cloud Shell。

在已開啟的終端機中，執行下列指令建立新的服務帳戶和金鑰。

您將使用這個服務帳戶，從 Cloud Run 應用程式向 Vertex AI Gemini API 發出 API 呼叫。

使用 Qwiklabs 專案詳細資料設定專案詳細資料。

範例：qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

建立服務帳戶並授予角色。

PROJECT_ID=$(gcloud config get-value project)
SERVICE_ACCOUNT_NAME='vertex-client'
DISPLAY_NAME='Vertex Client'
KEY_FILE_NAME='vertex-client-key'

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"


gcloud iam service-accounts keys create $KEY_FILE_NAME.json --iam-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

如果系統提示您授權，請按一下「授權」繼續操作。

啟用必要服務，以便使用 Vertex AI API 和 Gemini 聊天功能。

gcloud services enable \
    generativelanguage.googleapis.com \
    aiplatform.googleapis.com \
    cloudaicompanion.googleapis.com \
    run.googleapis.com \
    cloudresourcemanager.googleapis.com

啟用必要服務，以便使用 Vertex AI API 和 Gemini 聊天功能。

gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    runapps.googleapis.com \
    workstations.googleapis.com \
    servicemanagement.googleapis.com \
    secretmanager.googleapis.com \
    containerscanning.googleapis.com

(END OF OPTIONAL SECTION)

5. 授予 Cloud Workstations 存取權

在 Cloud Console 中開啟 Cloud Workstations。

為已佈建的 Qwiklabs 學生授予 Cloud Workstation 存取權。

複製為此專案建立的 Qwiklabs 使用者名稱/電子郵件地址，然後使用該名稱/電子郵件地址新增主要使用者。選取工作站，然後按一下「PERMISSIONS」。

詳情請見下文。

按一下「ADD PRINCIPAL」按鈕。

貼上 Qwiklabs 學生的電子郵件地址，然後選取「Cloud Workstations User」角色。

依序點選「Start」和「Launch」，開啟工作站，然後使用內建終端機繼續執行下列步驟。

複製 GitHub 存放區

建立資料夾並複製 GitHub 存放區。

mkdir github
cd github
git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git

使用「File / Open Folder」選單項目開啟「github/genai-for-developers」。

6. 啟用 Gemini Code Assist

按一下右下角的「Gemini」圖示，然後點選「Login to Google Cloud」。

按一下終端機中的連結，即可開始授權流程。

按一下「開啟」即可前往連結網頁。

選取 Qwiklabs 學生帳戶，然後在下一個畫面中點選「登入」。

複製驗證碼：

返回終端機並貼上程式碼。

等待驗證程序完成，然後按一下「選取 Google 專案」。

在彈出式視窗中，選取 Qwiklabs 專案。

範例：

開啟檔案「devai-api/app/routes.py」，然後在檔案中任一處按一下滑鼠右鍵，並在內容選單中選取「Gemini > Explain this"」。

查看 Gemini 針對所選檔案提供的說明。

7. LangChain 工具包

LangChain 工具包是一組工具，可簡化並強化使用 LangChain 開發應用程式。這些工具提供的功能因具體工具包而異，但一般來說，這些工具可協助您：

連結至外部資料來源：存取 API、資料庫和其他外部來源的資訊，並將這些資訊納入 LangChain 應用程式。
進階提示技巧：使用預先建立的提示或自訂提示，以最佳化與語言模型的互動。
建立及管理鏈結：輕鬆建立複雜的鏈結，並有效管理鏈結。
評估和監控：分析 LangChain 應用程式和鏈結的效能。

部分熱門 LangChain Toolkit 包括：

代理程式執行工具包：開發代理程式的工具，可透過網頁瀏覽或程式碼執行等動作與現實世界互動。
提示工程工具包：收集了各種資源，協助您設計有效的提示。

GitLab Toolkit

在本研究室中，您將使用 GitLab Toolkit 自動建立 GitLab 合併要求。

Gitlab 工具包包含可讓 LLM 代理程式與 Gitlab 存放區互動的工具。這項工具是 python-gitlab 程式庫的包裝函式。

GitLab 工具包可執行下列工作：

建立檔案：在存放區中建立新檔案。
讀取檔案：從存放區讀取檔案。
更新檔案：更新存放區中的檔案。
Create Pull Request：從 Bot 的工作分支版本建立提取要求，並將其提交至基礎分支版本。
Get Issue：從存放區擷取問題。
Get Issue：擷取特定問題的詳細資料。
針對問題發表意見：針對特定問題發布意見。
刪除檔案：從存放區刪除檔案。

8. GitLab 存放區和工具包設定

開啟 GitLab，建立新的公開專案，然後在「Settings / Access Tokens」下方設定專案存取權權杖。

請使用下列詳細資料：

權杖名稱：devai-api-qwiklabs
角色：Maintainer
選取範圍：api

複製存取權杖值並貼到筆電上的暫存檔案中，這會在後續步驟中使用。

9. 準備在 Cloud Run 上部署應用程式

返回 Cloud Workstations 執行個體，使用現有的終端機或開啟新的終端機。

透過網頁式授權流程取得使用者帳戶的存取憑證。

按一下連結，然後按照步驟產生驗證碼。

gcloud auth login

使用 Qwiklabs 專案詳細資料設定專案詳細資料。

範例：qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR-QWIKLABS-PROJECT-ID

設定其他環境變數：

export PROJECT_ID=$(gcloud config get-value project)
export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api

設定 GitLab 整合所需的環境變數。

export GITLAB_PERSONAL_ACCESS_TOKEN=gitlab-token

為避免在終端機中洩漏機密資訊，最佳做法是使用 read -s，這是一種安全的方式，可設定環境變數，而不會在主控台的指令記錄中顯示值。執行後，您必須貼上值並按下 Enter 鍵。

您必須更新 GitLab 使用者 ID 和存放區名稱，才能執行這項指令。

範例：export GITLAB_REPOSITORY="gitrey/qwiklabs-test"

export GITLAB_REPOSITORY="USERID/REPOSITORY"

設定其他環境變數：

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

10. LangSmith LLM 追蹤設定

建立 LangSmith 帳戶，並在「Settings」(設定) 部分產生 Service API 金鑰。https://docs.smith.langchain.com/

設定 LangSmith 整合所需的環境變數。

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LANGCHAIN_API_KEY=langchain-service-api-key

11. JIRA 設定

這些值不會用於本實驗室，因此您無須在執行指令前將其更新為特定 JIRA 專案值。

設定 Cloud Run 服務部署作業所需的環境變數。

export JIRA_API_TOKEN=jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

12. 將 Devai-API 部署至 Cloud Run

確認你位於正確的資料夾。

cd ~/github/genai-for-developers/devai-api

在本實驗室中，我們會遵循最佳做法，並使用 Secret Manager 在 Cloud Run 中儲存及參照存取權杖和 LangChain API 金鑰值。

將 JIRA 存取權杖儲存在 Secret Manager 中。

echo -n $JIRA_API_TOKEN | \
 gcloud secrets create JIRA_API_TOKEN \
 --data-file=-

將 GitLab 存取權杖儲存在 Secret Manager 中。

echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
 gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
 --data-file=-

將 LangChain API 金鑰儲存在 Secret Manager 中。

echo -n $LANGCHAIN_API_KEY | \
 gcloud secrets create LANGCHAIN_API_KEY \
 --data-file=-

將應用程式部署至 Cloud Run。

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

回答 Y 以建立 Artifact Registry Docker 存放區。

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in 
region [us-central1] will be created.

Do you want to continue (Y/n)?  y

請查看下方的 gcloud run deploy SERVICE_NAME --source=. 流程。瞭解詳情。

在幕後，這個指令會使用 Google Cloud 的 buildpacks 和 Cloud Build，自動從原始碼建構容器映像檔，不必在電腦上安裝 Docker 或設定 Buildpacks 或 Cloud Build。也就是說，上述單一指令可執行原本需要 gcloud builds submit 和 gcloud run deploy 指令才能執行的動作。

如果您已提供 Dockerfile(我們在這個存放區中已提供)，Cloud Build 就會使用該檔案建構容器映像檔，而不會依賴 Buildpack 自動偵測及建構容器映像檔。如要進一步瞭解 Buildpack，請參閱說明文件。

在控制台中查看 Cloud Build 記錄。

在 Artifact Registry 中查看已建立的 Docker 映像檔。

開啟 cloud-run-source-deploy/devai-api，查看系統自動偵測到的安全漏洞。檢查是否有修正程式可用，並根據說明瞭解如何修正。

在 Cloud Console 中查看 Cloud Run 執行個體詳細資料。

執行 curl 指令測試端點。

curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"prompt": "Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything."}' \
   $(gcloud run services list --filter="(devai-api)" --format="value(URL)")/generate

(選用章節) 設定 Cloud Workstation

Cloud Workstations 提供 Google Cloud 上的代管開發環境，內建安全防護機制，且預先設定且可自訂的開發環境。您可以建立工作站設定，以可重現的方式指定環境，而不需要要求開發人員安裝軟體和執行設定指令碼。工作站設定的任何更新都會在下次啟動時自動套用至工作站。開發人員可以透過瀏覽器 IDE、多種本機程式碼編輯器 (例如 VSCode 或 JetBrains IDE，例如 IntelliJ IDEA Ultimate 和 PyCharm Professional)，或是透過 SSH 存取工作站。

Cloud Workstations 會使用下列 Google Cloud 資源管理開發環境：

工作站叢集可用來指定特定區域內的一組工作站，以及其連結的虛擬私有雲網路。工作站叢集與 Google Kubernetes Engine (GKE) 叢集無關。
工作站設定可做為工作站範本，工作站設定會定義詳細資料，例如工作站虛擬機器 (VM) 執行個體類型、永久性儲存空間、容器映像檔定義環境、要使用的 IDE 或程式碼編輯器等等。管理員和平台團隊也可以使用身分與存取權管理 (IAM) 規則，授予團隊或個別開發人員存取權。
Workstations 是預先設定的開發環境，可提供雲端 IDE、語言工具、程式庫等。工作站可視需要啟動或停止，並在專案中的 Compute Engine VM 上執行，並附加永久磁碟來儲存工作階段之間的資料。

管理員和平台團隊會建立工作站設定，並與開發團隊分享。每位開發人員都會根據工作站設定建立工作站。

在本研究室中，您會使用瀏覽器 IDE，但 Cloud Workstations 也支援其他常見的開發介面：

您可以透過 JetBrains Gateway 使用自己的本機 JetBrains IDE
如果您使用本機 VSCode，也可以透過 SSH 存取工作站，進行遠端開發作業。
您也可以從本機電腦設定 SSH 和 TCP 通道，連線至工作站

(選用部分) 建立工作站叢集

這些步驟會在實驗室設定期間執行，因此您不需要執行這些步驟。

這些步驟說明如何設定 Cloud Workstations 叢集、設定和工作站。

請參閱本節內容，然後前往「Forge 平台」一節。

建立工作站叢集：

gcloud workstations clusters create ws-cluster --region=us-central1

建立工作站設定

gcloud workstations configs create devai-config \
--cluster=ws-cluster \
--machine-type=e2-standard-8 \
--region=us-central1 \
--running-timeout=21600 \
--idle-timeout=1800 \
--container-predefined-image=codeoss \
--pd-disk-size=200 \
--pd-disk-type=pd-standard \
--service-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com \
--pool-size=1

建立工作站

gcloud workstations create devai-workstation \
--cluster=ws-cluster \
--config=devai-config \
--region=us-central1

在 Cloud 控制台中查看可用的電腦工作站。啟動並執行「devai-workstation」。

啟用右下角的「Gemini」，按照新瀏覽器分頁中的登入流程操作，然後將產生的程式碼複製回控制台，完成登入程序。

開啟左側面板中的「Gemini」對話方塊，並詢問 Gemini：

「You are a Cloud Workstations Product Manager, tell me about Cloud Workstations」。

「You are Cloud Workstations Product Manager, Can I create my custom Cloud Workstations image with my company tools so new developers can onboard in minutes?」。

(END OF OPTIONAL SECTION)

13. Forge 平台

Forge 是一個平台，可讓開發人員建構可與 Atlassian 產品 (例如 Jira、Confluence、Compass 和 Bitbucket) 整合的應用程式。

安裝 Forge CLI

在終端機中執行下列指令。

下載 Node 版本管理工具 ( nvm)，並在目前的終端機工作階段中提供該工具的路徑。

cd ~/github/genai-for-developers

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash


export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

安裝 nvm。

在終端機中執行下列指令，選取最新的 Node.js LTS 版本：

nvm install --lts
nvm use --lts

執行以下指令，即可全域安裝 Forge CLI：

npm install -g @forge/cli

在本實驗室中，我們將使用環境變數登入。

設定 JIRA 專案

使用個人帳戶建立/查看 JIRA 專案。

查看現有的 JIRA 專案：https://admin.atlassian.com/

使用個人帳戶建立新的 JIRA 專案。

前往 https://team.atlassian.com/your-work，按一下，然後選取。接著，選取「JIRA Software」-「立即試用」。按照提示完成專案/網站建立程序。

選取「JIRA 軟體」。

建立新專案。

14. Atlassian API 權杖

建立或使用現有的 Atlassian API 權杖，登入 CLI。

CLI 執行指令時會使用您的權杖。

前往 https://id.atlassian.com/manage/api-tokens。
按一下「Create API token」。
輸入用來描述 API 權杖的標籤。例如 forge-api-token。
按一下「建立」。
按一下「複製到剪貼簿」，然後關閉對話方塊。

在 Cloud Workstations 終端機中執行下列指令。

登入 Forge CLI 即可開始使用 Forge 指令。

設定 JIRA/FORGE 電子郵件地址。請將電子郵件地址替換為自己的電子郵件地址。

export FORGE_EMAIL=your-email

設定 Forge API 權杖。請用您的 JIRA API 權杖代碼取代。

export FORGE_API_TOKEN=your-jira-api-token

執行下列指令測試 Forge CLI。系統要求收集數據分析時，請回覆「No」。

forge settings set usage-analytics false

確認你是否已登入。

forge whoami

輸出內容範例。

Logged in as John Green (johngreen@email.com)
Account ID: 123090:aaabbcc-076a-455c-99d0-d1aavvccdd

建立 Forge 應用程式

確認您位於「~/github/genai-for-developers」資料夾。

執行指令來建立 Forge 應用程式。

forge create

系統提示時，請使用下列值：

應用程式名稱：devai-jira-ui-qwiklabs
選取類別：UI Kit
選取產品：Jira
選取範本：jira-issue-panel

切換至應用程式資料夾。

cd devai-jira-ui-qwiklabs/

執行部署指令。

forge deploy

輸出內容範例：

Deploying your app to the development environment.
Press Ctrl+C to cancel.

Running forge lint...
No issues found.

✔ Deploying devai-jira-ui-qwiklabs to development...

ℹ Packaging app files
ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

安裝應用程式。

forge install

系統提示時，請使用下列值：

選取產品：Jira
輸入網站網址：your-domain.atlassian.net

輸出內容範例：

Select the product your app uses.

? Select a product: Jira

Enter your site. For example, your-domain.atlassian.net

? Enter the site URL: genai-for-developers.atlassian.net

Installing your app onto an Atlassian site.
Press Ctrl+C to cancel.

? Do you want to continue? Yes

✔ Install complete!

Your app in the development environment is now installed in Jira on genai-for-developers.atlassian.net

開啟 JIRA 網站，然後建立新的 JIRA 工作，並附上以下說明：

Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything.

開啟工作時，您會看到「devai-jira-ui-qwiklabs」按鈕。

按一下按鈕，並在 UI 中查看變更內容。

查看 Forge 後端記錄。

forge logs

Atlassian 開發人員控制台

您也可以在 Atlassian Developer Console 中查看及管理已部署的應用程式。

查看記錄 - 切換至 Development 環境

查看 Forge 應用程式資訊清單和原始碼

開啟「devai-jira-ui-qwiklabs/manifest.yml」檔案，並使用 Gemini Code Assist 進行說明。

查看說明。

開啟下列檔案，並請 Gemini Code Assist 說明：

devai-jira-ui-qwiklabs/src/frontend/index.jsx
devai-jira-ui-qwiklabs/src/resolvers/index.js

使用 DevAI API Cloud Run 端點更新 Forge 應用程式

檢查是否已設定 GCP 專案 ID：

gcloud config get project

如果沒有，請使用 Qwiklabs 實驗室頁面中的專案 ID 設定 GCP 專案：

範例：qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

設定 Cloud Run 服務網址：

export DEVAI_API_URL=$(gcloud run services list --filter="(devai-api)" --format="value(URL)")

forge variables set DEVAI_API_URL $DEVAI_API_URL

執行下列指令確認：

forge variables list

輸出內容範例

更新 Forge 應用程式資訊清單和程式碼

這些程式碼片段位於 sample-devai-jira-ui 資料夾底下的存放區中。

在編輯器中開啟資訊清單檔案：devai-jira-ui-qwiklabs/manifest.yml

在檔案結尾處加入下列程式碼行，並將 Cloud Run 端點替換為您部署的端點。

permissions:
  scopes:
    - read:jira-work
    - write:jira-work
  external:
    fetch:
      client:
        - devai-api-gjerpi6qqq-uc.a.run.app/generate # replace with YOUR CLOUD RUN URL

在編輯器中開啟解析器/索引檔案：devai-jira-ui-qwiklabs/src/resolvers/index.js

請在現有 getText 函式後方加入以下程式碼行。

resolver.define('getApiKey', (req) => {
  return process.env.LLM_API_KEY;
});

resolver.define('getDevAIApiUrl', (req) => {
  return process.env.DEVAI_API_URL;
});

在編輯器中開啟前端/索引檔案：devai-jira-ui-qwiklabs/src/frontend/index.jsx

請將 index.jsx 替換為下方內容。更新 GitLab 使用者 ID/存放區的連結。

您需要在兩個地方更新 YOUR-GIT-USERID 和 YOUR-GIT-REPO。

在檔案中搜尋這行，然後進行變更：

https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests

import React from 'react';
import ForgeReconciler, { Text, Link, useProductContext } from '@forge/react';
import { requestJira } from '@forge/bridge';
import { invoke } from '@forge/bridge';
import api, { route, assumeTrustedRoute } from '@forge/api';

// const apiKey = await invoke("getApiKey")
const devAIApiUrl = await invoke("getDevAIApiUrl")


const App = () => {
  const context = useProductContext();

  const [description, setDescription] = React.useState();

  const fetchDescriptionForIssue = async () => {
    const issueId = context?.extension.issue.id;
  
    const res = await requestJira(`/rest/api/2/issue/${issueId}`);
    const data = await res.json();
    
    // const genAI = new GoogleGenerativeAI(apiKey);
    // const model = genAI.getGenerativeModel({ model: "gemini-pro"});
    // const prompt = `You are principal software engineer at Google and given requirements below to implement.\nPlease provide implementation details and documentation.\n\nREQUIREMENTS:\n\n${data.fields.description}`
    // const result = await model.generateContent(prompt);
    // const text = result.response.text();
    // const jsonText = JSON.stringify(text);

    const bodyGenerateData = `{"prompt": ${JSON.stringify(data.fields.description)}}`;

    const generateRes = await api.fetch(devAIApiUrl+'/generate',
      {
        body: bodyGenerateData,
        method: 'post',
        headers: { 'Content-Type': 'application/json' },
      }
    )


    const resData = await generateRes.text();
    const jsonText = JSON.stringify(resData);

    const bodyData = `{
      "body": ${jsonText}
    }`;

    console.log("bodyData", bodyData)
    // Add Gemini response as a comment on the JIRA issue
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: bodyData
    });
    // Add link to the GitLab merge request page as a comment
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: `{"body": "[GitLab Merge Request|https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests]"}`
    });


    return "Response will be added as a comment. Please refresh in a few moments.";
  };

  React.useEffect(() => {
    if (context) {
      fetchDescriptionForIssue().then(setDescription);
    }
  }, [context]);

  return (
    <>
      <Text>{description}</Text>
      <Link href='https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests' openNewTab={true}>GitLab Merge Request</Link>
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

重新部署 Forge 應用程式

在 package.json 檔案中新增依附元件：

"@forge/api": "4.0.0",

安裝依附元件：

npm install

部署更新後的應用程式：

forge deploy

輸出內容範例：

ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

We've detected new scopes or egress URLs in your app.
Run forge install --upgrade and restart your tunnel to put them into effect.

安裝更新版應用程式：

forge install --upgrade

輸出內容範例：

Upgrading your app on the Atlassian site.

Your app will be upgraded with the following additional scopes:
- read:jira-work
- write:jira-work

Your app will exchange data with the following urls:
- devai-api-7su2ctuqpq-uc.a.run.app

? Do you want to continue? Yes

✔ Upgrade complete!

Your app in the development environment is now the latest in Jira on genai-for-developers.atlassian.net.

測試 Forge 應用程式

在 JIRA 專案中開啟現有的 JIRA 工作，或建立新的 JIRA 工作。

如果先前已新增面板，請移除該面板。

按一下「...」，然後在選單中選取「移除」。之後，您可以再次點選按鈕。

查看 Jira 留言

收到 DEVAI API 的回應後，系統會在 JIRA 問題上新增兩則註解。

GitLab 合併要求
Gemini 使用者故事實作詳細資料

切換「History」和「Comments」分頁，即可重新整理檢視畫面。

啟用 GitLab 合併要求建立功能

開啟 devai-api/app/routes.py 檔案，並取消註解 generate_handler 方法中的下列行：

print(f"{response.text}\n")

    # resp_text = response.candidates[0].content.parts[0].text

    # pr_prompt = f"""Create GitLab merge request using provided details below.
    # Create new files, commit them and push them to opened merge request.
    # When creating new files, remove the lines that start with ``` before saving the files.

    # DETAILS: 
    # {resp_text}
    # """

    # print(pr_prompt)
    # agent.invoke(pr_prompt)

重新部署 Cloud Run 應用程式

確認你位於正確的資料夾。

cd ~/github/genai-for-developers/devai-api

如果您使用的是同一個終端機工作階段，可能仍會設定所有環境變數。

請在終端機中執行「echo $GITLAB_REPOSITORY」來確認。

如果您已開啟新的終端機工作階段，請按照下列步驟重設。

請務必先重設必要的環境變數，再重新部署應用程式。

您必須更新 GitLab 使用者 ID 和存放區名稱，才能執行這項指令。

export GITLAB_REPOSITORY="USERID/REPOSITORY"

設定其他環境變數：

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api
export PROJECT_ID=$(gcloud config get-value project)

export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

GitLab 工具包會使用「devai」分支，將合併要求的變更內容推送。

確認您已建立該分支。

將應用程式部署至 Cloud Run。

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

驗證端對端整合

再次按一下按鈕，從 JIRA 工作項啟動程序，並在 GitLab 存放區的「Merge request」部分和 LangSmith 中驗證輸出內容。

GitLab 合併要求詳細資料。

LangSmith LLM 追蹤記錄

開啟 LangSmith 入口網站，並查看 JIRA 問題建立呼叫的 LLM 追蹤記錄。

範例 LangSmith 大型語言追蹤記錄。

(選用章節) 將變更推送至 GitHub 存放區

前往 GitHub 網站，建立新的存放區，將本研究室的變更推送至個人存放區。

返回 Cloud Workstations 執行個體，並在終端機中設定 Git 使用者名稱和電子郵件。

請先更新值，再執行指令。

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

產生安全殼層 (SSH) 金鑰，並將其新增至 GitHub 存放區。

請先更新電子郵件，再執行指令。

請勿輸入通關密語，並按下 Enter 鍵多次來完成金鑰產生程序。

ssh-keygen -t ed25519 -C "your-email-address"

eval "$(ssh-agent -s)"

ssh-add ~/.ssh/id_ed25519

cat ~/.ssh/id_ed25519.pub

將產生的公開金鑰新增至 GitHub 帳戶。

開啟 https://github.com/settings/keys，然後按一下「New SSH key」。

請使用「qwiklabs-key」做為金鑰名稱，並複製/貼上上一個指令的輸出內容。

返回終端機，修訂並推送變更。

cd ~/github/genai-for-developers

git remote rm origin

使用上述建立的存放區設定遠端來源。

請用您的存放區網址取代。

git remote add origin git@github.com:YOUR-GITHUB-USERID/YOUR-GITHUB-REPO.git

新增、修訂及推送變更。

git add .

git commit -m "lab changes"

git push -u origin main

15. 恭喜！

恭喜，您已完成實驗室！

涵蓋內容：

如何部署 Cloud Run 應用程式，以便與 Gemini API 整合。
如何建立及部署 Atlassian Forge 應用程式 (適用於 JIRA)。
如何使用 LangChain ReAct Agent 自動執行 GitLab 工作。
如何在 LangSmith 中查看 LLM 追蹤記錄。

下一步：

更多實作課程即將推出！

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。