הטמעת סיפורי משתמשים ב-JIRA באמצעות GenAI

מידע על Codelab זה

העדכון האחרון: מרץ 24, 2025

נכתב על ידי Andrey Shakirov

דף זה תורגם על ידי Cloud Translation API.

1.‏ סקירה כללית

במעבדה הזו תלמדו איך ליצור פתרון לאוטומציה של הטמעת סיפורי משתמשים ב-JIRA באמצעות GenAI.

מה תלמדו

הסדנה מורכבת מכמה חלקים עיקריים:

פריסה של אפליקציית Cloud Run לשילוב עם ממשקי Gemini API
יצירת אפליקציה של Atlassian Forge ל-JIRA ופריסה שלה
שימוש ב-LangChain ReAct Agents לאוטומציה של משימות ב-GitLab

דרישות מוקדמות

ההנחה בשיעור ה-Lab הזה היא שיש לכם היכרות עם סביבות Cloud Console ו-Cloud Shell.

הגדרת פרויקט ב-Cloud

נכנסים למסוף Google Cloud ויוצרים פרויקט חדש או משתמשים מחדש בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, עליכם ליצור חשבון.

שם הפרויקט הוא השם המוצג של המשתתפים בפרויקט. זוהי מחרוזת תווים שלא משמשת את Google APIs. תמיד אפשר לעדכן אותו.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו אחרי שמגדירים אותו. מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי. בדרך כלל לא משנה מה המחרוזת הזו. ברוב ה-codelabs תצטרכו להפנות למזהה הפרויקט (בדרך כלל מזהים אותו בתור PROJECT_ID). אם המזהה שנוצר לא מוצא חן בעיניכם, תוכלו ליצור מזהה אקראי אחר. לחלופין, אפשר לנסות כתובת משלכם ולבדוק אם היא זמינה. לא ניתן לשנות אותו אחרי השלב הזה, והוא נשאר למשך כל פרק הזמן של הפרויקט.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שמשתמשים בו בחלק מממשקי ה-API. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי העזרה.

בשלב הבא, כדי להשתמש במשאבים או ב-API של Cloud, תצטרכו להפעיל את החיוב במסוף Cloud. השלמת הקודלאב הזה לא תעלה הרבה, אם בכלל. כדי להשבית את המשאבים ולמנוע חיובים אחרי סיום המדריך, אפשר למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בסך 300$.

הגדרת הסביבה

פותחים את Gemini Chat.

אפשר גם להקליד 'יש לך שאלה ל-Gemini?' בסרגל החיפוש.

מפעילים את Gemini for Google Cloud API:

לוחצים על 'Start chatting' ופועלים לפי אחת מהשאלות לדוגמה או מקלידים הנחיה משלכם כדי לנסות את התכונה.

הנחיות שאפשר לנסות:

הסבר על Cloud Run ב-5 נקודות עיקריות.
אתם מנהלי מוצרים ב-Google Cloud Run, ואתם צריכים להסביר לתלמיד/ה על Cloud Run ב-5 נקודות עיקריות קצרות.
אתם מנהלי מוצרים ב-Google Cloud Run, ואתם צריכים להסביר את Cloud Run למפתח Kubernetes מוסמך ב-5 נקודות עיקריות קצרות.
אתם מנהלי מוצר של Google Cloud Run, ואתם צריכים להסביר למפתח בכיר מתי כדאי להשתמש ב-Cloud Run לעומת GKE, ב-5 נקודות מפתח קצרות.

במדריך להנחיות מוסבר איך לכתוב הנחיות טובות יותר.

איך Gemini for Google Cloud משתמש בנתונים שלכם

המחויבות של Google לפרטיות

Google הייתה אחת מהחברות הראשונות בתחום שפרסמתה מחויבות לפרטיות ב-AI/ML, שבה אנו מבטאים את האמונה שלנו שללקוחות צריכה להיות רמה הגבוהה ביותר של אבטחה ושליטה על הנתונים שלהם שמאוחסנים בענן.

נתונים שאתם שולחים ומקבלים

השאלות שאתם שואלים את Gemini, כולל כל פרטי הקלט או הקוד שאתם שולחים ל-Gemini לצורך ניתוח או השלמה, נקראות הנחיות. התשובות או השלמות הקוד שאתם מקבלים מ-Gemini נקראות תגובות. Gemini לא משתמש בהנחיות שלכם או בתשובות שלו כנתונים לאימון המודלים שלו.

הצפנה של הנחיות

כששולחים הנחיות ל-Gemini, הנתונים מוצפנים במעבר כקלט למודל הבסיסי ב-Gemini.

נתוני תוכנית שנוצרו מ-Gemini

‫Gemini מאומן על קוד מ-Google Cloud (מצד ראשון) ועל קוד נבחר של צד שלישי. אתם אחראים על האבטחה, הבדיקה והיעילות של הקוד שלכם, כולל כל השלמה, יצירה או ניתוח של קוד ש-Gemini מציעה לכם.

מידע נוסף על האופן שבו Google מטפלת בהנחיות

3.‏ אפשרויות לבדיקה של הנחיות

יש כמה דרכים לבדוק את ההנחיות.

Vertex AI Studio

Vertex AI Studio הוא חלק מפלטפורמת Vertex AI של Google Cloud, שמיועדת במיוחד לפשט ולהאיץ את הפיתוח והשימוש במודלים של AI גנרטיבי.

Google AI Studio

Google AI Studio הוא כלי מבוסס-אינטרנט ליצירת אב טיפוס ולניסויים בתכנון הנחיות וב-Gemini API.

אפליקציית Gemini בדפדפן (gemini.google.com)

אפליקציית האינטרנט של Google Gemini‏ (gemini.google.com) היא כלי מבוסס-אינטרנט שמיועד לעזור לכם לגלות את מלוא הפוטנציאל של מודלי ה-AI של Gemini מבית Google ולהשתמש בו.

אפליקציית Google Gemini לנייד ל-Android ו-אפליקציית Google ל-iOS

4.‏ בדיקת הבקשה

יצירת חשבון שירות

חוזרים למסוף Google Cloud ומפעילים את Cloud Shell בלחיצה על הסמל שמשמאל לסרגל החיפוש.

במסוף שנפתח, מריצים את הפקודות הבאות כדי ליצור חשבון שירות ומפתחות חדשים.

תשתמשו בחשבון השירות הזה כדי לבצע קריאות API ל-Vertex AI Gemini API מאפליקציית Cloud Run.

מגדירים את פרטי הפרויקט באמצעות פרטי הפרויקט ב-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'

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"

אם מתבקשים לאשר, לוחצים על 'אישור' כדי להמשיך.

מפעילים את השירותים הנדרשים כדי להשתמש ב-Vertex AI APIs וב-Gemini Chat.

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

מפעילים את השירותים הנדרשים כדי להשתמש ב-Vertex AI APIs וב-Gemini Chat.

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

שכפול של מאגר GitHub

משכפלים את המאגר ב-GitHub.

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

פתיחת Cloud Shell Editor

באמצעות פריט התפריט File / Open Folder, פותחים את genai-for-developers.

פותחים את הקובץ devai-api/app/routes.py, לוחצים לחיצה ימנית במקום כלשהו בקובץ ובוחרים באפשרות Gemini > Explain this" בתפריט ההקשר.

קוראים את ההסבר של Gemini לגבי הקובץ שנבחר.

5.‏ הגדרת מאגר ו-Toolkit של GitLab

במעבדה הזו נשתמש ב-GitLabToolkit כדי ליצור בקשות מיזוג ב-GitLab באופן אוטומטי.

סקירה כללית על ערכות הכלים של LangChain

LangChain Toolkits הם ערכות כלים שנועדו לייעל ולשפר את הפיתוח של אפליקציות באמצעות LangChain. הן מציעות פונקציות שונות בהתאם לערכת הכלים הספציפית, אבל באופן כללי הן עוזרות בנושאים הבאים:

קישור למקורות נתונים חיצוניים: גישה למידע מממשקי API, ממסדי נתונים וממקורות חיצוניים אחרים, ושילוב המידע הזה באפליקציות של LangChain.
שיטות מתקדמות להנחיה: שימוש בהנחיות שהוגדרו מראש או יצירה של הנחיות בהתאמה אישית כדי לבצע אופטימיזציה של האינטראקציות עם מודלים של שפה.
יצירה וניהול של שרשורים: אפשר ליצור שרשורים מורכבים בקלות ולנהל אותם ביעילות.
הערכה ומעקב: ניתוח הביצועים של האפליקציות והשרשראות של LangChain.

ערכות כלים פופולריות של LangChain כוללות:

ערכות כלים להפעלת סוכנים: כלים לפיתוח סוכנים שיכולים לקיים אינטראקציה עם העולם האמיתי באמצעות פעולות כמו גלישה באינטרנט או ביצוע קוד.
ערכת הכלים לתכנון הנחיות: אוסף משאבים ליצירת הנחיות יעילות.

סקירה כללית על GitLab Toolkit

ערכת הכלים של Gitlab מכילה כלים שמאפשרים לסוכן LLM לקיים אינטראקציה עם מאגר Gitlab. הכלי הוא מעטפת לספרייה python-gitlab.

ערכת הכלים של GitLab יכולה לבצע את המשימות הבאות:

Create File – יצירת קובץ חדש במאגר.
קריאת קובץ – קריאת קובץ מהמאגר.
עדכון קובץ – עדכון קובץ במאגר.
Create Pull Request – יצירת בקשת משיכה מההסתעפות הפעילה של הרובוט להסתעפות הבסיסית.
Get Issues – אחזור בעיות מהמאגר.
Get Issue – אחזור פרטים על בעיה ספציפית.
תגובה על בעיה – פרסום תגובה לגבי בעיה ספציפית.
Delete File – מחיקה של קובץ מהמאגר.

הגדרת פרויקט ב-GitLab

פותחים את GitLab, יוצרים פרויקט חדש ומגדירים את אסימון הגישה לפרויקט בקטע Settings / Access Tokens.

יש להשתמש בפרטים הבאים:

שם הטוקן: devai-api-qwiklabs
תפקיד: Maintainer
בוחרים את ההיקפים: api

מעתיקים את הערך של אסימון הגישה ומדביקים אותו בקובץ זמני במחשב הנייד. הערך הזה ישמש בשלבים הבאים.

6.‏ הכנה לפריסה של אפליקציה ב-Cloud Run

חוזרים ל-Cloud Shell Editor ומשתמשים בטרמינל קיים או פותחים טרמינל חדש.

מגדירים את פרטי הפרויקט באמצעות פרטי הפרויקט ב-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 GITLAB_PERSONAL_ACCESS_TOKEN. זוהי דרך מאובטחת להגדיר משתני סביבה בלי שהערך יופיע בהיסטוריית הפקודות של המסוף. אחרי ההפעלה, צריך להדביק את הערך וללחוץ על Enter. צריך לייצא גם את משתנה הסביבה: export GITLAB_PERSONAL_ACCESS_TOKEN

כדי להשתמש בפקודה הזו, צריך לעדכן את מזהה המשתמש ואת שם המאגר ב-GitLab.

לדוגמה: 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"

הגדרת המעקב של LangSmith LLM

מגדירים את החשבון אם רוצים להציג את פרטי המעקב אחר הסוכן ב-LangSmith, אחרת מריצים את הפקודות כפי שהן.

יוצרים חשבון LangSmith ויוצרים מפתח Service API בקטע 'הגדרות'. https://smith.langchain.com/settings

מגדירים את משתני הסביבה הנדרשים לשילוב עם LangSmith.

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

export LANGCHAIN_API_KEY=langchain-service-api-key

הגדרת 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

יצירת מפתח API

יוצרים מפתח API חדש בקטע Cloud Console / API & Services / Credentials.

המפתח הזה ישמש לאימות קריאות ל-JIRA API באפליקציה של Cloud Run.

בסביבת הייצור, צריך להגדיר הגבלות על אפליקציות וממשקי API למפתח ה-API שנוצר. הגבלות על אפליקציות מגבילות את השימוש במפתח API לאתרים ספציפיים(למשל, המכונה שלכם ב-JIRA).

הגדרת משתני הסביבה הנדרשים לפריסה של שירות Cloud Run.

export DEVAI_API_KEY=your-api-key

יצירת סודות ב-Secret Manager

במעבדה הזו, אנחנו פועלים לפי השיטות המומלצות ומשתמשים ב-Secret Manager כדי לאחסן את הערכים של אסימוני הגישה, מפתח ה-API ומפתח ה-API של LangChain ב-Cloud Run, ולהפנות אליהם.

יצירה ואחסון של סודות נדרשים ב-Secret Manager.

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

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

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

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

7.‏ פריסה של Devai-API ב-Cloud Run

מוודאים שנמצאים בתיקייה הנכונה.

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

פריסת האפליקציה ב-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" \
  --update-secrets="DEVAI_API_KEY=DEVAI_API_KEY:latest" \
  --min-instances=1 \
  --max-instances=3

משיבים Y כדי ליצור מאגר Docker ב-Artifact Registry.

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=.. מידע נוסף

מאחורי הקלעים, הפקודה הזו משתמשת ב-buildpacks וב-Cloud Build של Google Cloud כדי ליצור באופן אוטומטי קובצי אימג' של קונטיינרים מקוד המקור, בלי שתצטרכו להתקין את Docker במכונה או להגדיר buildpacks או Cloud Build. כלומר, הפקודה היחידה שמתוארת למעלה מבצעת את הפעולה שנדרשות לה אחרת הפקודות gcloud builds submit ו-gcloud run deploy.

אם סיפקתם קובץ Dockerfile(כפי שעשינו במאגר הזה), Cloud Build ישתמש בו כדי ליצור קובצי אימג' של קונטיינרים, במקום להסתמך על ה-buildpacks כדי לזהות קובצי אימג' של קונטיינרים וליצור אותם באופן אוטומטי. מידע נוסף על buildpacks זמין במסמכי התיעוד.

בודקים את היומנים של Cloud Build במסוף.

בודקים את קובץ האימג' של Docker שנוצר ב-Artifact Registry.

בודקים את פרטי המכונה של Cloud Run במסוף Cloud.

אפליקציית בדיקה

בודקים את נקודת הקצה על ידי הרצת הפקודה curl.

לפני שמריצים את הפקודה, צריך לעדכן את כתובת ה-URL של שירות Cloud Run.

דוגמה:

curl -H "X-devai-api-key: $DEVAI_API_KEY" https://devai-api-1110000001.us-central1.run.app/test

8.‏ הטמעה אוטומטית של סטורי

Forge היא פלטפורמה שמאפשרת למפתחים ליצור אפליקציות שמשולבות עם מוצרי Atlassian, כמו Jira, ‏ Confluence, ‏ Compass ו-Bitbucket.

התקנת Forge CLI

כדי להתקין את Forge CLI באופן גלובלי, מריצים את הפקודה:

npm install -g @forge/cli

בשיעור ה-Lab הזה נשתמש במשתני סביבה כדי להתחבר.

הגדרת פרויקט ב-JIRA

שימוש בחשבון האישי ליצירה או לצפייה בפרויקטים ב-JIRA

בודקים את הפרויקטים הקיימים ב-JIRA: https://admin.atlassian.com/

יוצרים פרויקט חדש ב-JIRA באמצעות החשבון האישי.

עוברים אל https://team.atlassian.com/your-work ולוחצים על ואז על . לאחר מכן, בוחרים באפשרות 'JIRA Software' – 'Try it now'. פועלים לפי ההוראות כדי להשלים את יצירת הפרויקט או האתר.

בוחרים באפשרות JIRA Software.

יוצרים פרויקט חדש.

יצירת טוקן API של Atlassian

יוצרים אסימון API קיים של Atlassian או משתמשים בו כדי להתחבר ל-CLI.

ה-CLI משתמש באסימון שלכם כשמריצים פקודות.

עוברים לכתובת https://id.atlassian.com/manage/api-tokens.
לוחצים על Create API token.
מזינים תווית לתיאור של טוקן ה-API. לדוגמה, forge-api-token.
לוחצים על יצירה.
לוחצים על העתקה ללוח וסוגרים את תיבת הדו-שיח.

הגדרת הגדרות הסביבה של Forge

חוזרים ל-Cloud Console ומריצים את הפקודות הבאות בטרמינל.

כדי להתחיל להשתמש בפקודות של Forge, צריך להתחבר ל-CLI של Forge.

מגדירים את כתובת האימייל ב-JIRA או ב-FORGE. מחליפים את הכתובת בכתובת האימייל שלכם.

export FORGE_EMAIL=your-email

מגדירים את טוקן ה-API של Forge. מחליפים את הטוקן של JIRA API.

export FORGE_API_TOKEN=your-jira-api-token

מריצים את הפקודה הבאה כדי לבדוק את ה-CLI של Forge. עונים 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

בודקים שאתם נמצאים בתיקייה ~/genai-for-developers.

מריצים את הפקודה כדי ליצור אפליקציה ב-Forge.

forge create

כשמוצגת בקשה, מזינים את הערכים הבאים:

שם האפליקציה: devai-jira-ui-qwiklabs
בוחרים קטגוריה: UI Kit
בוחרים מוצר: Jira
בוחרים תבנית: jira-issue-panel

עוברים לתיקיית האפליקציה.

cd devai-jira-ui-qwiklabs/

מריצים את הפקודה כדי להתקין את יחסי התלות.

npm install

מריצים את פקודת הפריסה.

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
מזינים את כתובת ה-URL של האתר: 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.

לוחצים על הלחצן ובודקים את השינויים בממשק המשתמש.

הצגת יומני הקצה העורפי של Forge.

forge logs

Atlassian Developer Console

אפשר גם להציג ולנהל אפליקציות שנפרסו ב-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

עדכון אפליקציית Forge באמצעות נקודת קצה של DevAI API ב-Cloud Run

בודקים אם מזהה הפרויקט ב-GCP מוגדר:

gcloud config get project

אם לא, מגדירים את פרויקט GCP באמצעות מזהה הפרויקט שבדף של סדנת Qwiklabs:

לדוגמה: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

מגדירים את כתובת ה-URL של שירות 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

מגדירים את מפתח ה-API של DEVAI:

export DEVAI_API_KEY=api-key-that-you-created

forge variables set --encrypt DEVAI_API_KEY $DEVAI_API_KEY

מאשרים על ידי הפעלת הפקודה הבאה:

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/create-gitlab-mr # replace with YOUR CLOUD RUN URL

פותחים את קובץ המפַתח/האינדקס בעורך: devai-jira-ui-qwiklabs/src/resolvers/index.js

מוסיפים את השורות הבאות אחרי הפונקציה getText הקיימת.

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

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

פותחים את הקובץ frontend/index בעורך: devai-jira-ui-qwiklabs/src/frontend/index.jsx

מחליפים את index.jsx בתוכן שבהמשך. מעדכנים את הקישור למזהה המשתמש או למאגר ב-GitLab.

יש שני מקומות שבהם צריך לעדכן את 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 devAIApiKey = 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 bodyGenerateData = `{"prompt": ${JSON.stringify(data.fields.description)}}`;

    const generateRes = await api.fetch(devAIApiUrl+'/create-gitlab-mr,
      {
        body: bodyGenerateData,
        method: 'post',
        headers: {
          'Content-Type': 'application/json',
          'x-devai-api-key': devAIApiKey,
         },
      }
    )

    const resData = await generateRes.text();

    // 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

לאחר קבלת תשובה מ-DEVAI API, תתווסף תגובה לבקשה ב-JIRA.

קישור לבקשת המיזוג ב-GitLab

עוברים בין הכרטיסיות History ו-Comments כדי לרענן את התצוגה.

אימות בקשת המיזוג ב-GitLab

פותחים את GitLab ובודקים אם יש בקשות מיזוג חדשות בפרויקט.

מעקבים של LangSmith LLM

אם הגדרתם מעקב LLM, פותחים את LangSmith portal ובודקים את המעקב של LLM בקריאה ליצירת בקשת מיזוג ב-GitLab.

דוגמה למעקב אחר LLM של LangSmith.

9.‏ דחיפת השינויים למאגר ב-GitHub

(קטע אופציונלי)

נכנסים לאתר של GitHub ויוצרים מאגר חדש כדי לדחוף את השינויים של הסדנה הזו למאגר האישי שלכם.

חוזרים למסוף Cloud ומגדירים את שם המשתמש ואת כתובת האימייל של 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 ~/genai-for-developers

git remote rm origin

מגדירים את המקור המרוחק באמצעות המאגר שנוצר למעלה.

מחליפים את הכתובת בכתובת ה-URL של המאגר.

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

10.‏ מעולה!

כל הכבוד, סיימת את שיעור ה-Lab!

הנושאים שעסקנו בהם:

איך לפרוס אפליקציות של Cloud Run כדי לשלב אותן עם ממשקי Gemini API.
איך יוצרים ומפרסים אפליקציה של Atlassian Forge ל-JIRA.
איך משתמשים ב-LangChain ReAct Agents לאוטומציה של משימות ב-GitLab.
איך בודקים את עקבות ה-LLM ב-LangSmith.

השלב הבא:

בקרוב נוסיף עוד סשנים מעשיים.

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים הנפרדים.

מחיקת הפרויקט

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.

דיווח על טעות