Make quality profile (SonarQube) savable to SCM Industrial Project (234313) Make quality profile (SonarQube) savable to SCM Final Meeting Students: Meshi Fried, Ilanit Smul Supervisor: Assaf Katz SCM = source code management Computer Science Department Technion - Israel Institute of Technology

SonarQube is an open source platform for continuous inspection of code quality to perform automatic reviews with static analysis of code to detect bugs, code smells and security vulnerabilities on 20+ programming languages. SonarQube use “Quality Profiles” and “Quality Gates” to analyze your project. Quality Profile allowed you to define the requirements from the project by defining sets of rules, and with Quality Gate you can define set of Boolean conditions based on measure thresholds against which projects are measured. SonarQube's greatest asset is that it provides fully automated analysis and integration with Maven, Ant, Gradle, MSBuild and continuous integration tools. Introduction SonarQube היא מערכת open-source שמבצעת static code analysis למעל 20 שפות תכנות. SonarQube מאפשרת הצגת היסטוריה של ריצות קודמות, ובפרט באגים, הערות, unit tests ועוד. כדי לנתח את הקוד, יש לספק ל-SonarQube: quality profiles ו-quality gates. ב-quality profiles מגדירים את החוקים שעל הקוד לקיים, כאשר לכל שפה יש quality profile נפרד. ב-quality gates מגדירים תנאים בוליאניים המשמשים כתנאיי סף שעל הפרויקט לקיים על מנת שנוכל לעבור לשלב הבא ב-delivery. כיום, השליטה ב-quality profiles ו-quality gates נעשית דרך הדפדפן.

Goals Everything is code: Using configuration as code, in order to store SonarQube analysis as source code. Automation over SCM: Import and Export Quality Profiles and Quality Gates automatically straight to SCM (Git). Integrate with Jenkins: Defining Quality Profiles and Gates as injected configuration, and managing them through Jenkins. Goals מטרות: שימוש ב-configuration as code על מנת לאחסן את האנליזות של SonarQube כ-source code. אוטומציה מעל SCM: ביצוע import/export של profiles/gates ישר לתוך/מ- SCM. אינטגרציה עם ג'נקינס.

Methodology Familiarity with web services concepts. Understanding of the SonarQube API. Research on how to communicate with SonarQube server using REST API and OkHttp3 library for Groovy. Maintaining SonarQube Quality Profiles and Quality Gates with Git. Integrate our Groovy scripts with Jenkins by configuring a shared Library and writing pipeline scripts. Methodology מתודולוגיה: היכרות עם כל הקונספט של web services. הבנת ה-API של SonarQube. בדיקה כיצד ניתן לתקשר עם Sonar באמצעות REST API וספריית okhttp3 של Groovy. ניהול ה-profiles וה- gates דרך גיט. אינטגרציה עם ג'נקינס.

Automation the import and export of Quality Profile and Quality Gates. Full integration with Jenkins. Upload the project’s deliverables to: Git – including documentation (link). SonarQube community – in the near future. Achievements הישגים: ביצוע אוטומציה ל-import/export של profiles/gates. אינטגרציה עם גיט. העלאת תוצרי הפרויקט לגיט (יש קישור) ובהמשך לקהילת SonarQube.

Examples Demo Website – link דוגמאות: להפעיל את הדמו. להראות את האתר + הדוגמאות שיש בו. כנראה שנצטרך גם להראות הדגמה חיה של הפרויקט. TODO: להוסיף קישור לגיט ולהסביר שהתיעוד נמצא שם.

Milestones Week 1 (1.4-7.4): Week 2 (8.4-14.4): Understanding project goals. Planning the initial schedule. Experience with SonarQube: Investigating the current behavior of import and export quality profiles/gates. Focusing on Java and JavaScript projects. Week 2 (8.4-14.4): Familiarity with web services concepts. Understanding of the SonarQube API, and specially the “import” and “export” options. Research on how to communicate with SonarQube server using REST API and cURL commands. Milestones שבוע 1 (1.4-7.4): הבנת מטרות הפרויקט. תכנון הלו"ז הראשוני (עם התקדמות הפרויקט ביצענו שינויים בלו"ז זה). התנסות עם SonarQube: חקירת ההתנהגות הנוכחית ב-import & export של quality profile/gate, תוך התמקדות בפרויקטי Java ו-JavaScript. שבוע 2 (8.4-14.4): היכרות עם web services. הבנת ה-API של SonarQube, תוך התמקדות באפשרויות ה-import & export. בדיקה כיצד ניתן להפעיל את SonarQube תוך שימוש ב-REST API ובפקודות cURL.

Milestones Weeks 3-4 (15.4-28.4): Writing Batch scripts: Note: At this stage of the project we realized that the SonarQube API has fully supported in import and export of Quality Gate(contrary to our initial assumption), and therefore we had to change the schedule. export Quality Profile (XML file) from SonarQube. Export Profile: import Quality Profile (XML file) into SonarQube. Import Profile: export Quality Gate (json file) from SonarQube. Export Gate: import Quality Gate (json file) into SonarQube. Import Gate: Milestones שבועות 3-4 (15.4-25.4): כתיבת 4 סקריפטי batch: תוך שימוש בפקודות cURL ובעיקר GET ו-POST, וכן ע"י ה-API של SonarQube. export של quality profile: ייצוא מ-sonar אל תוך קובץ XML. import של quality profile: ייבוא של קובץ XML אל תוך sonar. export של quality gate: ייצוא מ-sonar אל תוך קובץ json. import של quality gate: ייבוא של קובץ json אל תוך sonar. הערה: כיום לא קיימת אפשרות מובנת ב-SonarQube ל-import&export של quality gates, לכן בתכנון הלו"ז הראשוני של הפרויקט חשבנו ששלב זה יימשך הרבה יותר זמן (כחודש). אולם, גילינו ש-sonar מציעה API המאפשר פעולות רבות נוספות (שאינן גלויות למשתמש הרגיל ב-sonar – דרך הדפדפן ולא ה-API), ובפרט את הפעולות הנדרשות עבור import&export של quality gates. לכן, שינינו את הלו"ז והוספנו משימות חדשות.

Milestones Week 5 (29.4-5.5): Rewrite the scripts to Groovy: Export Profile: <projectKey> OR <language> <profileName> Import Profile: <fileName> <token> OR <fileName> <username> <password> Export Gate: <gateName> <fileName> Import Gate: <fileName> <token> OR <fileName> <username> <password> Add support in authentication (username and password comparing to token). Minor fixes, such as: Maintain project association for profiles/gate after running the scripts. Milestones שבוע 5 (29.4-5.5): שכתוב 4 סקריפטי ה-batch ל-groovy: בשלב זה גיבשנו את הפורמט הכמעט-סופי של הסקריפטים (מבחינת פרמטרים) אולם בהמשך הפרויקט כנראה שנשנה אותו מעט. export של quality profile: קיימות שתי אפשרויות לביצוע הפעולה, הנבדלות באופיו של ה-profile שאותו רוצים לייצא – האם מדובר ב-profile ספציפי או ב-profile המשוייך לפרויקט מסויים. במקרה והתקבל פרמטר יחיד, כלומר projectKey (מעיין ID ייחודי לכל פרויקט ב-sonar), אז מבצעים export לכל ה-profiles שבשימוש הפרויקט בעל אותו projectKey. במקרה והתקבלו 2 פרמטרים, כלומר language (שפת התכנות שעבורה הוגדר ה-profile, כיום קיימות 6 שפות שנתמכות ע"י sonar) ו-profileName (השם של ה-profile הרצוי), אז מבצעים export רק ל-profile בעל אותו שפה ושם הזהים לפרמטרים שסופקו. import של quality profile: קיימות שתי אפשרויות לביצוע הפעולה, הנבדלות באופן ההתחברות ל-sonar – האם מדובר בשם משתמש וסיסמא או בדרך מאובטחת יותר כמו token. בשתי האפשרויות, מקבלים בנוסף לפרמטרים הנוגעים ל-authentication, פרמטר של filename (שם הקובץ המייצג את ה-profile שעבורו מבצעים import). export של quality gate: מקבל פרמטר של gateName (שם ה-gate הרצוי) ופרמטר אופציונלי fileName (המציין את שם הקובץ שבו יישמר ה-gate שמייצאים). import של quality gate: גם כאן קיימות שתי אפשרויות לביצוע הפעולה, הנבדלות באופן ההתחברות ל-sonar (שם משתמש וסיסמא לעומת token). בשתי האפשרויות, מקבלים בנוסף פרמטר של fileName (שם הקובץ המייצג את ה-gate שעבורו מבצעים import). פרט לעבודת השכתוב ל-groovy, הרחבנו את הפונקציונאליות של הסקריפטים, כמו: תמיכה בנושא ה-authentication, שמירה על שיוך הפרויקטים לאחר הרצת הסקריפטים (דוגמא: במקרה וב-sonar קיים פרויקט p שאליו משוייך gate בשם g, אז לאחר הרצת importGate ל-gate בשם g, בעצם מתבצעת דריסה של ה-gate המקביל בסונאר, אך השיוך בין ה-gate לפרויקט p עדיין נשמר), ועוד.

Milestones Weeks 6-7 (6.5-19.5): Start the integration with Jenkins: Define “Shared Library” and “Node”. Define 4 “Pipelines” for each operation and write the corresponding “Jenkins Files”. Week 8 (20.5-26.5): Update the groovy scripts: Add more parameters (like Sonar Server). Run behind proxy server. Better exception support. Milestones שבועות 6-7 (6.5-19.5): שילוב סקריפטי ה-groovy ביחד עם Jenkins Pipeline: במשימה זו למדנו כיצד לעבוד עם Jenkins (למשל הגדרת shared library, node, pipelines), וכן נאלצנו לשנות מעט את הסקריפטים על מנת ש-Jenkins תוכל להריץ אותם כראוי (למשל הוצאת הסקריפטים ממחלקות אל פונקציות, ועוד). שבוע 8 (20.5-26.5): הוספת פרמטרים נוספים לסקריפטים, למשל: SERVER_URL. הרצת הסקריפטים עם שרת proxy. תמיכה טובה יותר ב-exceptions: במימוש הנוכחי, לפעמים הסקריפטים נתקלים בשגיאה (כמו קבלת projectKey שאינו קיים), מדפיסים אותה ומסיימים. אנו רוצים לשנות את מנגנון זה, כך שתתאפשר זריקת חריגות, על מנת להעבירן הלאה לסקריפטים אחרים שמורצים ע"י Jenkins.

Milestones Weeks 9-11 (27.5-16.6): Continuing the integration with Jenkins. Add more parameters to support the combination with the Git (like GIT_URL and GIT_BRANCH). Fix a bug related to running Jenkins’s slave on different computers: Jenkins use two files system: One for the master and the other for the slave. For this reason, we had to change the way we read/write a file: instead of using the File object, we used Jenkins’s ‘readFile’/’writeFile’ commands. In addition, to support this solution, we moved our project from the “src” folder to a new “vars” folder. Milestones שבועות 9-11 (27.5-16.6): המשך ביצוע האינטגרציה עם ג'נקינס. נתקלנו בבעיה הבאה: ג'נקינס משתמשת בשתי מערכות קבצים, אחת עבור ה-server ושנייה עבור ה-node. כאשר הקוד נמצא בתוך תיקיית src אז ההתייחסויות לאובייקט File הן למערכת הראשונה, בעוד כל הקריאות מה-pipeline (למשל הקריאה bat) הן למערכת השנייה. בגלל בעיות טכניות, אין אפשרות לכתוב קוד ב-"src" שיכתוב קבצים, כך שצריך לשים את הקוד הזה ב-"vars" שבו ניתן להשתמש ביכולות כמו writeFile (או readFile) בשביל לכתוב ל-workplace (או לקרוא ממנו). הפתרון: הבעיה הייתה שהאובייקטים שמשמשים אותנו ליצירת הבקשות מהשרת ע"י okhttp3 הם לא serializable. גם ספריית JsonSlurper אינה serializable ולכן שינינו ל-JsonSlurperClassic. הבעיה נפתרה ע"י הוספת אנוטציית @nocps (המשמשת למניעת pause של ה-node ע"י המאסטר) מעל הפונקציות שמשתמשות בספריה הזו, ולכן היה גם צורך לבודד פעולות אלה.  כמו כן, הקוד הועבר לתיקייה vars ונוסף השימוש ב-writeFile ו-readFile.

Milestones Weeks 12-13 (17.6-30.6): Write documentation. Upload to GitHub. Create website for the project. Milestones שבועות 12-13 (17.6-30.6): כתיבת documentation (תיעוד) לפרויקט. בדיקת האפשרות של העלאת תוצרי הפרויקט ל-GittHub. יצירת אתר אינטרנט לפרויקט.

Building Blocks Project on Git Jenkins SonarQubeOverSCM repository Must include the following folders: JenkinsFiles Sonar-Gates Sonar-Profiles Jenkins Configure the shared library in Jenkins. Configure SonarQube node. Import the relevant job. Building Blocks SonarQube Server Projects Quality Profiles. Quality Gates. Dashboard. SonarQubeOverSCM repository JenkinsFiles – pipeline scripts. JenkinsJobs – includes pre-configured parameters. Vars - the Groovy scripts. SonarQube Over SCM

Workflow Configure the Shared Library and Node Import the job using CLI command “create-job” Build the job from jenkins Jenkins cloning your project and changes the relevant files Jenkins cloning the Shared Library to use the groovy scripts such as ExportProfile Enter the relevant parameters, such as your git url, sonar server url, etc. Workflow Jenkins commits the changes if needed Build succeed or failed You can see the changes in SonarQube or in your git

We learned how to use REST API, and more generally how Web Services works. We learned how to use the “OkHttp3 library” (for Groovy) to make HTTP requests from SonarQube's server (after trying other solutions that did not work well when importing files to SonarQube). We learned how to use Jenkins, and how to integrate this complex system with other projects. Conclusions סיכום: למדנו כיצד להשתמש ב-REST API, ובאופן כללי כיצד עובדים עם web services. למדנו כיצד משתמשים בספרייה okhttp (לגרובי) על מנת לבצע בקשות HTTP (וזאת אחרי שניסינו פתרונות אחרים שכשלו בעת ייבוא קבצים ל-sonar). למדנו כיצד להשתמש בג'נקינס, וכיצד לשלב מערכת מורכבת זו עם פרויקטים אחרים.

Thank you!