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

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

בשיעור ה-Lab הזה תבנו פתרון לאוטומציה של הטמעה של סיפורי משתמשים ב-JIRA באמצעות AI גנרטיבי.

מה תלמדו

יש כמה חלקים עיקריים במעבדה:

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

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

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

2. הגדרה ודרישות

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

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

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

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

הגדרת הסביבה

פותחים צ'אט עם Gemini.

אפשר גם להקליד 'יש לך שאלה ל-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)

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

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

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

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

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

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

תשתמשו בחשבון השירות הזה כדי לבצע קריאות ל-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 API ובאינטראקציה עם Gemini, צריך להפעיל את השירותים הנדרשים.

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

כדי להשתמש ב-Vertex AI APIs ובאינטראקציה עם 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

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

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

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

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

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

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

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

סקירה כללית של ערכת הכלים של GitLab

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

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

‫Create File (יצירת קובץ) – יוצר קובץ חדש במאגר.
‫Read File (קריאת קובץ) – קורא קובץ מהמאגר.
Update File (עדכון קובץ) – מעדכן קובץ במאגר.
‫Create Pull Request (יצירת בקשת משיכה) – יוצר בקשת משיכה מענף העבודה של הבוט לענף הבסיס.
‫Get Issues – אחזור בעיות ממאגר.
‫Get Issue (קבלת בעיה) – אחזור פרטים על בעיה ספציפית.
‫Comment on Issue (הוספת תגובה לבעיה) – פרסום תגובה לבעיה ספציפית.
מחיקת קובץ – מחיקת קובץ מהמאגר.

הגדרת פרויקט ב-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"

הגדרת מעקב אחרי LLM ב-LangSmith

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

יוצרים חשבון LangSmith ומפיקים מפתח Service API בקטע Settings (הגדרות). 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 ומפתח LangChain API ב-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 Console.

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

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

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

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

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

הגדרת הגדרות סביבה ב-Forge

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

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

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

export FORGE_EMAIL=your-email

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

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

בודקים שאתם נמצאים בתיקייה ~/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

פותחים את הקובץ resolvers/index בכלי העריכה: 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.

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

לוחצים על ... ובוחרים באפשרות 'הסרה' מהתפריט. אחרי כן, אפשר ללחוץ שוב על הלחצן.

בדיקת התגובות ב-Jira

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

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

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

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

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

מעקבים של מודלים גדולים של שפה (LLM) ב-LangSmith

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

דוגמה לתיעוד עקבות של LLM ב-LangSmith.

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

(אופציונלי)

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

חוזרים ל-Cloud Console ומגדירים את שם המשתמש ואת כתובת האימייל של 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 APIs.
איך יוצרים ומפעילים אפליקציית Atlassian Forge ל-JIRA.
איך משתמשים ב-LangChain ReAct Agents לאוטומציה של משימות ב-GitLab.
איך בודקים עקבות של מודלים גדולים של שפה (LLM) ב-LangSmith.

השלב הבא:

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

הסרת המשאבים

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

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

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