From 55c5e96a42b8354d42f06b545685590fce17ef81 Mon Sep 17 00:00:00 2001 From: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Date: Tue, 18 Jul 2023 08:40:37 +0100 Subject: [PATCH 01/20] Update product.yml code comments for guidance on specific variable usage (#39137) Co-authored-by: Laura Coursen --- data/variables/product.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data/variables/product.yml b/data/variables/product.yml index 846094c0f0..123ec6c62c 100644 --- a/data/variables/product.yml +++ b/data/variables/product.yml @@ -3,12 +3,13 @@ # Company +# Use this variable when referring to the company in the context of its business. For example, in licensing agreements company_short: 'GitHub' # GitHub's flagship products product_name: >- {% ifversion ghec %}GitHub Enterprise Cloud{% elsif ghes %}GitHub Enterprise Server{% elsif ghae %}GitHub AE{% else %}GitHub{% endif %} -## Use this variable when the output should always be GitHub, regardless of the product the user is using +## Use this variable when referring to the product, when the output should always be GitHub. For example, "the GitHub REST API" prodname_dotcom: 'GitHub' ## Use this variable when the output should always be GitHub Enterprise, regardless of the product the user is using From c2f5a30b9cb7effbdca5dd15e87e9ee87b43cebd Mon Sep 17 00:00:00 2001 From: kahlan88 Date: Tue, 18 Jul 2023 09:19:13 +0100 Subject: [PATCH 02/20] Update getting-started-with-github-copilot.md (#26114) Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com> --- assets/images/help/copilot/copilot-activate.png | Bin 0 -> 12231 bytes .../getting-started-with-github-copilot.md | 3 +++ 2 files changed, 3 insertions(+) create mode 100644 assets/images/help/copilot/copilot-activate.png diff --git a/assets/images/help/copilot/copilot-activate.png b/assets/images/help/copilot/copilot-activate.png new file mode 100644 index 0000000000000000000000000000000000000000..508162976d326e84b54c04d201e8c4e5368920d9 GIT binary patch literal 12231 zcmZvC1yCH%)-Nu>76|U{?j9Th1VRYzzBs{Uf#B{C9D;`679hCm;_mLSxGnPd-}l{n zzgP99s^^@V>7MRmJ>7kN5o(|0G2RisgMop;P*jjnhk=1heB*ghklyY>>IXg@_a_WbH3Q_&Ius@gJ;V5ekFX5E6(#d_-Zpjy0yCg_Vln z0%)8J<_FqJ_QCPHewFEZ7fx1F$9UULnV(-Ch1haQkLbFp)h@6u;PC<-Pk+r4;%P*O zv0)IR{*3t>^Ft-45h=-uD#ed1DF!h_ggp4c&Ub_^O&thUmL8?@4fV4;;qA{J-t@+!?EB3w47zPd||@X*X(rL6(UU#bxjE=d!q^krDMwq z1yy42hV8b@bO4QTd4=7Z;XE*EZE#-RumbQlziy>Z7mHXgGEZUcaXtq&vSTF~?E zqqgK(6WQq%hbOW@!%vqd~@OY+0V6A z^iwNm6fQAa9I_E+H!Ko5|!y{1OSye-@$UOixt zM?rsvCe|XAS`@CAf%mAoK6E(QnxO1UoNn4w%H`;$%LRewHYfa?llZ4j3{O}I0E(34`*7qTW1MJl+%p%hG$hOK4|xd5-*=7qw6XZV zR~R!az~2VRIla$?;1!Gb=8XK(_(^-lz91ABr zn5IU7J2BFnQc5OpR0^NcLP4mOd@*o_5*pt#$g~4D^?gP1Z@l3S-z93F8lDCkpA6gN zBqO{_qBWlLXnt+|Mt4y-BDQ>YDws^B*mwU)a0~t2-eVN6PjRLC%Jhm`AS^O{{ z-Ovk11m>;)WBGI1YSe8MqF`V!jufJa$R=PD-8a=61rjckk2x86fSKE8Zi??r?~LjU zUz6jRxFC5#j~TB(E0#z$l=)tEEB;cEuF$P;wGg+ktdM*Pna+aFjE_oE=8)IMJZi=+>AO<#y#WD*s|@wQ|O_WY3TI7UC9cMX}#P zzvW)a>F6wKEJ_Q>>Ewy3dR1H+?p_TW3{!mN{c87Bn;BPwmRaem`>!mG=7P)6k43ub z&%c;ve2>&^Fm8BnsBVIoRc0kqDu%ygm+6)+<#~U-DI(SZOU0D(D^{pgNSy{OSu}{d z)&4CKR?03Amv2*lu6|^@fyKz^CyZf?(T|}cZsBFO7M-RA>e?XLT=GWoHQMCNofMn! z@(@S$7qR8p7i9muvBqvFuV2vB(Y4U^sb6Y%Y~X7!sK;$6vDLDnm_D27a%FW}5Ec?1 zalJiWnR(#tc0zDL@bBHicB83`^{f(6pI7}+rT1H}%18PxiQIrgjYH2d#IRru9;Cmn zDIw>d@gn!k^9Z78kn@h&iDe~g_TMpppXr>VoHH)&(hTAcf|aJ}F_uo)6z-W01<47^ z`N`?Xl|{#r+z?MkgQ5}p%c4~YB}#0k)2~S%b-h{I)_Xf?du2>(`wCZg>Pl09fxrY{ z+aWwpBvB9Rs$Ggsluk!;jaTpk>y_?R3%)s8sBCc`ag+-_gsp-#iIqT?Ust?ts=-tb zPj^;#wXs+is;k;i`KR4My53~LeA%wL*)(eD?~>(`=91wb>C=@H1b31XVL5C$uV|du z-{fv1hJ86eBV!}m_1(N}z?s_4#KHNu`iFz$NfxuUND>5k}p^Uy;|R5seWMZt)@R)%fxvD7^Ne3iqQgK491qoIe(oyHyW zogO-y9IqMbb}MpM&$?OVz~{KQ9EY5T9H`jqW$oSY?b7azUHPo`%YwaGOPflY(3)PW z2f{^0Zh z_`xU7(pYNau`^7vSdvJxLGrn)vWq83H54G#Eu|T}VoFlmd_wH*|I6p#WMYmprMjv5 z#w4!WzNc>!jBPDr-8&o(O~6m+9_(iX^u_8D-B2zud)r(m5Sl8xDqD;uEpXM;nU42O zZqW~%M*0vyC^}eQ3n&E+H74%5YQj04yU`?)h?Nj?ZB4?&lJuWlo|@!fZAG+3#KPmv1L9%fh9a&=f$UR~{_oQP`mtNO6 zD!Eq(2BzEcH+njZw{Cce?0?y_8h>pYtohY?a2i;M2<{8*yNYb_M|~;!Bhw(G|IPO2 ze78!}xon{9X;d~rmEKcDvX*zvXia(k$q3F_VpK=$gWG9Ukka&zKO8Q4f1HJ!o1GrO zcc%!{o%AA*&bEb_;j^RSyeHo19orTU=O7UYT(gymnHm)4KXegDLM$$|t1j zr3_uD-A>-_8$eclpF=3fB)sUsyshCevXkmlGLYTAMm)XbM}IQk~RU6wZEtzQJq$nvk#Y?_Z)~i`?Vy}qMC&6Ob`Cs$T}Sb5 z@pu0(J62;9TQALs>R$=YU7#F?7ryqza|S7II|@4sZAD8J6&U6>9t8#gmKX-{je~tF z;;$ssY>jHXmg>%4DK52| zJ_n5x%@c>3mKNL=G`;sNdf0fZGO}C%_!P)9_^M*$@6}j@&sg*RiuSSBSavgykNcAq zq+#CB_LNUABVQ^Hz=-hf`~Q$qY)>$ThxqKF`@-Q67*(&bu1IJT4xGxSS3KsLLzGpW zlED_nr}ydpfNOx_F0I9P3$q+xsHN2P}H9xmj=zX;lg0D#vcnfs&Vw4Kl^ zTx70Sf}ZSfPwd0E^AB=5We1_B^B&bSufr6R|J^DR<-1V_Bm_K}>pvc9b1~+#S}!yZ z0}-fKS~$KcS2x%~Aj`+sGUGFG8- zTKOzrUivti&%Iq=iZG-@Y2fvrk%n{@%Ne(wmJ#h+#7q~T4h;R8`tQ4cgefQe4#E_5 z-Nj;{Qui zZ*p*A!!;~gQZF3+{I5B*nc!ZZ_9Zg!+V9#}Kz8Pjr+=0!7d_TN^2K^_s4v$g5_}T( zU04}3aiX;susvV0k2Ju$>>kZ~=vIO~8P=ar6K%KnH0b`*bxd5R#LGq8-fWfM%_zy= z9!wECLCM68`@|oug%6iMI$ALdyDv}vEIWV=eNJcfUmxckLq_azz=z!#IJB=fRsMVu zPn%eoW^rPFgbo!|mtGWB_J!x0Q@bv5U!O`ICgc2O6#Snq1{ymI+!rk}T}Q}&`~Ro& zHycnorPgH?HP5%5@g@Cjy)NRgw?5^6mtenkncB$f=nq}idkCHI%$Uw9Ui8|}&YaGD zxdt1(jbd*?8q41AX`7<40}FH@4aUvA@7?p=7g?90)NZ0wWb_^PS)2a2608ttLJwnj zl`(I3<~`r?$7ZDpbZT1>{8DE0%*=DE{$CS!Zea`VGN~@w zOj~|V5@_ATAd!owr9JC-eW@TK;rD^Gy)9E(*4u=x(#KoTfB&OHFhR$C-<|=)TkGoB z==EP~_^aj#R{X7@z?-V}Ggm#< z+qC*f#&r{XAE$F2#NR&5+t_w$pSisLa*NRsk#CQE-!ITU*$Q2SIFLUK%Cl?GwcCS_ zKK|R^s)evU=jw81-zBitV0ljjWkeaAn6`bWo?F{M60olHyD1Y;1s#3K*Dn!$lo3=P}fxc|$Q9P!SgK--}Tcv7BXRdk063s^Oqi;Ep_h?{dBya(}r^*JuP z>_iqn@6F^9y!uqZKk!gLg&vuyi0^;jLy@8CyM=3SNYHj5yDY0TwgA`HjqH3NKBV|5 z(Q)33s@ev{srGfuqkVeMzoE>aqKig=yGHr>&B^V({<>!{BC8aW5Fy)}ZPjnc6SQt1 zW-1vRsh>W0zq<7EqHnWf&| zQUApe!#|5}^2v*flp&zu(qhB{s8NG>!wZk6b8hQLmTsHJL6vykmwhg|&=rhQF^D#` z=*x+fgsmicF|;NQRKDog@vPg$E76fY{!efU#CgvY=u%yZ?hC29#QCh4*$Cd-I3ev- zT|7hlJMa$N9Ef+Eki;Qg<05WCW$CbzmwZ)TDtf(S5YGX71VvqE2fPFP#-_f%0NU5L z76MhCeJmNTFLxbarcch1dvE%<(!TjK5pIw&%Df^Qi67Sa&umcC?zM?#Nr!#Y=K}jqTSv}17$DtnZ<{vZ>(n?UjhXZ{`scKbPZ?KADnpZ@h z-aPHk*Fvta@hE)LyXW=Sm-*H=C)TssZhIqp?u{+0{8EJoTJ4u9jj-2mQ9i~^r7rv- z=S^nEoU5#TR-r8Skpu@GT=3~O#p}Ihoh9d&Fx>m%pLZRv&oOs*Z{Az;aHQ4ow-65# zgL^%tW%bknEHCjm35+bYV)zii-y;a!K$ckGK6{fe+iX{=1wzzOjS_vcL9cvWstWpj zx*RJzP1Q+P$|5sW?kb@7N$aCnTPnbKw`POQCIicN1HJ<3aq36AtIO)Kp+{f*LIZgu zRiyB6g4d)JZzAzvc_eR+v0!wXBF|(cIyD>}c<<^h^!OE3f*Gi9-VE9@OSpusisx6% zlYQ8miJK+%W+K~PTR|vAD;U;*@=9ywp49-P^Z=;?R$X+ss<*Jt5W8I{FmPfkMk1-w z@Rg&Oze_icqL&ZgqY3wiRycx=`M=5Qmu>fd*f{UOa%3d5UeX!VrsZ(@j#i&(=FT;^9ZFzv?aLkGmZHi@GSyfYBg)YK50Gj}AQ>lB?^XPwurv zuh37{n%r)$<9AtBDNgKVnGQV9<5t&iE^aQOK=E=Orh1xt33l{zNe3tvjEcd2LAlIH zv*;ceNC-{GGMzL9R0nwOvKR?{8)YkY|9WI8_d%gC@Az%rqLV=)BssW$obPD&I@ViX z3ZIjbG-t1dF0|b7$csHr#;r}9k$|d_GS}bY8hVRwv;ef8H}J4WNkniD+!eK^Dz-0+ z&-;@5IODwJV;){=^?i*m;2I(Ink7Z>bwOo8;@@cao(B@}I=+2nIX51}uNx6ISmncmZ9=@*D`d~A;6nkB{ATEy|7dMU=fK7Q z5k}wR`sG>nzU+sx##RsGe)r%$HXRLbP`gO5@y~@!r z#uty7O@WRF6_TZ)*QcN8aDF_&MrcUv0QU={%fugc?EViUad=}xQhmd7SMFz-X=Bc@ zF1+ro+%1moI39N6Vs}{)+wCb3D+%Z#zkY};Nx2R}d9cUgV?u!9kem=Cfh4Mm-?)DL zajua#!^x<>+G_+lI)@B8+z7&QAYy#AX7S1VA_wdQ!ta!IICWIRY&o6|d@X2!a@{Q+ zjK>BdBXhajp-Sg}JxA=_0a7;on4pyL+LnRm99mik#afyK|1QWTXdaYJ-Nbe~BrhSO z;8cH6^}9@(!#d8|7qt>`upd6^|9hOe`b>f8Tb7^#7e21vfB88YAP=#G*zwFEmO2@^iI_*3nVw(_t1qIb>X_5+UnFma6?nj6^h% znZl{fA`!hv%QK>;;FUN^yeD4H)i0^biHq}vg_|nUF=Eqoh~0FQw2o+x#@6G8C+8yi zZ2R=J%4hX>DSO2I(vhFL)L@VM2hi~4@<*eJ|L~WbDVx%|TR*xqz~22zf8h!!6)B4( z2&Os7?%=ZWUj6EVYjfE-C&E&X=urTpMTOYF(Bzw(KKq$#iOBB2kFnEl^%F<8n+u{r z{-V!^sz!UNcG!3zccy|0h6mzJzBued6na&krRhtWkug*{YG!mF1_bkGks|`41;UUt zMAU^K>x>J@0KV835r?b&AW5i8^G{s zi-1E`A$&jBe=?UX3-b17>)mw&J>52TthQ^ldZ-~_K|a1F$i42-=+%Ei$gkSOyUIV^ z`>Mt+A6@7KS7h%y8D%*0E=dT((j;*ZbD>=yw|8ijeWtRb@atcWT?BhgNgN*j(lkn- zMLL?DT?U>7TO5E#M_LF-MBmIRqg!Mtd{W)B6yZ4m^RwpYUBarUa_~>!pqFFlRp#o6 zrIIe@bD$0oC!Y`7r~YlSf3&1NS$+Ehu3JX$@fM6#%-n3}IS~1Z3!Pa})r#z;kBPr6 zLgn$51~_~-(Ui<+*@q=09P4t%n?ep1g?$zNIv8wam}!-rzpYn6BviF5#?zy2Baz;H zlLC>_;n%+BlTD7_;}Kh$&IC{I<2~@HFJQVqIfV7et_A!UfrvDEqOV*&H|<%sqi}PC zODMBsl!}a@I`5^-(z~djB!D12aGq+t@4Eei7bCs*+)+56N3Fzp94d~@(sXoEL$PD{ z%dn3FgwWHEw+Ybb=d%ZHyw21#-6y{x;O8f3gxFPD9&s^o$vbrx6-9q~KWo8U*I-~r zd)GUkZ$Q;+d@`!qZZ{1YD{Nd0&y#iHB?Ll(AAWM@(piKW1EygXoaIGipo=#@NK5RN z6wJ9Ta=3>)bLl_mQthXesYwry$S6HG4Tw1$CJycC&i~acJG{-}pb3drWRYna>pq_f zBDoJ90?V=Fl7vJ!d-SmwI``$y%Kd(*eC|tJrPBFsvmT|ISwEVkpRjcLrSx zfmFSMTPNzdWN{4>P_U2W!^3S8tVm4|?JyfShL7dCdV+Zcj`%XQ0rS3AW_wCyE7!~>`V)*yfXEyNArJy(j2j1|dIIX^h zr)Up3A9P2V!NRUctS=kVN7zyC#61xVGVW)oA@Jn*yeqi%i!0`mq;L&hAI%dd-j||< zAX71-NKAL6@86(W`gqAH?v;%?W^!ll?zZ?n|;7W@S(f0 zV!t5m>IzQcV`Uk#($?LhZ)Z>M?YdNCK*tUe_&o5Dw}iyqFLQaNc(pYsof4PVWT1pJ zXlL1gl2f`5I*^Qrf#ref1z-ja1b!o(Zu&zMtNHYxB)4XAf=^oVOy3MxDfAyTBcJw* zWkKLXBZz8eoxv4VsZ2_|Q#_B1=r&Kj`cZ{g>_>n`NZchax`nMI>-V;WG3ZC03B#iM zF8>mIY#kJqRz&f%fy^N$0S+b)j2Ug(W@PbgoK2ee(NKx4>QH*_ntzJ0I`D(Z`LdmhNJ-p=m-!$EfolKs35GW@YD-Rc5I_Ts!vvhG>> zYXYC$AngKm6t!{1LCUFE@@92=0)JbHNaG_Rz7#E(t}GJjx7T*_k;||E3!G2(wql^J`s_7o5I>WELLw=whjK=JP|&DIvjIK|{f&4n4w#}~yx3KjGvi}$&9vP$b_|g7Zo=}W zX!&6NegZL-UI@fWxcKXjPnBf7Sc0m4RDomL+1q)_h2t^w@AddQRXd#H#2Qr^yyTHc z+pVHdtSonOpOYHrvIgUGP*0Td76@J6AAOTGtXOB*JQ|neRSG3Z3xDfsyXB--smIl> zJiMIK8YjTR{USmXCFx=o*M1j`kT>cgL4fqeK0qUta`^oEcpLmVS20c>J5VNQ&@ah( zH9?kUE%W7XMuLbP=TTXhS9qM0njLNAD{7yD7-}{sxFchqAFf85Qg_LuHB@sotxL~T zxfVu7&AUC7Hz8Od%2<=`&a7w2yN~&Cfb;dhc^MzBDaN9wnp~j6dCFemQ@&0SmzSQG zRp=)@IYOb!K^nb%?@v#{5k}>_ExUR(Cis4r`F%4F<#Q_R%A^Qsl;X1d*Z1wNw~Y}{ z+lxWP%=FL=upQsnQL+$00eaEINU z6tKi9G#GAAyBD4C)3VS(D`HqXZ+O0HDM!)zaN_p2golgp&B#vu9AStfY-OZMljy`2dyQ`FTt5gw_C z5GQdxrDql$7XZ+qXU%f9xaL-V*1rRpTJ~4X)VJfw3Nmj*rVy;3qef6JW3-4X>}pSX zIBh*Hp$AHt5LKHabR`+1m%66@0Wdws(@&Brcl-ydRuqhBbq@y5F|6@}0-b2A?aYUj zeEjt5o@9lE{jp9v)u{fNHsWLh&d2(IX605|grO(QZy7pSSh$u*Y{a!6M1QN6hw4qS zF11aGUZbYUYQhB4T1Yo3cuMfb@PCWo?9LU|!*kIg`5Zpe4xkN-fkgLIU)j~fLqrjV zW{EDuD$GsKaL>IH|NOZB{8*@`)v`;^!-o+`=E%aOL*Y6h85F6PG_P{B>8d)N)`%$-FhlFMYjBKctdoC;nqJ6lcezD7f!`=bFUlOf;hG_ju+=&V$8X?1P*D!MUAC@ zy>#ORIw^)1Zj!&h4FfPeEpu+RVfEZNu^|k#Mz~FRAAhNti1cLu+pg^I6(@}Dr8qMW zI7R^!aR;r;u}f6G=2t z{bJg9Qq93)K8>~+g=7P;*i>HESL$8K?&%3mPxT^Hz2J#;@EXx$*Q+nD$EevHaoM)x z)ds$77v}EXZzSz`bU;@fnHYr$vd%9q$5yA~xW~y$atfvZlu|@pAiAf$$D9#dYd>V6 zQ%)DY3ottD?!T?7EWOA`$Qk>c)CP-E0em(`48SDY;kHhQX^UAmNi@s~|kPW%C%=TN$a(S-O6V>LqdK7G%k0d|~ z`)`Lhh6#M@tI+MIT&U^2P3+YQ>-3HXf7ylPVDaSb_Q!6%fKb$22EvUI`Z^u;TaSkG zAvm2zQU?~v=I2HA9!EdGF8E{6l(M&2y=+cnHMyJ@I)+kXD&)|`w-z-DKe_wfnQ2&x zimk#6{dH5m`Sk_bxY;VR{NXBX9zTSN06q2V-qVU!Nhub%SXKSfik`vs`E$uo3uLi5 z{SWkAmF+fFo{KCaj$bHtq>R%kCtlRg`5Qbkj=LdsXWa8Tm$6`x=<;Z(BuazZ&B5{X zmAdLQhzW1aWdBWT^@jX=VvcAb&BliZK`nyK&rfq1Lo7#v5SpK)E?C5Sa8gbvm*Pk& z{rnwdzUN&D_0PS#Qxditv@N432GjCSfBNa*G;&eXCje6QT%3&Bf*6F~*FqUOfQSqF z5S{3_32i-5S3WO#rb#LpSrlU4*zFhE0n+bM@53F$s8!*7lH)kc4ZB2%c}L;8um9@y z=D%O!CmvWKa7n-aVnq3zWm%D%Nx~>~Ztho4T?xRf1C(MUW2|vh6j;;XH$6GqudN)s z_f>xbA|)^~aMJdof&MJ<3P^HinrXFs?zuE#xgpdXX!q&PoOo}N(@k`Nz3U%tM@jrX zw1}e$SY-mYh?>PIWW9wef#HIJGe>2MxaCdShde4SQ)$bi6~>vnn4YWUaJk(?7VLa8 z8z!gaNmVSsg@mjklQ3>6{EmlvRGCbBfs8DPGP+sa6&%3tdstB8S^d*E?UwN}XP?XQ zWH?tNMtB0@aK3;sQw7Q!8(dyq6Q*^&oz;j)O@&*mb3Ov37t8It-zWg%bVC*!ms-qO zL(caM=X%|zKRrsUVI#0yAheio?Hu9K0zCHw?&X?ZoDL7Bf9p{;H)bRgmvM1yJA=f?F6@^~Ae#a3nA*DMST;cy)LY>-`&lXWd<{K8M_g6M_-Hjv^>s#`g*s2Z zZEX31!Fhi(>@zZf%X?8N@hJt8W9B3*kDlUH%*Y|n;q?y+FhkK2>v~xGnl_pQnjV`p z%-YbVmSn3%IkyP14q@j05v(cNL3GK0UIcsdK?jT=Q&G89<=SAez#27%m%GxoQ8lhY z_6WqmtYY$N$q$R~Eq@O67FR`gch$An#n1u*slEre zCq;Zj?*eGw>nuf6XNxvtPl%s~aep!<6p7wtdM*bpT~H-!&rF8l^!_r->GfB+-ddB3 z{(PF#SNxqF$+J;5&&gRKOLvY45`#r1NnRB$OKWew-j9({RlPHa#lKd7Sk8a>pl`2U zEItsJ-~JdZ-t)WHO<{EOvn6D8g79y{u*ONfW>#&=|Pot@%}XWpQ&fsb-(0yu zCHip5??x@a`J-0^3KA_&i6#?as!?#unC6UT%u_z66z)#-_khyO>adWOPG!)Aq~9Ww zNTZ6^q6Xewt5F7u2n>*XS2FzO80WM|bqkM8z7sBh1J{0w^AZy@NpG5oLynw|3QAz) zP3yVLx)YO%m(})d)J37}P!0xI`hkD|9Z^|MUo*-_wj_7fob!aGNhe>oqx~Am-o&p5;uxsE~m1V?UM6Mi@A58jzwrpC0>Im zdWHZ;@H>*uGcIwuRh6QOPU6zAi39P+%ISzL;=@nBy7Fj3~BdrEER<*Zod2u z*r&CE=ZAbELqf}D!v=wE-Z)!VvFi@PuOu2$;wB#+puf*1U6)KmS${RuqDZd!EA!@H za07sjcPlRA_E~Xt4X^wn)9%w1MXwB{B@0;y1)O2%M@IM|!E}NCC}z#4^HLm-$Wwh!;R&ugl1^1_;vD`Moz;}^~Lj2Nl%?JwHqz*|a7?(q* z(Y`J6pp5F6J169WM*jZJ}!TJ)XjrOt~pl@=n2*n zRniH@!(}rnRveD{#vt@bM7+N1{yoE&=dcEk#K#zD^aX~}DfV8t6Mj^@^JQmaeNW5P z8UY^8=)xv@9tEL9(!1^LdM|RIwGUI6cBSvEojT5AEL`L|Ev$dVv?TO&POlGyN!l*b zarg7JgK!;xUO-3j-a{|`TSN^bjtz?~bJ#B5(OTiny5YhK0=2h@@tp^9W{?+>XGR3kegMQ0QJ(cQhjB z;0v~9pblz60)%!T1SOH#CUBo;;AdJdI4jj-a?0-J^cTsjg0d{YktGdCIQr|`{{{xw zMSZaTUGf=eFoiC%ob%u+cR987qEh=BHKdmzeM@^6RNlr4V*L~4G^MK3ml z_jMx_y;+XfRaop^#7^c b`3g$~IzSrR+++I(-l8b`Nv2ZDIPm`f(8t$< literal 0 HcmV?d00001 diff --git a/content/copilot/getting-started-with-github-copilot.md b/content/copilot/getting-started-with-github-copilot.md index 7d63416cc2..f397b8c43d 100644 --- a/content/copilot/getting-started-with-github-copilot.md +++ b/content/copilot/getting-started-with-github-copilot.md @@ -266,6 +266,9 @@ To use {% data variables.product.prodname_copilot %}, you must first install the 1. If you have not previously authorized {% data variables.product.prodname_vscode %} in your {% data variables.product.prodname_dotcom %} account, you will be prompted to sign in to {% data variables.product.prodname_dotcom %} in {% data variables.product.prodname_vscode %}. - If you have previously authorized {% data variables.product.prodname_vscode %} for your account on {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_copilot %} will be automatically authorized. + - If you don't get the prompt to authorize, click the bell icon in the bottom panel of the {% data variables.product.prodname_vscode %} window. + + ![Screenshot of the {% data variables.product.prodname_vscode %} task bar with {% data variables.product.prodname_copilot %} icons. The bell icon is outlined in dark orange.](/assets/images/help/copilot/copilot-activate.png) 1. In your browser, {% data variables.product.prodname_dotcom %} will request the necessary permissions for {% data variables.product.prodname_copilot %}. To approve these permissions, click **Authorize {% data variables.product.prodname_vscode %}**. 1. To confirm the authentication, in {% data variables.product.prodname_vscode %}, in the "{% data variables.product.prodname_vscode %}" dialog box, click **Open**. From 2e28162aa947868b836be55e0e35217b2734d654 Mon Sep 17 00:00:00 2001 From: Eric Sorenson Date: Tue, 18 Jul 2023 01:35:38 -0700 Subject: [PATCH 03/20] Removes an inaccurate phrase from org archiving docs (#38995) Co-authored-by: Eric Sorenson Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com> --- .../managing-organization-settings/archiving-an-organization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/organizations/managing-organization-settings/archiving-an-organization.md b/content/organizations/managing-organization-settings/archiving-an-organization.md index d27e1a30d8..40bf199728 100644 --- a/content/organizations/managing-organization-settings/archiving-an-organization.md +++ b/content/organizations/managing-organization-settings/archiving-an-organization.md @@ -20,7 +20,7 @@ topics: ## About archiving your organization -When you archive an organization, all repositories in the organization will be archived as well. This means that all issues, pull requests, and comments will be read-only. A key will be set in the API to indicate the organization has been archived. Many actions that can be performed in an organization will be disabled, including creating new repositories and deleting existing repositories. You will still be able to transfer repositories out of the organization, for example, to give a project to a user who is taking over active maintenance. +When you archive an organization, all repositories in the organization will be archived as well. This means that all issues, pull requests, and comments will be read-only. A key will be set in the API to indicate the organization has been archived. Many actions that can be performed in an organization will be disabled, including creating new repositories. You will still be able to delete repositories. You will also still be able to transfer repositories out of the organization, for example, to give a project to a user who is taking over active maintenance. When an organization is archived, visitors to the organization's profile will see a banner indicating that it has been archived. The repositories in the organization will now have a badge and a banner on their home page indicating that they are read-only. From 4ccb9302c4696bb4a5b42ad170b3749e7099ae5b Mon Sep 17 00:00:00 2001 From: Sophie <29382425+sophietheking@users.noreply.github.com> Date: Tue, 18 Jul 2023 11:07:55 +0200 Subject: [PATCH 04/20] Delete sentence from "Creating a tasklist" (#39214) --- .../creating-a-tasklist.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/issues/managing-your-tasks-with-tasklists/creating-a-tasklist.md b/content/issues/managing-your-tasks-with-tasklists/creating-a-tasklist.md index 859d92adb2..48373f85d1 100644 --- a/content/issues/managing-your-tasks-with-tasklists/creating-a-tasklist.md +++ b/content/issues/managing-your-tasks-with-tasklists/creating-a-tasklist.md @@ -20,14 +20,14 @@ You can use the **Add tasklist** button to quickly add a tasklist to your issue. 1. Navigate to the issue you want to contain your new tasklist. You can also create a new issue. 1. At the bottom of the issue description, click {% octicon "plus" aria-hidden="true" %} **Add tasklist**. - + ![Screenshot of an issue. The "Add tasklist" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-tasklist-ui.png) - + 1. You can then add issues, pull requests, and draft tasks to your new tasklist. For more information, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist)." ## Creating tasklists with Markdown -You can create tasklists using Markdown in the issue description (the opening comment of an issue). You can include links to issues and pull requests or create draft issues. +You can create tasklists using Markdown in the issue description (the opening comment of an issue). You can include links to issues and pull requests or create draft issues. You can add a tasklist by copying the Markdown below into your issue description: @@ -47,7 +47,7 @@ Once you have started editing your tasklist Markdown, you can add new tasks by p * A draft task. Draft tasks are text that can later be converted into issues. * The full link to an issue or pull request or, if the issue or pull request is in the same repository as your tasklist, you can use the #ISSUE-NUMBER shorthand syntax. For example, `https://github.com/octo-org/octo-repo/issues/45` or `#45`. -* If an issue or pull request is in the same repository +* If an issue or pull request is in the same repository If you add a draft task, it must meet these requirements: @@ -58,7 +58,7 @@ Your tasklist will be rendered by {% data variables.product.product_name %} when ## Changing the title of a tasklist -When you create a new tasklist, the default title is "Tasks." You can modify the title by clicking {% octicon "pencil" aria-hidden="true" %} **Rename** in the tasklist's context menu or by editing the issue's markdown. +When you create a new tasklist, the default title is "Tasks." You can modify the title by clicking {% octicon "pencil" aria-hidden="true" %} **Rename** in the tasklist's context menu or by editing the issue's markdown. 1. In the top-right of the issue body, select {% octicon "kebab-horizontal" aria-label="Show options" %} and click **Edit**. @@ -83,5 +83,3 @@ When you copy your tasklist using the "Copy Markdown" option, {% data variables. ![Screenshot of a tasklist. The tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/projects-v2/tasklist-kebab.png) 1. In the menu, click **Copy markdown**. - -Your tasklist will be copied to your clipboard as a From 802d15e11b44e4ee4cfcec76de632982c77a91b7 Mon Sep 17 00:00:00 2001 From: hubwriter Date: Tue, 18 Jul 2023 10:52:51 +0100 Subject: [PATCH 05/20] Update repository-references.js --- src/observability/tests/repository-references.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/observability/tests/repository-references.js b/src/observability/tests/repository-references.js index 13b35bfe83..fff2359175 100644 --- a/src/observability/tests/repository-references.js +++ b/src/observability/tests/repository-references.js @@ -47,6 +47,7 @@ const PUBLIC_REPOS = new Set([ 'help-docs-archived-enterprise-versions', 'hubot', 'insights-releases', + 'issue-metrics', 'janky', 'linguist', 'localization-support', From d140cde17787065292d551a97c38d40a64eae1bd Mon Sep 17 00:00:00 2001 From: hubwriter Date: Tue, 18 Jul 2023 12:17:43 +0100 Subject: [PATCH 06/20] Actions: Add repo links to action creation articles as examples (#39142) Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> --- .../creating-actions/creating-a-composite-action.md | 8 ++++++++ .../creating-a-docker-container-action.md | 8 ++++++++ .../creating-actions/creating-a-javascript-action.md | 7 +++++++ 3 files changed, 23 insertions(+) diff --git a/content/actions/creating-actions/creating-a-composite-action.md b/content/actions/creating-actions/creating-a-composite-action.md index d25a7c5e70..4fd4f17ee7 100644 --- a/content/actions/creating-actions/creating-a-composite-action.md +++ b/content/actions/creating-actions/creating-a-composite-action.md @@ -142,3 +142,11 @@ jobs: ``` From your repository, click the **Actions** tab, and select the latest workflow run. The output should include: "Hello Mona the Octocat", the result of the "Goodbye" script, and a random number. + +## Example composite actions on {% data variables.product.prodname_dotcom_the_website %} + +You can find many examples of composite actions on {% data variables.product.prodname_dotcom_the_website %}. + +- [microsoft/action-python](https://github.com/microsoft/action-python) +- [microsoft/gpt-review](https://github.com/microsoft/gpt-review) +- [tailscale/github-action](https://github.com/tailscale/github-action) \ No newline at end of file diff --git a/content/actions/creating-actions/creating-a-docker-container-action.md b/content/actions/creating-actions/creating-a-docker-container-action.md index 796b81e96c..47d97daba6 100644 --- a/content/actions/creating-actions/creating-a-docker-container-action.md +++ b/content/actions/creating-actions/creating-a-docker-container-action.md @@ -259,3 +259,11 @@ jobs: ``` {% data reusables.actions.test-private-action-example %} + +## Example Docker container actions on {% data variables.product.prodname_dotcom_the_website %} + +You can find many examples of Docker container actions on {% data variables.product.prodname_dotcom_the_website %}. + +- [github/issue-metrics](https://github.com/github/issue-metrics) +- [microsoft/infersharpaction](https://github.com/microsoft/infersharpaction) +- [microsoft/ps-docs](https://github.com/microsoft/ps-docs) \ No newline at end of file diff --git a/content/actions/creating-actions/creating-a-javascript-action.md b/content/actions/creating-actions/creating-a-javascript-action.md index 8e85411fd2..2f2b5722a5 100644 --- a/content/actions/creating-actions/creating-a-javascript-action.md +++ b/content/actions/creating-actions/creating-a-javascript-action.md @@ -285,3 +285,10 @@ jobs: - [`javascript-action` template repository](https://github.com/actions/javascript-action) - [`typescript-action` template repository](https://github.com/actions/typescript-action) + +## Example JavaScript actions on {% data variables.product.prodname_dotcom_the_website %} + +You can find many examples of JavaScript actions on {% data variables.product.prodname_dotcom_the_website %}. + +- [DevExpress/testcafe-action](https://github.com/DevExpress/testcafe-action) +- [duckduckgo/privacy-configuration](https://github.com/duckduckgo/privacy-configuration) \ No newline at end of file From 4ae746bb3b6e468f4d6a602d52d6357a4cd98408 Mon Sep 17 00:00:00 2001 From: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Date: Tue, 18 Jul 2023 13:31:47 +0100 Subject: [PATCH 07/20] Adds content to 'Out of disk or memory' troubleshooting article (#38917) --- .../out-of-disk-or-memory.md | 17 ++++++++++++++--- .../results-differ-between-platforms.md | 2 +- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md b/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md index d280e66689..25bd1d22f8 100644 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md +++ b/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md @@ -1,7 +1,7 @@ --- title: 'Error: "Out of disk" or Error: "Out of memory"' shortTitle: 'Out of disk or memory' -intro: 'If you see one of these errors, try these steps.' +intro: 'If you see one of these errors with {% data variables.product.prodname_actions %}, {% ifversion ghes %}try reviewing the specifications of your self-hosted runners.{% else %}you can try alternative runners.{% endif %}' allowTitleToDifferFromFilename: true product: '{% data reusables.gated-features.code-scanning %}' versions: @@ -15,6 +15,17 @@ versions: {% data reusables.code-scanning.beta %} -On very large projects, {% data variables.product.prodname_codeql %}, you may see `Error: "Out of disk"` or `Error: "Out of memory"` on the runner. +{% ifversion ghes %} +On very large projects, you may see `Error: "Out of disk"` or `Error: "Out of memory"` on self-hosted runners when running {% data variables.product.prodname_codeql %}. In this case, you may need to increase the memory or disk space available on your runners. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)." -{% ifversion fpt or ghec %}If you encounter this issue on a hosted {% data variables.product.prodname_actions %} runner, contact {% data variables.contact.contact_support %} so that we can investigate the problem. {% else %}If you encounter this issue, try increasing the memory on the runner.{% endif %} \ No newline at end of file +You can also review the recommended hardware resources for running {% data variables.product.prodname_codeql %} to make sure your self-hosted runners meet those requirements. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/recommended-hardware-resources-for-running-codeql)." + +{% else %} +## Use self-hosted runners + +Self-hosted runners offer more control of hardware, operating system, and software tools than {% data variables.product.company_short %}-hosted runners can provide. For more information, see "[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)." You can review the recommended hardware resources for running {% data variables.product.prodname_codeql %} to make sure your self-hosted runners meet those requirements. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/recommended-hardware-resources-for-running-codeql)." + +{% ifversion actions-hosted-runners %} +## Use larger runners +You can use larger runners, which are {% data variables.product.company_short %}-hosted runners with more RAM, CPU, and disk space than standard runners. These runners have the runner application and other tools preinstalled. For more information about larger runners and the specifications you can use with them, see "[AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners)."{% endif %} +{% endif %} \ No newline at end of file diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/results-differ-between-platforms.md b/content/code-security/code-scanning/troubleshooting-code-scanning/results-differ-between-platforms.md index 0274a052a5..f3608102ec 100644 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/results-differ-between-platforms.md +++ b/content/code-security/code-scanning/troubleshooting-code-scanning/results-differ-between-platforms.md @@ -12,4 +12,4 @@ versions: If you are analyzing code written in Python, you may see different results depending on whether you run the {% data variables.code-scanning.codeql_workflow %} on Linux, macOS, or Windows. -On GitHub-hosted runners that use Linux, the {% data variables.code-scanning.codeql_workflow %} tries to install and analyze Python dependencies, which could lead to more results. To disable the auto-install, add `setup-python-dependencies: false` to the "Initialize CodeQL" step of the workflow. For more information about configuring the analysis of Python dependencies, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning)." +On {% data variables.product.company_short %}-hosted runners that use Linux, the {% data variables.code-scanning.codeql_workflow %} tries to install and analyze Python dependencies, which could lead to more results. To disable the auto-install, add `setup-python-dependencies: false` to the "Initialize CodeQL" step of the workflow. For more information about configuring the analysis of Python dependencies, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning)." From c8931f73f2d65d99920217a8e29d9d411640a92b Mon Sep 17 00:00:00 2001 From: Jurre Date: Tue, 18 Jul 2023 14:42:24 +0200 Subject: [PATCH 08/20] [Dependabot] Vendoring option is supported for Security Updates (#39162) Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> --- data/reusables/dependabot/configuration-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/reusables/dependabot/configuration-options.md b/data/reusables/dependabot/configuration-options.md index 32abbc42cd..1020d02672 100644 --- a/data/reusables/dependabot/configuration-options.md +++ b/data/reusables/dependabot/configuration-options.md @@ -21,5 +21,5 @@ | [`schedule.time`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#scheduletime) | {% octicon "x" aria-label="Not supported" %}| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Time of day to check for updates (hh:mm) | | [`schedule.timezone`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#scheduletimezone) | {% octicon "x" aria-label="Not supported" %}| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Timezone for time of day (zone identifier) | | [`target-branch`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch) | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Branch to create pull requests against | -| [`vendor`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#vendor) | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | Update vendored or cached dependencies | +| [`vendor`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#vendor) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | Update vendored or cached dependencies | | [`versioning-strategy`](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#versioning-strategy) | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | How to update manifest version requirements | From a03aff9281f27b49144d68d70b51af85b3e57fb2 Mon Sep 17 00:00:00 2001 From: docs-bot <77750099+docs-bot@users.noreply.github.com> Date: Tue, 18 Jul 2023 06:37:03 -0700 Subject: [PATCH 09/20] Update OpenAPI Description (#39226) --- .../fine-grained-pat-permissions.json | 13 ++- .../data/fpt-2022-11-28/fine-grained-pat.json | 10 +- .../server-to-server-permissions.json | 15 ++- .../fpt-2022-11-28/server-to-server-rest.json | 10 +- .../fpt-2022-11-28/user-to-server-rest.json | 10 +- .../fine-grained-pat-permissions.json | 13 ++- .../ghec-2022-11-28/fine-grained-pat.json | 10 +- .../server-to-server-permissions.json | 15 ++- .../server-to-server-rest.json | 10 +- .../ghec-2022-11-28/user-to-server-rest.json | 10 +- src/github-apps/lib/config.json | 2 +- src/rest/data/fpt-2022-11-28/schema.json | 93 ++++++++++++++++++- src/rest/data/ghec-2022-11-28/schema.json | 93 ++++++++++++++++++- src/rest/data/ghes-3.6/schema.json | 2 +- src/rest/data/ghes-3.7/schema.json | 2 +- src/rest/data/ghes-3.8/schema.json | 2 +- src/rest/data/ghes-3.9-2022-11-28/schema.json | 2 +- src/rest/lib/config.json | 2 +- src/webhooks/lib/config.json | 2 +- 19 files changed, 285 insertions(+), 31 deletions(-) diff --git a/src/github-apps/data/fpt-2022-11-28/fine-grained-pat-permissions.json b/src/github-apps/data/fpt-2022-11-28/fine-grained-pat-permissions.json index 330246d1c2..fa4e992dec 100644 --- a/src/github-apps/data/fpt-2022-11-28/fine-grained-pat-permissions.json +++ b/src/github-apps/data/fpt-2022-11-28/fine-grained-pat-permissions.json @@ -363,7 +363,7 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "additional-permissions": [], "access": "write" }, @@ -372,7 +372,7 @@ "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "additional-permissions": [], "access": "write" }, @@ -2182,6 +2182,15 @@ "additional-permissions": [], "access": "write" }, + { + "category": "repos", + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "additional-permissions": [], + "access": "write" + }, { "category": "repos", "slug": "enable-automated-security-fixes", diff --git a/src/github-apps/data/fpt-2022-11-28/fine-grained-pat.json b/src/github-apps/data/fpt-2022-11-28/fine-grained-pat.json index 6938ef834b..41886981fc 100644 --- a/src/github-apps/data/fpt-2022-11-28/fine-grained-pat.json +++ b/src/github-apps/data/fpt-2022-11-28/fine-grained-pat.json @@ -1754,13 +1754,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -3770,6 +3770,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json b/src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json index 473d4551a5..e85aecc227 100644 --- a/src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json +++ b/src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json @@ -437,7 +437,7 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "access": "write", "user-to-server": true, "server-to-server": true, @@ -448,7 +448,7 @@ "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "access": "write", "user-to-server": true, "server-to-server": true, @@ -2730,6 +2730,17 @@ "server-to-server": true, "additional-permissions": [] }, + { + "category": "repos", + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "access": "write", + "user-to-server": true, + "server-to-server": true, + "additional-permissions": [] + }, { "category": "repos", "slug": "enable-automated-security-fixes", diff --git a/src/github-apps/data/fpt-2022-11-28/server-to-server-rest.json b/src/github-apps/data/fpt-2022-11-28/server-to-server-rest.json index e4783311cb..c32622a6bb 100644 --- a/src/github-apps/data/fpt-2022-11-28/server-to-server-rest.json +++ b/src/github-apps/data/fpt-2022-11-28/server-to-server-rest.json @@ -1538,13 +1538,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -3406,6 +3406,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/data/fpt-2022-11-28/user-to-server-rest.json b/src/github-apps/data/fpt-2022-11-28/user-to-server-rest.json index ff1abcb66b..0f1efc67ff 100644 --- a/src/github-apps/data/fpt-2022-11-28/user-to-server-rest.json +++ b/src/github-apps/data/fpt-2022-11-28/user-to-server-rest.json @@ -1772,13 +1772,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -3836,6 +3836,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/data/ghec-2022-11-28/fine-grained-pat-permissions.json b/src/github-apps/data/ghec-2022-11-28/fine-grained-pat-permissions.json index ddd64d71e7..650e8b0513 100644 --- a/src/github-apps/data/ghec-2022-11-28/fine-grained-pat-permissions.json +++ b/src/github-apps/data/ghec-2022-11-28/fine-grained-pat-permissions.json @@ -660,7 +660,7 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "additional-permissions": [], "access": "write" }, @@ -669,7 +669,7 @@ "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "additional-permissions": [], "access": "write" }, @@ -2741,6 +2741,15 @@ "additional-permissions": [], "access": "write" }, + { + "category": "repos", + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "additional-permissions": [], + "access": "write" + }, { "category": "repos", "slug": "enable-automated-security-fixes", diff --git a/src/github-apps/data/ghec-2022-11-28/fine-grained-pat.json b/src/github-apps/data/ghec-2022-11-28/fine-grained-pat.json index 3268ee52b8..199c7efbb1 100644 --- a/src/github-apps/data/ghec-2022-11-28/fine-grained-pat.json +++ b/src/github-apps/data/ghec-2022-11-28/fine-grained-pat.json @@ -1870,13 +1870,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -4020,6 +4020,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/data/ghec-2022-11-28/server-to-server-permissions.json b/src/github-apps/data/ghec-2022-11-28/server-to-server-permissions.json index 875cb46aea..cbcc649795 100644 --- a/src/github-apps/data/ghec-2022-11-28/server-to-server-permissions.json +++ b/src/github-apps/data/ghec-2022-11-28/server-to-server-permissions.json @@ -809,7 +809,7 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "access": "write", "user-to-server": true, "server-to-server": true, @@ -820,7 +820,7 @@ "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "access": "write", "user-to-server": true, "server-to-server": true, @@ -3420,6 +3420,17 @@ "server-to-server": true, "additional-permissions": [] }, + { + "category": "repos", + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "access": "write", + "user-to-server": true, + "server-to-server": true, + "additional-permissions": [] + }, { "category": "repos", "slug": "enable-automated-security-fixes", diff --git a/src/github-apps/data/ghec-2022-11-28/server-to-server-rest.json b/src/github-apps/data/ghec-2022-11-28/server-to-server-rest.json index c4b3fcfb45..db7732cbcc 100644 --- a/src/github-apps/data/ghec-2022-11-28/server-to-server-rest.json +++ b/src/github-apps/data/ghec-2022-11-28/server-to-server-rest.json @@ -1654,13 +1654,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -3656,6 +3656,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/data/ghec-2022-11-28/user-to-server-rest.json b/src/github-apps/data/ghec-2022-11-28/user-to-server-rest.json index 3a2e5b44b3..d3de62f4c0 100644 --- a/src/github-apps/data/ghec-2022-11-28/user-to-server-rest.json +++ b/src/github-apps/data/ghec-2022-11-28/user-to-server-rest.json @@ -1888,13 +1888,13 @@ "slug": "get-copilot-for-business-seat-information-and-settings-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing" + "requestPath": "/orgs/{org}/copilot/billing" }, { "slug": "list-all-copilot-for-business-seat-assignments-for-an-organization", "subcategory": "copilot-for-business", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats" + "requestPath": "/orgs/{org}/copilot/billing/seats" }, { "slug": "add-teams-to-the-copilot-for-business-subscription-for-an-organization", @@ -4086,6 +4086,12 @@ "verb": "delete", "requestPath": "/repos/{owner}/{repo}/autolinks/{autolink_id}" }, + { + "slug": "check-if-automated-security-fixes-are-enabled-for-a-repository", + "subcategory": "repos", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes" + }, { "slug": "enable-automated-security-fixes", "subcategory": "repos", diff --git a/src/github-apps/lib/config.json b/src/github-apps/lib/config.json index 4af9a98a24..a8bc76f3aa 100644 --- a/src/github-apps/lib/config.json +++ b/src/github-apps/lib/config.json @@ -60,5 +60,5 @@ "2022-11-28" ] }, - "sha": "19833171fa53a9a674f247f795f0cf44a65a05e4" + "sha": "741cbd72628a3a80f15ba2321e18a2237b69b803" } \ No newline at end of file diff --git a/src/rest/data/fpt-2022-11-28/schema.json b/src/rest/data/fpt-2022-11-28/schema.json index 94ecf63f82..41b8a69195 100644 --- a/src/rest/data/fpt-2022-11-28/schema.json +++ b/src/rest/data/fpt-2022-11-28/schema.json @@ -213729,7 +213729,7 @@ { "serverUrl": "https://api.github.com", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "title": "Get Copilot for Business seat information and settings for an organization", "category": "copilot", "subcategory": "copilot-for-business", @@ -213866,7 +213866,7 @@ { "serverUrl": "https://api.github.com", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "title": "List all Copilot for Business seat assignments for an organization", "category": "copilot", "subcategory": "copilot-for-business", @@ -458725,6 +458725,95 @@ } ] }, + { + "serverUrl": "https://api.github.com", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "title": "Check if automated security fixes are enabled for a repository", + "category": "repos", + "subcategory": "repos", + "parameters": [ + { + "name": "owner", + "description": "

The account owner of the repository. The name is not case sensitive.

", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "

The name of the repository without the .git extension. The name is not case sensitive.

", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "bodyParameters": [], + "enabledForGitHubApps": true, + "codeExamples": [ + { + "key": "default", + "request": { + "description": "Example", + "acceptHeader": "application/vnd.github.v3+json", + "parameters": { + "owner": "OWNER", + "repo": "REPO" + } + }, + "response": { + "statusCode": "200", + "contentType": "application/json", + "description": "

Response if dependabot is enabled

", + "example": { + "enabled": true, + "paused": false + }, + "schema": { + "title": "Check Automated Security Fixes", + "description": "Check Automated Security Fixes", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether automated security fixes are enabled for the repository.", + "examples": [ + true + ] + }, + "paused": { + "type": "boolean", + "description": "Whether automated security fixes are paused for the repository.", + "examples": [ + false + ] + } + }, + "required": [ + "enabled", + "paused" + ] + } + } + } + ], + "previews": [], + "descriptionHTML": "

Shows whether automated security fixes are enabled, disabled or paused for a repository. The authenticated user must have admin read access to the repository. For more information, see \"Configuring automated security fixes\".

", + "statusCodes": [ + { + "httpStatusCode": "200", + "description": "

Response if dependabot is enabled

" + }, + { + "httpStatusCode": "404", + "description": "

Not Found if dependabot is not enabled for the repository

" + } + ] + }, { "serverUrl": "https://api.github.com", "verb": "put", diff --git a/src/rest/data/ghec-2022-11-28/schema.json b/src/rest/data/ghec-2022-11-28/schema.json index c8a28d8ab9..a4bc171c30 100644 --- a/src/rest/data/ghec-2022-11-28/schema.json +++ b/src/rest/data/ghec-2022-11-28/schema.json @@ -225428,7 +225428,7 @@ { "serverUrl": "https://api.github.com", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing", + "requestPath": "/orgs/{org}/copilot/billing", "title": "Get Copilot for Business seat information and settings for an organization", "category": "copilot", "subcategory": "copilot-for-business", @@ -225565,7 +225565,7 @@ { "serverUrl": "https://api.github.com", "verb": "get", - "requestPath": "/organizations/{org}/copilot/billing/seats", + "requestPath": "/orgs/{org}/copilot/billing/seats", "title": "List all Copilot for Business seat assignments for an organization", "category": "copilot", "subcategory": "copilot-for-business", @@ -475772,6 +475772,95 @@ } ] }, + { + "serverUrl": "https://api.github.com", + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/automated-security-fixes", + "title": "Check if automated security fixes are enabled for a repository", + "category": "repos", + "subcategory": "repos", + "parameters": [ + { + "name": "owner", + "description": "

The account owner of the repository. The name is not case sensitive.

", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "

The name of the repository without the .git extension. The name is not case sensitive.

", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "bodyParameters": [], + "enabledForGitHubApps": true, + "codeExamples": [ + { + "key": "default", + "request": { + "description": "Example", + "acceptHeader": "application/vnd.github.v3+json", + "parameters": { + "owner": "OWNER", + "repo": "REPO" + } + }, + "response": { + "statusCode": "200", + "contentType": "application/json", + "description": "

Response if dependabot is enabled

", + "example": { + "enabled": true, + "paused": false + }, + "schema": { + "title": "Check Automated Security Fixes", + "description": "Check Automated Security Fixes", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether automated security fixes are enabled for the repository.", + "examples": [ + true + ] + }, + "paused": { + "type": "boolean", + "description": "Whether automated security fixes are paused for the repository.", + "examples": [ + false + ] + } + }, + "required": [ + "enabled", + "paused" + ] + } + } + } + ], + "previews": [], + "descriptionHTML": "

Shows whether automated security fixes are enabled, disabled or paused for a repository. The authenticated user must have admin read access to the repository. For more information, see \"Configuring automated security fixes\".

", + "statusCodes": [ + { + "httpStatusCode": "200", + "description": "

Response if dependabot is enabled

" + }, + { + "httpStatusCode": "404", + "description": "

Not Found if dependabot is not enabled for the repository

" + } + ] + }, { "serverUrl": "https://api.github.com", "verb": "put", diff --git a/src/rest/data/ghes-3.6/schema.json b/src/rest/data/ghes-3.6/schema.json index ce5905a17e..21499549dd 100644 --- a/src/rest/data/ghes-3.6/schema.json +++ b/src/rest/data/ghes-3.6/schema.json @@ -306018,7 +306018,7 @@ } ], "previews": [], - "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", + "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", "statusCodes": [ { "httpStatusCode": "200", diff --git a/src/rest/data/ghes-3.7/schema.json b/src/rest/data/ghes-3.7/schema.json index 2a7372219a..97c744059c 100644 --- a/src/rest/data/ghes-3.7/schema.json +++ b/src/rest/data/ghes-3.7/schema.json @@ -308989,7 +308989,7 @@ } ], "previews": [], - "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", + "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", "statusCodes": [ { "httpStatusCode": "200", diff --git a/src/rest/data/ghes-3.8/schema.json b/src/rest/data/ghes-3.8/schema.json index 96c2fa2e97..92be4900c3 100644 --- a/src/rest/data/ghes-3.8/schema.json +++ b/src/rest/data/ghes-3.8/schema.json @@ -319026,7 +319026,7 @@ } ], "previews": [], - "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", + "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", "statusCodes": [ { "httpStatusCode": "200", diff --git a/src/rest/data/ghes-3.9-2022-11-28/schema.json b/src/rest/data/ghes-3.9-2022-11-28/schema.json index 31cfdb82cc..0b07c34542 100644 --- a/src/rest/data/ghes-3.9-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.9-2022-11-28/schema.json @@ -321810,7 +321810,7 @@ } ], "previews": [], - "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", + "descriptionHTML": "

Deprecation Notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on the application authorizations settings screen within GitHub. The scopes returned are the union of scopes authorized for the application. For example, if an application has one token with repo scope and another token with user scope, the grant will return [\"repo\", \"user\"].

", "statusCodes": [ { "httpStatusCode": "200", diff --git a/src/rest/lib/config.json b/src/rest/lib/config.json index 90e6ad5599..1ebe128a03 100644 --- a/src/rest/lib/config.json +++ b/src/rest/lib/config.json @@ -33,5 +33,5 @@ ] } }, - "sha": "19833171fa53a9a674f247f795f0cf44a65a05e4" + "sha": "741cbd72628a3a80f15ba2321e18a2237b69b803" } \ No newline at end of file diff --git a/src/webhooks/lib/config.json b/src/webhooks/lib/config.json index afc486647d..59b1fb5372 100644 --- a/src/webhooks/lib/config.json +++ b/src/webhooks/lib/config.json @@ -1,3 +1,3 @@ { - "sha": "19833171fa53a9a674f247f795f0cf44a65a05e4" + "sha": "741cbd72628a3a80f15ba2321e18a2237b69b803" } \ No newline at end of file From 5db51023f9a0f0e049e160cfd4ecd888d310abe0 Mon Sep 17 00:00:00 2001 From: Sarita Iyer <66540150+saritai@users.noreply.github.com> Date: Tue, 18 Jul 2023 09:58:29 -0400 Subject: [PATCH 10/20] Refactor of CodeQL CLI docs into "Getting started" and "Advanced" map topics (#38718) Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Co-authored-by: Felicity Chapman --- .../about-code-scanning-with-codeql.md | 2 +- .../built-in-codeql-query-suites.md | 4 +- .../customizing-code-scanning.md | 4 +- .../sarif-support-for-code-scanning.md | 2 +- .../unnecessary-step-found.md | 2 +- ...onfiguring-codeql-cli-in-your-ci-system.md | 34 +-- ...installing-codeql-cli-in-your-ci-system.md | 2 +- .../codeql-cli-manual/database-init.md | 2 +- .../codeql-cli/codeql-cli-reference/index.md | 20 -- .../about-the-codeql-cli.md | 81 +++++++ ...nalyzing-your-code-with-codeql-queries.md} | 179 ++++++--------- .../customizing-analysis-with-codeql-packs.md | 180 +++++++++++++++ .../index.md | 25 ++ ...reparing-your-code-for-codeql-analysis.md} | 142 ++++++++---- .../setting-up-the-codeql-cli.md} | 89 +++++--- ...ading-codeql-analysis-results-to-github.md | 112 +++++++++ content/code-security/codeql-cli/index.md | 4 +- .../about-codeql-workspaces.md | 7 +- .../creating-and-working-with-codeql-packs.md | 17 +- .../creating-codeql-query-suites.md | 51 +++-- .../exit-codes.md | 1 + .../extractor-options.md | 1 + .../index.md | 16 +- .../publishing-and-using-codeql-packs.md} | 214 +++++++++++++----- .../query-reference-files.md | 5 +- .../sarif-output.md | 1 + ...-options-in-a-codeql-configuration-file.md | 9 +- .../testing-custom-queries.md | 17 +- .../testing-query-help-files.md | 8 +- ...sing-custom-queries-with-the-codeql-cli.md | 5 +- .../about-the-codeql-cli.md | 68 ------ .../publishing-and-using-codeql-packs.md | 186 --------------- .../code-scanning/what-is-codeql-cli.md | 2 +- 33 files changed, 897 insertions(+), 595 deletions(-) delete mode 100644 content/code-security/codeql-cli/codeql-cli-reference/index.md create mode 100644 content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md rename content/code-security/codeql-cli/{using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md => getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md} (66%) create mode 100644 content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md create mode 100644 content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md rename content/code-security/codeql-cli/{using-the-codeql-cli/creating-codeql-databases.md => getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md} (75%) rename content/code-security/codeql-cli/{using-the-codeql-cli/getting-started-with-the-codeql-cli.md => getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md} (65%) create mode 100644 content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md rename content/code-security/codeql-cli/{codeql-cli-reference => using-the-advanced-functionality-of-the-codeql-cli}/about-codeql-workspaces.md (92%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/creating-and-working-with-codeql-packs.md (88%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/creating-codeql-query-suites.md (93%) rename content/code-security/codeql-cli/{codeql-cli-reference => using-the-advanced-functionality-of-the-codeql-cli}/exit-codes.md (98%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/extractor-options.md (99%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/index.md (70%) rename content/code-security/codeql-cli/{codeql-cli-reference/about-codeql-packs.md => using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md} (53%) rename content/code-security/codeql-cli/{codeql-cli-reference => using-the-advanced-functionality-of-the-codeql-cli}/query-reference-files.md (92%) rename content/code-security/codeql-cli/{codeql-cli-reference => using-the-advanced-functionality-of-the-codeql-cli}/sarif-output.md (99%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/specifying-command-options-in-a-codeql-configuration-file.md (95%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/testing-custom-queries.md (94%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/testing-query-help-files.md (92%) rename content/code-security/codeql-cli/{using-the-codeql-cli => using-the-advanced-functionality-of-the-codeql-cli}/using-custom-queries-with-the-codeql-cli.md (92%) delete mode 100644 content/code-security/codeql-cli/using-the-codeql-cli/about-the-codeql-cli.md delete mode 100644 content/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs.md diff --git a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql.md b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql.md index b2e6d1c867..d6aa2cd241 100644 --- a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql.md +++ b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql.md @@ -76,7 +76,7 @@ These queries must belong to a published {% data variables.product.prodname_code - {% data variables.product.prodname_ql %} packs do not include transitive dependencies, so queries in the pack can depend only on the standard libraries (that is, the libraries referenced by an `import LANGUAGE` statement in your query), or libraries in the same {% data variables.product.prodname_ql %} pack as the query. - {% data variables.product.prodname_codeql %} query packs (beta) can be downloaded from multiple GitHub container registries. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#downloading-codeql-packs-from-github-enterprise-server)." -For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)." +For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)." {% data reusables.code-scanning.beta-codeql-packs-cli %} diff --git a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/built-in-codeql-query-suites.md b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/built-in-codeql-query-suites.md index 7b1cac2016..749875059f 100644 --- a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/built-in-codeql-query-suites.md +++ b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/built-in-codeql-query-suites.md @@ -20,7 +20,7 @@ With {% data variables.product.prodname_codeql %} {% data variables.product.prod Currently, both the `default` query suite and the `security-extended` query suite are available for default setup for {% data variables.product.prodname_code_scanning %}. For more information on default setup, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning)." -To use a custom query suite, you must configure advanced setup for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. For more information on advanced setups and creating a query suite, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql)" and "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)." +To use a custom query suite, you must configure advanced setup for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. For more information on advanced setups and creating a query suite, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql)" and "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)." ## Built-in {% data variables.product.prodname_codeql %} query suites @@ -40,4 +40,4 @@ The built-in {% data variables.product.prodname_codeql %} query suites, `default ## Further reading -- "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)" +- "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)" diff --git a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md index 789989c779..812e2d3833 100644 --- a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md +++ b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning.md @@ -354,7 +354,7 @@ be used efficiently by the default {% data variables.product.prodname_codeql %} action. To ensure optimal performance, if you need to specify exact query pack versions, you should consider reviewing periodically whether the pinned version of the query pack needs to be moved forward. -For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." +For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." {% endnote %} {% endif %} @@ -559,7 +559,7 @@ To find the id of a query, you can click the alert in the list of alerts in the You can find another example illustrating the use of these filters in the "[Example configuration files](#example-configuration-files)" section. -For more information about using `exclude` and `include` filters in your custom configuration file, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite)." For information on the query metadata you can filter on, see "[Metadata for CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)." +For more information about using `exclude` and `include` filters in your custom configuration file, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite)." For information on the query metadata you can filter on, see "[Metadata for CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)." {% endif %} diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md b/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md index 284e14f169..681a77df9b 100644 --- a/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md +++ b/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md @@ -85,7 +85,7 @@ If you provide a source root, any location of an artifact specified using an abs For example, a SARIF file is uploaded using a source root of `file:///github/workspace`. -``` +```shell # Conversion of absolute URIs to relative URIs for location artifacts file:///github/workspace/src/main.go -> src/main.go diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md b/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md index 6ee396e5f3..fbc4c88da2 100644 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md +++ b/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md @@ -15,7 +15,7 @@ versions: If you're using an old {% data variables.product.prodname_codeql %} workflow you may get the following warning in the output from the "Initialize {% data variables.product.prodname_codeql %}" action: -``` +```shell Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer necessary. Please remove this step as Code Scanning recommends analyzing the merge commit for best results. diff --git a/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md b/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md index e340ce3606..ee1c540835 100644 --- a/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md +++ b/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md @@ -47,9 +47,9 @@ You can display the command-line help for any command using the `--help``--help``--source-root` | {% octicon "x" aria-label="Optional" %} | Use if you run the CLI outside the checkout root of the repository. By default, the `database create` command assumes that the current directory is the root directory for the source files, use this option to specify a different location. | | `--codescanning-config` | {% octicon "x" aria-label="Optional" %} | Advanced. Use if you have a configuration file that specifies how to create the {% data variables.product.prodname_codeql %} databases and what queries to run in later steps. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#using-a-custom-configuration-file)" and "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create#--codescanning-configfile)." | -For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases)." +For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)." ### Single language example This example creates a {% data variables.product.prodname_codeql %} database for the repository checked out at `/checkouts/example-repo`. It uses the JavaScript extractor to create a hierarchical representation of the JavaScript and TypeScript code in the repository. The resulting database is stored in `/codeql-dbs/example-repo`. -``` +```shell $ codeql database create /codeql-dbs/example-repo --language=javascript \ --source-root /checkouts/example-repo @@ -108,7 +108,7 @@ This example creates two {% data variables.product.prodname_codeql %} databases The resulting databases are stored in `python` and `cpp` subdirectories of `/codeql-dbs/example-repo-multi`. -``` +```shell $ codeql database create /codeql-dbs/example-repo-multi \ --db-cluster --language python,cpp \ --command make --no-run-unnecessary-builds \ @@ -153,24 +153,24 @@ codeql database analyze <database> --format=<format> \ | Option | Required | Usage | |--------|:--------:|-----| | `` | {% octicon "check" aria-label="Required" %} | Specify the path for the directory that contains the {% data variables.product.prodname_codeql %} database to analyze. | -| `` | {% octicon "x" aria-label="Optional" %} | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `//qlpacks/codeql/-queries/codeql-suites`. For information about creating your own query suite, see [Creating CodeQL query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites) in the documentation for the {% data variables.product.prodname_codeql_cli %}. +| `` | {% octicon "x" aria-label="Optional" %} | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `//qlpacks/codeql/-queries/codeql-suites`. For information about creating your own query suite, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)" in the documentation for the {% data variables.product.prodname_codeql_cli %}. | `--format` | {% octicon "check" aria-label="Required" %} | Specify the format for the results file generated by the command. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghae or ghec %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)." | `--output` | {% octicon "check" aria-label="Required" %} | Specify where to save the SARIF results file. | `--sarif-category` | {% octicon "question" aria-label="Required with multiple results sets" %} | Optional for single database analysis. Required to define the language when you analyze multiple databases for a single commit in a repository.

Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|{% ifversion code-scanning-tool-status-page %} |
`--sarif-add-baseline-file-info` | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to submit file coverage information to the tool status page. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page#how-codeql-defines-scanned-files)." | {% endif %} -| `--sarif-add-query-help` | {% octicon "x" aria-label="Optional" %} | Use if you want to include any available markdown-rendered query help for custom queries used in your analysis. Any query help for custom queries included in the SARIF output will be displayed in the code scanning UI if the relevant query generates an alert. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli#including-query-help-for-custom-codeql-queries-in-sarif-files)."{% ifversion codeql-packs %} +| `--sarif-add-query-help` | {% octicon "x" aria-label="Optional" %} | Use if you want to include any available markdown-rendered query help for custom queries used in your analysis. Any query help for custom queries included in the SARIF output will be displayed in the code scanning UI if the relevant query generates an alert. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries#including-query-help-for-custom-codeql-queries-in-sarif-files)."{% ifversion codeql-packs %} | `` | {% octicon "x" aria-label="Optional" %} | Use if you want to include CodeQL query packs in your analysis. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} packs](#downloading-and-using-codeql-query-packs)." | `--download` | {% octicon "x" aria-label="Optional" %} | Use if some of your CodeQL query packs are not yet on disk and need to be downloaded before running queries.{% endif %} | `--threads` | {% octicon "x" aria-label="Optional" %} | Use if you want to use more than one thread to run queries. The default value is `1`. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify `0`. | `--verbose` | {% octicon "x" aria-label="Optional" %} | Use to get more detailed information about the analysis process and diagnostic data from the database creation process. -For more information, see [Analyzing databases with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli)." +For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries)." ### Basic example of analyzing a CodeQL database This example analyzes a {% data variables.product.prodname_codeql %} database stored at `/codeql-dbs/example-repo` and saves the results as a SARIF file: `/temp/example-repo-js.sarif`. It uses `--sarif-category` to include extra information in the SARIF file that identifies the results as JavaScript. This is essential when you have more than one {% data variables.product.prodname_codeql %} database to analyze for a single commit in a repository. -``` +```shell $ codeql database analyze /codeql-dbs/example-repo \ javascript-code-scanning.qls --sarif-category=javascript \ --format={% ifversion fpt or ghae or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} --output=/temp/example-repo-js.sarif @@ -190,7 +190,7 @@ You can optionally submit file coverage information to {% data variables.product To include file coverage information with your {% data variables.product.prodname_code_scanning %} results, add the `--sarif-add-baseline-file-info` flag to the `codeql database analyze` invocation in your CI system, for example: -``` +```shell $ codeql database analyze /codeql-dbs/example-repo \ javascript-code-scanning.qls --sarif-category=javascript \ --sarif-add-baseline-file-info \ --format={% ifversion fpt or ghae or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} \ @@ -242,7 +242,7 @@ For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manu The following example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch. The example assumes that the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API uses the `GITHUB_TOKEN` environment variable. -``` +```shell codeql github upload-results \ --repository=my-org/example-repo \ --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ @@ -309,7 +309,7 @@ Before you can use a {% data variables.product.prodname_codeql %} pack to analyz **Note:** If you specify a particular version of a query pack to use, be aware that the version you specify may eventually become too old for the latest version of {% data variables.product.prodname_codeql %} to make efficient use of. To ensure optimal performance, if you need to specify exact query pack versions, you should reevaluate which versions you pin to whenever you upgrade the {% data variables.product.prodname_codeql %} CLI you're using. -For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." +For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." {% endnote %} {% endif %} @@ -323,7 +323,7 @@ This example runs the `codeql database analyze` command with the `--download` op 1. Run all the default queries in `octo-org/security-queries`. 1. Run only the query `queries/csrf.ql` from `octo-org/optional-security-queries` -``` +```shell $ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \ octo-org/security-queries \ octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \ @@ -423,6 +423,6 @@ If you use the {% data variables.product.prodname_codeql_cli %} to run {% data v ## Further reading -- [Creating CodeQL databases](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases) -- [Analyzing databases with the CodeQL CLI](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli){% ifversion codeql-packs %} -- [Publishing and using CodeQL packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs){% endif %} +- "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)." +- "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries)."{% ifversion codeql-packs %} +- [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs){% endif %} diff --git a/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system.md b/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system.md index d7f304b369..e3715984a2 100644 --- a/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system.md +++ b/content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system.md @@ -86,7 +86,7 @@ After you extract the {% data variables.product.prodname_codeql_cli %} bundle, y **Extract from successful output:** -``` +```shell codeql/cpp-all (//qlpacks/codeql/cpp-all/) codeql/cpp-examples (//qlpacks/codeql/cpp-examples/) codeql/cpp-queries (//qlpacks/codeql/cpp-queries/) diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-init.md b/content/code-security/codeql-cli/codeql-cli-manual/database-init.md index 2cee076e09..1f758f7fd9 100644 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-init.md +++ b/content/code-security/codeql-cli/codeql-cli-manual/database-init.md @@ -117,7 +117,7 @@ the filesystem. build tracing," which allows integration into existing build workflows when an explicit build command is not available. For information about when and how to use this feature, please refer to our documentation at -[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases). +"[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)." ### Extractor selection options diff --git a/content/code-security/codeql-cli/codeql-cli-reference/index.md b/content/code-security/codeql-cli/codeql-cli-reference/index.md deleted file mode 100644 index 891d75bc0b..0000000000 --- a/content/code-security/codeql-cli/codeql-cli-reference/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: CodeQL CLI reference -intro: 'You can learn how to use {% data variables.product.prodname_codeql %} workspaces and {% data variables.product.prodname_codeql %} packs and how to understand the output of {% data variables.product.prodname_codeql %} commands.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghae: '*' - ghec: '*' -topics: - - Advanced Security - - Code scanning -children: - - /about-codeql-packs - - /about-codeql-workspaces - - /query-reference-files - - /sarif-output - - /exit-codes ---- - diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md new file mode 100644 index 0000000000..99e15da167 --- /dev/null +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md @@ -0,0 +1,81 @@ +--- +title: About the CodeQL CLI +intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to run CodeQL processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.product_name %}.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +redirect_from: + - /code-security/codeql-cli/about-the-codeql-cli + - /code-security/codeql-cli/using-the-codeql-cli/about-the-codeql-cli +--- + +## About the {% data variables.product.prodname_codeql_cli %} + +Software developers and security researchers can secure their code +using {% data variables.product.prodname_codeql %} analysis. For more information about {% data variables.product.prodname_codeql %}, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql)." + +{% data reusables.code-scanning.what-is-codeql-cli %} + +You can use the {% data variables.product.prodname_codeql_cli %} to: + +- Run {% data variables.product.prodname_codeql %} analyses using queries provided by {% data variables.product.prodname_dotcom %} engineers and the open source community +- Generate code scanning alerts that you can upload to display in {% data variables.product.product_name %} +- Create {% data variables.product.prodname_codeql %} databases to use in the {% data variables.product.prodname_codeql %} for Visual Studio Code extension. +- Develop and test custom {% data variables.product.prodname_codeql %} queries to use in your own analyses + +The {% data variables.product.prodname_codeql_cli %} can analyze: + +- Dynamic languages, for example, JavaScript and Python. +- Compiled languages, for example, C/C++, C#,{% ifversion codeql-go-autobuild %} Go,{% endif %} and Java. +- Codebases written in a mixture of languages. + +For information about setting up the {% data variables.product.prodname_codeql_cli %}, see +"[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)." + +For information about using the {% data variables.product.prodname_codeql_cli %} in a third-party CI system to create results to display in {% data variables.product.prodname_dotcom %} as code scanning alerts, see [Configuring {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system). For information about enabling {% data variables.product.prodname_codeql %} code scanning using {% data variables.product.prodname_actions %}, see {% ifversion code-scanning-without-workflow %}"[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning)" and {% endif %}"[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning)." + +## About using the {% data variables.product.prodname_codeql_cli %} for {% data variables.product.prodname_code_scanning %} + +You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} on code that you're processing in a third-party continuous integration (CI) system. {% data reusables.code-scanning.about-code-scanning %} For an overview of the options for CI systems, see "[AUTOTITLE](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system)." For recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/recommended-hardware-resources-for-running-codeql)." + +Alternatively, you can use {% data variables.product.prodname_actions %} or Azure DevOps pipelines to scan code using the {% data variables.product.prodname_codeql_cli %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository)" or [Configure {% data variables.product.prodname_ghas_azdo %}](https://learn.microsoft.com/en-us/azure/devops/repos/security/configure-github-advanced-security-features) in Microsoft Learn. + +For an overview of all the options for using CodeQL analysis for code scanning, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)." + +{% data reusables.code-scanning.licensing-note %} + +## About generating code scanning results with {% data variables.product.prodname_codeql_cli %} + +If you choose to run the {% data variables.product.prodname_codeql_cli %} directly, you first have to install the {% data variables.product.prodname_codeql_cli %} locally. If you are planning to use the {% data variables.product.prodname_codeql_cli %} with an external CI system, you need to make the {% data variables.product.prodname_codeql_cli %} available to servers in your CI system, and ensure that they can authenticate with {% data variables.product.product_name %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)." + +Once the {% data variables.product.prodname_codeql_cli %} is set up, you can use three different commands to generate results and upload them to {% data variables.product.product_name %}: + +1. `database create` to create a {% data variables.product.prodname_codeql %} database to represent the hierarchical structure of each supported programming language in the repository. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)." +2. `database analyze` to run queries to analyze each {% data variables.product.prodname_codeql %} database and summarize the results in a SARIF file. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries)." +3. `github upload-results` to upload the resulting SARIF files to {% data variables.product.product_name %} where the results are matched to a branch or pull request and displayed as {% data variables.product.prodname_code_scanning %} alerts. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github)." + +## About the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} license + +**License notice:** If you don’t have a {% data variables.product.prodname_enterprise %} license then, by installing this product, you are agreeing to the [{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} Terms and Conditions](https://securitylab.github.com/tools/codeql/license). + +{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} is licensed on a per-user basis. Under the license restrictions, you can use {% data variables.product.prodname_codeql %} to perform the following tasks: + +- To perform academic research. +- To demonstrate the software. +- To test {% data variables.product.prodname_codeql %} queries that are released under an OSI-approved License to confirm that new versions of those queries continue to find the right vulnerabilities. + +Where "OSI-approved License" means an Open Source Initiative (OSI)-approved open source software license. + +If you are working with an Open Source Codebase (that is, a codebase that is released under an OSI-approved License) you can also use {% data variables.product.prodname_codeql %} for the following tasks: + +- To perform analysis of the Open Source Codebase. +- If the Open Source Codebase is hosted and maintained on {% data variables.product.prodname_dotcom_the_website %}, to generate CodeQL databases for or during automated analysis, continuous integration, or continuous delivery. + +{% data variables.product.prodname_codeql %} can’t be used for automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise, except in the express cases set forth herein. For these uses, contact the [sales team](https://enterprise.github.com/contact). diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md similarity index 66% rename from content/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md rename to content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md index cd2e6b6fdf..bc06aa8e9a 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md @@ -1,8 +1,8 @@ --- -title: Analyzing databases with the CodeQL CLI -shortTitle: Analyzing databases +title: Analyzing your code with CodeQL queries intro: 'You can run queries against a {% data variables.product.prodname_codeql %} database extracted from a codebase.' product: '{% data reusables.gated-features.codeql %}' +shortTitle: Analyzing code versions: fpt: '*' ghes: '*' @@ -14,25 +14,23 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/analyzing-databases-with-the-codeql-cli + - /code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli --- -{% data reusables.codeql-cli.codeql-site-migration-note %} - ## About analyzing databases with the {% data variables.product.prodname_codeql_cli %} {% data reusables.code-scanning.codeql-cli-version-ghes %} -To analyze a codebase, you run queries against a CodeQL -database extracted from the code. +To analyze a codebase, you run queries against a CodeQL database extracted from the code. {% data variables.product.prodname_codeql %} analyses produce [interpreted results](https://codeql.github.com/docs/codeql-overview/about-codeql/#interpret-query-results) that can be displayed as alerts or paths in source code. -For information about writing queries to run with `database analyze`, see "[Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." +For information about writing queries to run with `database analyze`, see "[Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." {% note %} **Other query-running commands** -Queries run with `database analyze` have strict [metadata requirements](/code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli#including-query-metadata). You can also execute queries using the following +Queries run with `database analyze` have strict [metadata requirements](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli#including-query-metadata). You can also execute queries using the following plumbing-level subcommands: - [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-run-queries), which @@ -52,8 +50,8 @@ analyze` to directly generate interpreted results. Before starting an analysis you must: -- [Set up the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli//getting-started-with-the-codeql-cli) to run commands locally. -- [Create a {% data variables.product.prodname_codeql %} database](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases) for the source code you want to analyze. +- [Set up the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) to run commands locally. +- [Create a {% data variables.product.prodname_codeql %} database](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) for the source code you want to analyze. The simplest way to run `codeql database analyze` is using {% data variables.product.prodname_codeql %} packs. You can also run the command using queries from a local checkout of the {% data variables.product.prodname_codeql %} repository, @@ -71,43 +69,36 @@ displayed in the correct location in the source code. You can analyze a database by running the following command: -``` +```shell codeql database analyze --format= --output= ... ``` -You must specify: +{% note %} -- ``: the path to the {% data variables.product.prodname_codeql %} database you want to analyze. -- `--format`: the format of the results file generated during analysis. A number of different formats are supported, including CSV, [SARIF](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#sarif-file), and graph formats. For more information about CSV and SARIF, -see [Results](#results). To find out which other results formats are -supported, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze)." -- `--output`: the output path of the results file generated during analysis. +**Note:** If you analyze more than one {% data variables.product.prodname_codeql %} database for a single commit, you must specify a SARIF category for each set of results generated by this command. When you upload the results to {% data variables.product.product_name %}, {% data variables.product.prodname_code_scanning %} uses this category to store the results for each language separately. If you forget to do this, each upload overwrites the previous results. -You can also specify: +```shell +codeql database analyze <database> --format=<format> \ + --sarif-category=<language-specifier> --output=<output> \ + {% ifversion codeql-packs %}<packs,queries>{% else %}<queries>{% endif %} +``` +{% endnote %} -- `...`: a space-separated list of queries to run over your database. This -is a list of arguments, where each argument can be: - - a path to a query file - - a path to a directory containing query files - - a path to a query suite file - - the name of a {% data variables.product.prodname_codeql %} query pack - - with an optional version range - - with an optional path to a query, directory, or query suite inside the pack +You must specify ``, `--format`, and `--output`. You can specify additional options depending on what analysis you want to do. - If omitted, the default query suite for the language of the analyzed database will be used. For the complete syntax of query specifiers, see "[Specifying which queries to run in a {% data variables.product.prodname_codeql %} pack](#specifying-which-queries-to-run-in-a-codeql-pack)." - -- `--sarif-category`: an identifying category for the results. Used when -you want to upload more than one set of results for a commit. -For example, when you use `github upload-results` to send results for more than one -language to the {% data variables.product.prodname_dotcom %} code scanning API. For more information about this use case, see [Configuring {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system). - -- `--sarif-add-query-help`: (supported in version 2.7.1 onwards) adds any custom query help written -in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in `.qhelp` files must be -converted to `.md` before running the analysis. For further information, -see "[Including query help for custom {% data variables.product.prodname_codeql %} queries in SARIF files](#including-query-help-for-custom-codeql-queries-in-sarif-files)." - -- `--download`: a boolean flag that will allow the CLI to download any referenced {% data variables.product.prodname_codeql %} packages that are not available locally. -If this flag is missing and a referenced {% data variables.product.prodname_codeql %} package is not available locally, the command will fail. +| Option | Required | Usage | +|--------|:--------:|-----| +| `` | {% octicon "check" aria-label="Required" %} | Specify the path for the directory that contains the {% data variables.product.prodname_codeql %} database to analyze. | +| `` | {% octicon "x" aria-label="Optional" %} | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `//qlpacks/codeql/-queries/codeql-suites`. For information about creating your own query suite, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites) in the documentation for the {% data variables.product.prodname_codeql_cli %}. +| `--format` | {% octicon "check" aria-label="Required" %} | Specify the format for the results file generated during analysis. A number of different formats are supported, including CSV, [SARIF](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#sarif-file), and graph formats. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghae or ghec %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)." +| `--output` | {% octicon "check" aria-label="Required" %} | Specify where to save the SARIF results file. +| `--sarif-category` | {% octicon "question" aria-label="Required with multiple results sets" %} | Optional for single database analysis. Required to define the language when you analyze multiple databases for a single commit in a repository.

Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|{% ifversion code-scanning-tool-status-page %} +|
`--sarif-add-baseline-file-info` | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to submit file coverage information to the {% data variables.code-scanning.tool_status_page %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page#how-codeql-defines-scanned-files)." | {% endif %} +| `--sarif-add-query-help` | {% octicon "x" aria-label="Optional" %} | Use if you want to include any available markdown-rendered query help for custom queries used in your analysis. Any query help for custom queries included in the SARIF output will be displayed in the code scanning UI if the relevant query generates an alert. For more information, see "[Including query help for custom {% data variables.product.prodname_codeql %} queries in SARIF files](#including-query-help-for-custom-codeql-queries-in-sarif-files)."{% ifversion codeql-packs %} +| `` | {% octicon "x" aria-label="Optional" %} | Use if you want to include CodeQL query packs in your analysis. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} query packs](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#downloading-and-using-codeql-query-packs)." +| `--download` | {% octicon "x" aria-label="Optional" %} | Use if some of your CodeQL query packs are not yet on disk and need to be downloaded before running queries.{% endif %} +| `--threads` | {% octicon "x" aria-label="Optional" %} | Use if you want to use more than one thread to run queries. The default value is `1`. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify `0`. +| `--verbose` | {% octicon "x" aria-label="Optional" %} | Use to get more detailed information about the analysis process and diagnostic data from the database creation process. {% note %} @@ -124,61 +115,37 @@ required upgrades. Explicitly running the upgrade command is not necessary. For full details of all the options you can use when analyzing databases, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze)." -## Specifying which queries to run in a {% data variables.product.prodname_codeql %} pack +### Basic example of analyzing a CodeQL database -Query specifiers are used by `codeql database analyze` and other commands that operate on a set of queries. -The complete form of a query specifier is `scope/name@range:path`, where: +This example analyzes a {% data variables.product.prodname_codeql %} database stored at `/codeql-dbs/example-repo` and saves the results as a SARIF file: `/temp/example-repo-js.sarif`. It uses `--sarif-category` to include extra information in the SARIF file that identifies the results as JavaScript. This is essential when you have more than one {% data variables.product.prodname_codeql %} database to analyze for a single commit in a repository. -- `scope/name` is the qualified name of a {% data variables.product.prodname_codeql %} pack. -- `range` is a [semver range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). -- `path` is a file system path to a single query, a directory containing queries, or a query suite file. +```shell +$ codeql database analyze /codeql-dbs/example-repo \ + javascript-code-scanning.qls --sarif-category=javascript \ + --format={% ifversion fpt or ghae or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} --output=/temp/example-repo-js.sarif -When you specify a `scope/name`, the `range` and `path` are -optional. If you omit a `range` then the latest version of the -specified pack is used. If you omit a `path` then the default query suite -of the specified pack is used. +> Running queries. +> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql. +... +> Shutting down query evaluator. +> Interpreting results. +``` -The `path` can be one of: a `.ql` query file, a directory -containing one or more queries, or a `.qls` query suite file. If -you omit a pack name, then you must provide a `path`, -which will be interpreted relative to the working directory -of the current process. Glob patterns are not supported. +{% ifversion code-scanning-tool-status-page %} +### Adding file coverage information to your results for monitoring -If you specify both a `scope/name` and `path`, then the `path` cannot -be absolute. It is considered relative to the root of the {% data variables.product.prodname_codeql %} -pack. +You can optionally submit file coverage information to {% data variables.product.product_name %} for display on the {% data variables.code-scanning.tool_status_page %} for {% data variables.product.prodname_code_scanning %}. For more information about file coverage information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page#how-codeql-defines-scanned-files)." -### Example query specifiers +To include file coverage information with your {% data variables.product.prodname_code_scanning %} results, add the `--sarif-add-baseline-file-info` flag to the `codeql database analyze` invocation in your CI system, for example: -- `codeql/python-queries` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack. +```shell +$ codeql database analyze /codeql-dbs/example-repo \ + javascript-code-scanning.qls --sarif-category=javascript \ + --sarif-add-baseline-file-info \ --format={% ifversion fpt or ghae or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} \ + --output=/temp/example-repo-js.sarif +``` -- `codeql/python-queries@1.2.3` - All the queries in the default query suite of version `1.2.3` of the `codeql/python-queries` pack. - -- `codeql/python-queries@~1.2.3` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack that is >= `1.2.3` and < `1.3.0`. - -- `codeql/python-queries:Functions` - All queries in the `Functions` directory in the latest version of the `codeql/python-queries` pack. - -- `codeql/python-queries@1.2.3:Functions` - All queries in the `Functions` directory in version 1.2.3 of the `codeql/python-queries` pack. - -- `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` - All queries in the `codeql-suites/python-code-scanning.qls` directory in version 1.2.3 of the `codeql/python-queries` pack. - -- `suites/my-suite.qls` - All queries in the `suites/my-suite.qls` file relative to the current working directory. - -{% note %} - -**Tip** - -The default query suite of the standard {% data variables.product.prodname_codeql %} query packs are `codeql-suites/-code-scanning.qls`. Several other useful query suites can also be found in the `codeql-suites` directory of each pack. For example, the `codeql/cpp-queries` pack contains the following query suites: - -- `cpp-code-scanning.qls` - Standard Code Scanning queries for C++. The default query suite for this pack. - -- `cpp-security-extended.qls` - Queries from the default `cpp-code-scanning.qls` suite for C++, plus lower severity and precision queries. - -- `cpp-security-and-quality.qls` - Queries from `cpp-security-extended.qls`, plus maintainability and reliability queries. - -You can see the sources for these query suites in the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites). Query suites for other languages are similar. - -{% endnote %} +{% endif %} ## Examples of running database analyses @@ -199,11 +166,11 @@ The {% data variables.product.prodname_codeql %} package management functionalit To run an existing {% data variables.product.prodname_codeql %} query pack from the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can specify one or more pack names: -``` +```shell codeql database analyze microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download ``` -This command runs the default query suite of two {% data variables.product.prodname_codeql %} query packs: `microsoft/coding-standards` version 1.0.0 and the latest version of `github/security-queries` on the specified database. For further information about default suites, see "[Publishing and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)." +This command runs the default query suite of two {% data variables.product.prodname_codeql %} query packs: `microsoft/coding-standards` version 1.0.0 and the latest version of `github/security-queries` on the specified database. For further information about default suites, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)." The `--download` flag is optional. Using it will ensure the query pack is downloaded if it isn’t yet available locally. {% endif %} @@ -213,7 +180,7 @@ The `--download` flag is optional. Using it will ensure the query pack is downlo To run a single query over a {% data variables.product.prodname_codeql %} database for a JavaScript codebase, you could use the following command from the directory containing your database: -``` +```shell codeql database analyze --download codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv ``` @@ -226,13 +193,13 @@ The analysis generates a CSV file (`js-results.csv`) in a new directory (`js-ana Alternatively, if you have the {% data variables.product.prodname_codeql %} repository checked out, you can execute the same queries by specifying the path to the query directly: -``` +```shell codeql database analyze ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv ``` You can also run your own custom queries with the `database analyze` command. For more information about preparing your queries to use with the {% data variables.product.prodname_codeql_cli %}, -see "[Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." +see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." ### Running all queries in a directory @@ -255,14 +222,14 @@ code scanning query suites. For example, to execute all Python queries contained in the `Functions` directory in the `codeql/python-queries` query pack you would run: -``` +```shell codeql database analyze codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download ``` Alternatively, if you have the {% data variables.product.prodname_codeql %} repository checked out, you can execute the same queries by specifying the path to the directory directly: -``` +```shell codeql database analyze ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif ``` @@ -301,33 +268,33 @@ pack. To analyze a database using all queries in the `experimental/Security` folder within the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack you can use: -``` +```shell codeql database analyze --format=sarif-latest --output=results \ codeql/cpp-queries:experimental/Security ``` To run the `RedundantNullCheckParam.ql` query in the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack use: -``` +```shell codeql database analyze --format=sarif-latest --output=results \ 'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql' ``` To analyze your database using the `cpp-security-and-quality.qls` query suite from a version of the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack that is >= 0.0.3 and < 0.1.0 (the highest compatible version will be chosen) you can use: -``` +```shell codeql database analyze --format=sarif-latest --output=results \ 'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls' ``` -If you need to reference a query file, directory, or suite whose path contains a literal `@` or `:`, you can prefix the query specification with path: like so: +If you need to reference a query file, directory, or suite whose path contains a literal `@` or `:`, you can prefix the query specification with `path:` like so: -``` +```shell codeql database analyze --format=sarif-latest --output=results \ path:C:/Users/ci/workspace@2/security/query.ql ``` -For more information about {% data variables.product.prodname_codeql %} packs, see [About {% data variables.product.prodname_codeql %} Packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs). +For more information about {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). {% endif %} ### Running query suites @@ -335,7 +302,7 @@ For more information about {% data variables.product.prodname_codeql %} packs, s To run a query suite on a {% data variables.product.prodname_codeql %} database for a C/C++ codebase, you could use the following command from the directory containing your database: -``` +```shell codeql database analyze codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download ``` @@ -347,9 +314,9 @@ or "[AUTOTITLE](/rest/code-scanning)". based on certain metadata properties. The standard {% data variables.product.prodname_codeql %} packs have metadata that specify the location of the query suites used by code scanning, so the {% data variables.product.prodname_codeql_cli %} knows where to find these suite files automatically, and you don’t have to specify the full path on the command line. -For more information, see "[Creating {% data variables.product.prodname_codeql %} query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)." +For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)." -For information about creating custom query suites, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)." +For information about creating custom query suites, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)." #### Diagnostic and summary information @@ -372,7 +339,7 @@ alerts generated by the custom queries. From {% data variables.product.prodname_codeql_cli %} v2.7.1 onwards, you can include markdown-rendered query help in SARIF files by providing the `--sarif-add-query-help` option when running `codeql database analyze`. -For more information, see [Configuring {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database). +For more information, see [AUTOTITLE](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database). You can write query help for custom queries directly in a markdown file and save it alongside the corresponding query. Alternatively, for consistency with the standard {% data variables.product.prodname_codeql %} queries, @@ -380,7 +347,7 @@ you can write query help in the `.qhelp` format. Query help written in `.qhelp` files can’t be included in SARIF files, and they can’t be processed by code scanning so must be converted to markdown before running the analysis. For more information, see ["Query help files"](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) -and "[Testing query help files](/code-security/codeql-cli/using-the-codeql-cli/testing-query-help-files)." +and "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files)." ## Results @@ -388,7 +355,7 @@ You can save analysis results in a number of different formats, including SARIF and CSV. The SARIF format is designed to represent the output of a broad range of static -analysis tools. For more information, see [SARIF output](/code-security/codeql-cli/codeql-cli-reference/sarif-output). +analysis tools. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output). If you choose to generate results in CSV format, then each line in the output file corresponds to an alert. Each line is a comma-separated list with the following information. diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md new file mode 100644 index 0000000000..0281374fee --- /dev/null +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md @@ -0,0 +1,180 @@ +--- +title: Customizing analysis with CodeQL packs +intro: 'You can use {% data variables.product.prodname_codeql %} packs to run {% data variables.product.prodname_codeql %} queries maintained by other people, or to share {% data variables.product.prodname_codeql %} queries that you''ve developed.' +shortTitle: Customizing analysis +product: '{% data reusables.gated-features.codeql %}' +versions: + feature: codeql-packs +topics: + - Advanced Security + - Code scanning + - CodeQL +redirect_from: + - /code-security/codeql-cli/about-codeql-packs + - /code-security/codeql-cli/codeql-cli-reference/about-codeql-packs +--- + +{% data reusables.codeql-cli.beta-note-package-management %} + +## About {% data variables.product.prodname_codeql %} packs + +{% data reusables.code-scanning.codeql-cli-version-ghes %} + +{% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. You can publish your own {% data variables.product.prodname_codeql %} packs and download packs created by others. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata. + +There are two types of {% data variables.product.prodname_codeql %} packs: query packs and library packs. + +- Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and {% ifversion query-pack-compatibility %}pre-compiled representations of each query, in addition to the query sources{% else %}a compilation cache{% endif %}. This ensures consistent and efficient execution of the queries in the pack. + +- Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled {% ifversion query-pack-compatibility %}separately{% else %}and there is no compilation cache included when the pack is published{% endif %}. + +You can use the package management commands in the {% data variables.product.prodname_codeql_cli %} to create {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-and-working-with-codeql-packs)." You can also publish and download {% data variables.product.prodname_codeql %} packs using the {% data variables.product.prodname_codeql_cli %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)." + +The standard {% data variables.product.prodname_codeql %} packages for all supported languages are published in the [{% data variables.product.prodname_container_registry %}](https://github.com/orgs/codeql/packages). +The [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql) contains source files for the standard {% data variables.product.prodname_codeql %} packs for all supported languages. + +## {% data variables.product.prodname_codeql %} pack structure + +A {% data variables.product.prodname_codeql %} pack must contain a file called `qlpack.yml` in its root directory. In the `qlpack.yml` file, the `name:` field must have a value that follows the format of `/`, where `` is the {% data variables.product.prodname_dotcom %} organization or user account that the pack will be published to and `` is the name of the pack. Additionally, query packs and library packs with {% data variables.product.prodname_codeql %} tests contain a `codeql-pack.lock.yml` file that contains the resolved dependencies of the pack. This file is generated during a call to the `codeql pack install` command, is not meant to be edited by hand, and should be added to your version control system. + +The other files and directories within the pack should be logically organized. For example, typically: + +- Queries are organized into directories for specific categories. + +- Queries for specific products, libraries, and frameworks are organized into +their own top-level directories. + +{% ifversion codeql-packs %} +## Downloading and using {% data variables.product.prodname_codeql %} query packs + +{% data reusables.code-scanning.beta-codeql-packs-cli %} + +The {% data variables.product.prodname_codeql_cli %} bundle includes queries that are maintained by {% data variables.product.company_short %} experts, security researchers, and community contributors. If you want to run queries developed by other organizations, {% data variables.product.prodname_codeql %} query packs provide an efficient and reliable way to download and run queries. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql-queries)." + +Before you can use a {% data variables.product.prodname_codeql %} pack to analyze a database, you must download any packages you require from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}. This can be done either by using the `--download` flag as part of the `codeql database analyze` command. If a package is not publicly available, you will need to use a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} to authenticate. For more information and an example, see "[Uploading results to {% data variables.product.product_name %}](#uploading-results-to-github)". + +| Option | Required | Usage | +|--------|:--------:|-----| +| `` | {% octicon "check" aria-label="Required" %} | Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack. | +| `--github-auth-stdin` | {% octicon "x" aria-label="Optional" %} | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token. + +{% ifversion query-pack-compatibility %} +{% note %} + +**Note:** If you specify a particular version of a query pack to use, be aware that the version you specify may eventually become too old for the latest version of {% data variables.product.prodname_codeql %} to make efficient use of. To ensure optimal performance, if you need to specify exact query pack versions, you should reevaluate which versions you pin to whenever you upgrade the {% data variables.product.prodname_codeql %} CLI you're using. + +For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." + +{% endnote %} +{% endif %} + +### Basic example of downloading and using query packs + +This example runs the `codeql database analyze` command with the `--download` option to: + +1. Download the latest version of the `octo-org/security-queries` pack. +2. Download a version of the `octo-org/optional-security-queries` pack that is _compatible_ with version 1.0.1 (in this case, it is version 1.0.2). For more information on semver compatibility, see [npm's semantic version range documentation](https://github.com/npm/node-semver#ranges). +3. Run all the default queries in `octo-org/security-queries`. +4. Run only the query `queries/csrf.ql` from `octo-org/optional-security-queries` + +```shell +$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \ + octo-org/security-queries \ + octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \ + --format=sarif-latest --output=/temp/example-repo-js.sarif + +> Download location: /Users/mona/.codeql/packages +> Installed fresh octo-org/security-queries@1.0.0 +> Installed fresh octo-org/optional-security-queries@1.0.2 +> Running queries. +> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. +> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. +> Starting evaluation of octo-org/security-queries/query1.ql. +> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. +> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. +> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql. +> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs. +> Shutting down query evaluator. +> Interpreting results. +``` + +### Direct download of {% data variables.product.prodname_codeql %} packs + +If you want to download a {% data variables.product.prodname_codeql %} pack without running it immediately, then you can use the `codeql pack download` command. This is useful if you want to avoid accessing the internet when running {% data variables.product.prodname_codeql %} queries. When you run the {% data variables.product.prodname_codeql %} analysis, you can specify packs, versions, and paths in the same way as in the previous example: + +```shell +echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ... +``` + +### Downloading {% data variables.product.prodname_codeql %} packs from multiple {% data variables.product.company_short %} container registries + +If your {% data variables.product.prodname_codeql %} packs reside on multiple container registries, then you must instruct the {% data variables.product.prodname_codeql_cli %} where to find each pack. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#downloading-codeql-packs-from-github-enterprise-server)." +{% endif %} + +## Specifying which queries to run in a {% data variables.product.prodname_codeql %} pack + +Query specifiers are used by `codeql database analyze` and other commands that operate on a set of queries. +The complete form of a query specifier is `scope/name@range:path`, where: + +- `scope/name` is the qualified name of a {% data variables.product.prodname_codeql %} pack. +- `range` is a [semver range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). +- `path` is a file system path to a single query, a directory containing queries, or a query suite file. + +When you specify a `scope/name`, the `range` and `path` are +optional. If you omit a `range` then the latest version of the +specified pack is used. If you omit a `path` then the default query suite +of the specified pack is used. + +The `path` can be one of: a `.ql` query file, a directory +containing one or more queries, or a `.qls` query suite file. If +you omit a pack name, then you must provide a `path`, +which will be interpreted relative to the working directory +of the current process. Glob patterns are not supported. + +If you specify both a `scope/name` and `path`, then the `path` cannot +be absolute. It is considered relative to the root of the {% data variables.product.prodname_codeql %} +pack. + +### Example query specifiers + +- `codeql/python-queries` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack. + +- `codeql/python-queries@1.2.3` - All the queries in the default query suite of version `1.2.3` of the `codeql/python-queries` pack. + +- `codeql/python-queries@~1.2.3` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack that is >= `1.2.3` and < `1.3.0`. + +- `codeql/python-queries:Functions` - All queries in the `Functions` directory in the latest version of the `codeql/python-queries` pack. + +- `codeql/python-queries@1.2.3:Functions` - All queries in the `Functions` directory in version 1.2.3 of the `codeql/python-queries` pack. + +- `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` - All queries in the `codeql-suites/python-code-scanning.qls` directory in version 1.2.3 of the `codeql/python-queries` pack. + +- `suites/my-suite.qls` - All queries in the `suites/my-suite.qls` file relative to the current working directory. + +{% note %} + +**Tip** + +The default query suite of the standard {% data variables.product.prodname_codeql %} query packs are `codeql-suites/-code-scanning.qls`. Several other useful query suites can also be found in the `codeql-suites` directory of each pack. For example, the `codeql/cpp-queries` pack contains the following query suites: + +- `cpp-code-scanning.qls` - Standard Code Scanning queries for C++. The default query suite for this pack. + +- `cpp-security-extended.qls` - Queries from the default `cpp-code-scanning.qls` suite for C++, plus lower severity and precision queries. + +- `cpp-security-and-quality.qls` - Queries from `cpp-security-extended.qls`, plus maintainability and reliability queries. + +You can see the sources for these query suites in the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites). Query suites for other languages are similar. + +{% endnote %} + +{% ifversion query-pack-compatibility %} +### About published packs + +When a pack is published for use in analyses, the `codeql pack create` or `codeql pack publish` command verifies that the content is complete and also adds some additional pieces of content to it: + +- For query packs, a copy of each of the library packs it depends on, in the precise versions it has been developed with. Users of the query pack won't need to download these library packs separately. + +- For query packs, precompiled representations of each of the queries. These are faster to execute than it would be to compile the QL source for the query at each analysis. + +Most of this data is located in a directory named `.codeql` in the published pack, but precompiled queries are in files with a `.qlx` suffix next to the `.ql` source for each query. When analyzing a database with a query from a published pack, {% data variables.product.prodname_codeql %} will load these files instead of the `.ql` source. If you need to modify the content of a _published_ pack, be sure to remove all of the `.qlx` files, since they may prevent modifications in the `.ql` files from taking effect. +{% endif %} diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md new file mode 100644 index 0000000000..0d3550d6a3 --- /dev/null +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md @@ -0,0 +1,25 @@ +--- +title: Getting started with the CodeQL CLI +intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to locally develop, test and run CodeQL queries on software projects.' +shortTitle: Getting started +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +children: + - /about-the-codeql-cli + - /setting-up-the-codeql-cli + - /preparing-your-code-for-codeql-analysis + - /analyzing-your-code-with-codeql-queries + - /customizing-analysis-with-codeql-packs + - /uploading-codeql-analysis-results-to-github +redirect_from: + - /code-security/codeql-cli/using-the-codeql-cli +--- + diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md similarity index 75% rename from content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases.md rename to content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md index f6a3af20bd..a52a5bd95e 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases.md +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md @@ -1,6 +1,7 @@ --- -title: Creating CodeQL databases -intro: 'You can build a {% data variables.product.prodname_codeql %} database containing the data needed to query your code.' +title: Preparing your code for CodeQL analysis +intro: 'You can build a {% data variables.product.prodname_codeql %} database containing the data needed to analyze your code.' +shortTitle: Preparing code for analysis product: '{% data reusables.gated-features.codeql %}' versions: fpt: '*' @@ -13,24 +14,29 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/creating-codeql-databases + - /code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases --- -{% data reusables.codeql-cli.codeql-site-migration-note %} - -## About creating {% data variables.product.prodname_codeql %} databases +## About preparing your code for analysis {% data reusables.code-scanning.codeql-cli-version-ghes %} -Before you analyze your code using {% data variables.product.prodname_codeql %}, you need to create a {% data variables.product.prodname_codeql %} database containing all the data required to run queries on your code. You can create {% data variables.product.prodname_codeql %} databases yourself using the {% data variables.product.prodname_codeql_cli %}, or download them from {% data variables.product.prodname_dotcom_the_website %}. +Before you analyze your code using {% data variables.product.prodname_codeql %}, you need to create a {% data variables.product.prodname_codeql %} database containing all the data required to run queries on your code. You can create {% data variables.product.prodname_codeql %} databases yourself using the {% data variables.product.prodname_codeql_cli %}. -{% data variables.product.prodname_codeql %} analysis relies on extracting relational data from your code, and using it to build a [{% data variables.product.prodname_codeql %} database](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database). {% data variables.product.prodname_codeql %} databases contain all of the important information about a codebase, which can be analyzed by executing {% data variables.product.prodname_codeql %} queries against it. {% data variables.product.prodname_dotcom %} creates and stores {% data variables.product.prodname_codeql %} databases for a large number of open-source projects. For more information, see "[Downloading {% data variables.product.prodname_codeql %} databases from {% data variables.product.prodname_dotcom_the_website %}](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases#downloading-databases-from-githubcom)." +{% data variables.product.prodname_codeql %} analysis relies on extracting relational data from your code, and using it to build a [{% data variables.product.prodname_codeql %} database](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database). {% data variables.product.prodname_codeql %} databases contain all of the important information about a codebase, which can be analyzed by executing {% data variables.product.prodname_codeql %} queries against it. -You can also create {% data variables.product.prodname_codeql %} databases yourself using the {% data variables.product.prodname_codeql_cli %}. Before you generate a {% data variables.product.prodname_codeql %} database, you need to: +Before you generate a {% data variables.product.prodname_codeql %} database, you need to: -- Install and set up the {% data variables.product.prodname_codeql_cli %}. For more information, see "[Getting started with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli)." -- Check out the version of your codebase you want to analyze. The directory should be ready to build, with all dependencies already installed. +1. Install and set up the {% data variables.product.prodname_codeql_cli %}. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)." +2. Check out the code that you want to analyze: + - For a branch, check out the head of the branch that you want to analyze. + - For a pull request, check out either the head commit of the pull request, or check out a {% data variables.product.prodname_dotcom %}-generated merge commit of the pull request. +3. Set up the environment for the codebase, making sure that any dependencies are available. For more information, see "[Creating databases for non-compiled languages](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#creating-databases-for-non-compiled-languages)" and "[Creating databases for compiled languages](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#creating-databases-for-compiled-languages)" in "Preparing your code for {% data variables.product.prodname_codeql %} analysis". +4. Find the build command, if any, for the codebase. Typically this is available in a configuration file in the CI system. + +Once the codebase is ready, you can run `codeql database create` to create the database. For information about using the {% data variables.product.prodname_codeql_cli %} in a third-party CI system to create results to display in {% data variables.product.prodname_dotcom %} as code scanning alerts, see [Configuring {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system). For information about enabling {% data variables.product.prodname_codeql %} code scanning using {% data variables.product.prodname_actions %}, see {% ifversion code-scanning-without-workflow %}"[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning)" and {% endif %}"[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning)." @@ -38,7 +44,7 @@ For information about using the {% data variables.product.prodname_codeql_cli %} {% data variables.product.prodname_codeql %} databases are created by running the following command from the checkout root of your project: -``` +```shell codeql database create --language= ``` @@ -61,21 +67,75 @@ You must specify: {% data reusables.code-scanning.beta-kotlin-or-swift-support %} {% data reusables.code-scanning.beta-ruby-support %} -You can specify additional options depending on the location of your source file, if the code needs to be compiled, and if you want to create {% data variables.product.prodname_codeql %} databases for more than one language: +You can specify additional options depending on the location of your source file, if the code needs to be compiled, and if you want to create {% data variables.product.prodname_codeql %} databases for more than one language. -- `--source-root`: the root folder for the primary source files used in database creation. By default, the command assumes that the current directory is the source root—use this option to specify a different location. -- `--db-cluster`: use for multi-language codebases when you want to create databases for more than one language. -- `--command`: used when you create a database for one or more compiled languages, omit if the only languages requested are Python and JavaScript. This specifies the build commands needed to invoke the compiler. Commands are run from the current folder, or `--source-root` if specified. If you don’t include a `--command`, {% data variables.product.prodname_codeql %} will attempt to detect the build system automatically, using a built-in autobuilder. -- `--no-run-unnecessary-builds`: used with `--db-cluster` to suppress the build command for languages where the {% data variables.product.prodname_codeql_cli %} does not need to monitor the build (for example, Python and JavaScript/TypeScript). +| Option | Required | Usage | +|--------|:--------:|-----| +| `` | {% octicon "check" aria-label="Required" %} | Specify the name and location of a directory to create for the {% data variables.product.prodname_codeql %} database. The command will fail if you try to overwrite an existing directory. If you also specify `--db-cluster`, this is the parent directory and a subdirectory is created for each language analyzed. | +| `--language` | {% octicon "check" aria-label="Required" %} | Specify the identifier for the language to create a database for, one of: {% data reusables.code-scanning.codeql-languages-keywords %} (use `javascript` to analyze TypeScript code {% ifversion codeql-kotlin-beta %} and `java` to analyze Kotlin code{% endif %}). When used with `--db-cluster`, the option accepts a comma-separated list, or can be specified more than once. | +| `--command` | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from `--source-root`. Not needed for Python and JavaScript/TypeScript analysis. | +| `--db-cluster` | {% octicon "x" aria-label="Optional" %} | Use in multi-language codebases to generate one database for each language specified by `--language`. | +| `--no-run-unnecessary-builds` | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to suppress the build command for languages where the {% data variables.product.prodname_codeql_cli %} does not need to monitor the build (for example, Python and JavaScript/TypeScript). | +| `--source-root` | {% octicon "x" aria-label="Optional" %} | Use if you run the CLI outside the checkout root of the repository. By default, the `database create` command assumes that the current directory is the root directory for the source files, use this option to specify a different location. | +| `--codescanning-config` | {% octicon "x" aria-label="Optional" %} | Advanced. Use if you have a configuration file that specifies how to create the {% data variables.product.prodname_codeql %} databases and what queries to run in later steps. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#using-a-custom-configuration-file)" and "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create#--codescanning-configfile)." | You can specify extractor options to customize the behavior of extractors that create {% data variables.product.prodname_codeql %} databases. For more information, see -"[Extractor options](/code-security/codeql-cli/using-the-codeql-cli/extractor-options)." +"[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options)." For full details of all the options you can use when creating databases, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create)." +### Single language example + +This example creates a {% data variables.product.prodname_codeql %} database for the repository checked out at `/checkouts/example-repo`. It uses the JavaScript extractor to create a hierarchical representation of the JavaScript and TypeScript code in the repository. The resulting database is stored in `/codeql-dbs/example-repo`. + +```shell +$ codeql database create /codeql-dbs/example-repo --language=javascript \ + --source-root /checkouts/example-repo + +> Initializing database at /codeql-dbs/example-repo. +> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd] + in /checkouts/example-repo. +> [build-stdout] Single-threaded extraction. +> [build-stdout] Extracting +... +> Finalizing database at /codeql-dbs/example-repo. +> Successfully created database at /codeql-dbs/example-repo. +``` + +### Multiple language example + +This example creates two {% data variables.product.prodname_codeql %} databases for the repository checked out at `/checkouts/example-repo-multi`. It uses: + +- `--db-cluster` to request analysis of more than one language. +- `--language` to specify which languages to create databases for. +- `--command` to tell the tool the build command for the codebase, here `make`. +- `--no-run-unnecessary-builds` to tell the tool to skip the build command for languages where it is not needed (like Python). + +The resulting databases are stored in `python` and `cpp` subdirectories of `/codeql-dbs/example-repo-multi`. + +```shell +$ codeql database create /codeql-dbs/example-repo-multi \ + --db-cluster --language python,cpp \ + --command make --no-run-unnecessary-builds \ + --source-root /checkouts/example-repo-multi +Initializing databases at /codeql-dbs/example-repo-multi. +Running build command: [make] +[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py +[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed. +[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi +[build-stdout] [INFO] Python version 3.6.9 +[build-stdout] [INFO] Python extractor version 5.16 +[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms +[build-stdout] [INFO] Processed 1 modules in 0.15s +[build-stdout] +Finalizing databases at /codeql-dbs/example-repo-multi. +Successfully created databases at /codeql-dbs/example-repo-multi. +$ +``` + ## Progress and results -Errors are reported if there are any problems with the options you have specified. For interpreted languages, the extraction progress is displayed in the console—for each source file, it reports if extraction was successful or if it failed. For compiled languages, the console will display the output of the build system. +Errors are reported if there are any problems with the options you have specified. For interpreted languages, the extraction progress is displayed in the console. For each source file, the console shows if extraction was successful or if it failed. For compiled languages, the console will display the output of the build system. When the database is successfully created, you’ll find a new directory at the path specified in the command. If you used the `--db-cluster` option to create more than one database, a subdirectory is created for each language. Each {% data variables.product.prodname_codeql %} database directory contains a number of subdirectories, including the relational data (required for analysis) and a source archive—a copy of the source files made at the time the database was created—which is used for displaying analysis results. @@ -93,7 +153,7 @@ The {% data variables.product.prodname_codeql_cli %} includes extractors to crea Creating databases for JavaScript requires no additional dependencies, but if the project includes TypeScript files, you must install Node.js 6.x or later. In the command line you can specify `--language=javascript` to extract both JavaScript and TypeScript files: -``` +```shell codeql database create --language=javascript --source-root /javascript-database ``` @@ -112,7 +172,7 @@ When creating databases for Python you must ensure: In the command line you must specify `--language=python`. For example: -``` +```shell codeql database create --language=python /python-database ``` @@ -122,7 +182,7 @@ This executes the `database create` subcommand from the code’s checkout root, Creating databases for Ruby requires no additional dependencies. In the command line you must specify `--language=ruby`. For example: -``` +```shell codeql database create --language=ruby --source-root /ruby-database ``` @@ -141,7 +201,7 @@ The {% data variables.product.prodname_codeql_cli %} includes autobuilders for { An autobuilder is invoked automatically when you execute `codeql database create` for a compiled `--language` if don’t include a `--command` option. For example, for a Java codebase, you would simply run: -``` +```shell codeql database create --language=java /java-database ``` @@ -168,7 +228,7 @@ The following examples are designed to give you an idea of some of the build com - C/C++ project built using `make`: - ``` + ```shell codeql database create cpp-database --language=cpp --command=make ``` @@ -176,38 +236,38 @@ The following examples are designed to give you an idea of some of the build com It is a good idea to add `/t:rebuild` to ensure that all code will be built, or do a prior `dotnet clean` (code that is not built will not be included in the {% data variables.product.prodname_codeql %} database): - ``` + ```shell codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild' ``` - Go project built using the `CODEQL_EXTRACTOR_GO_BUILD_TRACING=on` environment variable: - ``` + ```shell CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go ``` - Go project built using a custom build script: - ``` + ```shell codeql database create go-database --language=go --command='./scripts/build.sh' ``` - Java project built using Gradle: - ``` + ```shell # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL: codeql database create java-database --language=java --command='gradle --no-daemon clean test' ``` - Java project built using Maven: - ``` + ```shell codeql database create java-database --language=java --command='mvn clean install' ``` - Java project built using Ant: - ``` + ```shell codeql database create java-database --language=java --command='ant -f build.xml' ``` @@ -215,21 +275,21 @@ The following examples are designed to give you an idea of some of the build com - Swift project built from an Xcode project or workspace. By default, the largest Swift target is built: It's a good idea to ensure that the project is in a clean state and that there are no build artefacts available. - - ``` + + ```shell xcodebuild clean -all codeql database create -l swift swift-database ``` - Swift project built with `swift build`: - ``` + ```shell codeql database create -l swift -c "swift build" swift-database ``` - Swift project built with `xcodebuild`: - ``` + ```shell codeql database create -l swift -c "xcodebuild build -target your-target" swift-database ``` @@ -237,7 +297,7 @@ The following examples are designed to give you an idea of some of the build com - Swift project built using a custom build script: - ``` + ```shell codeql database create -l swift -c "./scripts/build.sh" swift-database ``` @@ -245,7 +305,7 @@ The following examples are designed to give you an idea of some of the build com - Project built using Bazel: - ``` + ```shell # Navigate to the Bazel workspace. # Before building, remove cached objects @@ -267,7 +327,7 @@ The following examples are designed to give you an idea of some of the build com - Project built using a custom build script: - ``` + ```shell codeql database create new-database --language= --command='./scripts/build.sh' ``` @@ -283,7 +343,7 @@ If the {% data variables.product.prodname_codeql_cli %} autobuilders for compile To create a {% data variables.product.prodname_codeql %} database with indirect build tracing, run the following command from the checkout root of your project: -``` +```shell codeql database init ... --begin-tracing ``` @@ -302,7 +362,7 @@ You may specify other options for the `codeql database init` command as normal. The `codeql database init` command will output a message: -``` +```shell Created skeleton . This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in /temp/tracingEnvironment. Please run one of these scripts before invoking your build command. Based on your operating system, we recommend you run: ... @@ -329,7 +389,7 @@ Once you have created a {% data variables.product.prodname_codeql %} database us The following example shows how you could use indirect build tracing in an Azure DevOps pipeline to create a {% data variables.product.prodname_codeql %} database: -``` +```yaml steps: # Download the {% data variables.product.prodname_codeql_cli %} and query packs... # Check out the repository ... @@ -405,7 +465,7 @@ steps: You can check if a repository has any {% data variables.product.prodname_codeql %} databases available for download using the `/repos///code-scanning/codeql/databases` endpoint. For example, to check for {% data variables.product.prodname_codeql %} databases using the [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/gh_api) you would run: -``` +```shell gh api /repos///code-scanning/codeql/databases ``` @@ -413,7 +473,7 @@ This command returns information about any {% data variables.product.prodname_co When you have confirmed that a {% data variables.product.prodname_codeql %} database exists for the language you are interested in, you can download it using the following command: -``` +```shell gh api /repos///code-scanning/codeql/databases/ -H 'Accept: application/zip' > path/to/local/database.zip ``` diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md similarity index 65% rename from content/code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.md rename to content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md index 39adea0f3a..e48a3e1ea0 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli.md +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md @@ -1,7 +1,6 @@ --- -title: Getting started with the CodeQL CLI -shortTitle: Getting started -intro: 'To get started with the {% data variables.product.prodname_codeql_cli %}, you need to set up the CLI so that it can access the tools and libraries required to create and analyze databases.' +title: Setting up the CodeQL CLI +intro: 'To get started with the {% data variables.product.prodname_codeql_cli %}, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.' product: '{% data reusables.gated-features.codeql %}' versions: fpt: '*' @@ -13,20 +12,17 @@ topics: - Code scanning - CodeQL redirect_from: - - /code-security/codeql-cli/getting-started-with-the-codeql-cli + - /code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli + --- -{% data reusables.codeql-cli.codeql-site-migration-note %} - -## Getting started with the {% data variables.product.prodname_codeql_cli %} +## Setting up the {% data variables.product.prodname_codeql_cli %} {% data reusables.code-scanning.codeql-cli-version-ghes %} To run {% data variables.product.prodname_codeql %} commands, you need to set up the CLI so that it can access the tools, queries, and libraries required to create and analyze databases. -## Setting up the {% data variables.product.prodname_codeql_cli %} - The {% data variables.product.prodname_codeql_cli %} can be set up to support many different use cases and directory structures. To get started quickly, we recommend adopting a relatively simple setup, as outlined in the steps below. @@ -42,7 +38,7 @@ tools](https://developer.apple.com/downloads/index.action) and [Rosetta 2](https {% endnote %} -For information about installing the {% data variables.product.prodname_codeql_cli %} in a CI system to create results to display in {% data variables.product.prodname_dotcom %} as code scanning alerts, see [Installing {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system). +For information about installing the {% data variables.product.prodname_codeql_cli %} in a CI system to create results to display in {% data variables.product.prodname_dotcom %} as code scanning alerts, see "[AUTOTITLE](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system)." ### 1. Download the {% data variables.product.prodname_codeql_cli %} zip package @@ -51,21 +47,23 @@ various {% data variables.product.prodname_codeql %}-specific files. If you don downloading this archive, you are agreeing to the [{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} Terms and Conditions](https://securitylab.github.com/tools/codeql/license). +You should download the {% data variables.product.prodname_codeql %} bundle from https://github.com/github/codeql-action/releases. The bundle contains: + +- {% data variables.product.prodname_codeql_cli %} product +- A compatible version of the queries and libraries from https://github.com/github/codeql +- Precompiled versions of all the queries included in the bundle + +{% ifversion ghes or ghae %} + {% note %} - -**Important:** There are several versions of the CLI available to download, depending on your use case: - -- If you want to use the most up to date {% data variables.product.prodname_codeql %} tools and features, download the version tagged `latest`. -- If you want to generate code scanning data to upload to {% data variables.product.prodname_enterprise %} server, then download the version that is compatible with the {% data variables.product.prodname_codeql_cli %} used in your CI system. For more information, see "[Installing {% data variables.product.prodname_codeql_cli %} in your CI system](/enterprise-server@latest/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system#downloading-the-codeql-cli)." - +For {% data variables.product.product_name %}{% ifversion ghes %} {{ allVersions[currentVersion].currentRelease }}{% endif %}, we recommend {% data variables.product.prodname_codeql_cli %} version {% data variables.product.codeql_cli_ghes_recommended_version %}. {% endnote %} -If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply -[download the zip archive](https://github.com/github/codeql-cli-binaries/releases) -for the version you require. +{% endif %} -If you want the CLI for a specific platform, download the appropriate `codeql-PLATFORM.zip` file. -Alternatively, you can download `codeql.zip`, which contains the CLI for all supported platforms. +You should always use the {% data variables.product.prodname_codeql %} bundle as this ensures compatibility and also gives much better performance than a separate download of the {% data variables.product.prodname_codeql_cli %} and checkout of the {% data variables.product.prodname_codeql %} queries. If you will only be running the CLI on one specific platform, download the appropriate `codeql-bundle-PLATFORM.tar.gz` file. Alternatively, you can download `codeql-bundle.tar.gz`, which contains the CLI for all supported platforms. + +{% data reusables.code-scanning.beta-codeql-packs-cli %} #### Download information for macOS "Catalina" (or newer) users @@ -108,12 +106,42 @@ At this point, you can execute {% data variables.product.prodname_codeql %} comm {% endnote %} -### 4. Verify your {% data variables.product.prodname_codeql_cli %} setup +## Testing the {% data variables.product.prodname_codeql_cli %} configuration -{% data variables.product.prodname_codeql_cli %} has subcommands you can execute to verify that you are correctly set up to create and analyze databases: +After you extract the {% data variables.product.prodname_codeql_cli %} bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases: -- Run `codeql resolve languages` to show which languages are available for database creation. This will list the languages supported by default in your {% data variables.product.prodname_codeql_cli %} package.{% ifversion codeql-packs %} -- (Optional) You can download some "[{% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)" containing pre-compiled queries you would like to run. To do this, run `codeql pack download [...pack-name]`, where `pack-name` is the name of the pack you want to download. The core query packs are a good place to start. They are: +- `codeql resolve qlpacks` if `//codeql` is on the `PATH`. +- `//codeql/codeql resolve qlpacks` otherwise. + +Extract from successful output: +```shell +codeql/cpp-all (//qlpacks/codeql/cpp-all/) +codeql/cpp-examples (//qlpacks/codeql/cpp-examples/) +codeql/cpp-queries (//qlpacks/codeql/cpp-queries/) +codeql/csharp-all (//qlpacks/codeql/charp-all/) +codeql/csharp-examples (//qlpacks/codeql/charp-examples/) +codeql/csharp-queries (//qlpacks/codeql/charp-queries/) +codeql/java-all (//qlpacks/codeql/java-all/) +codeql/java-examples (//qlpacks/codeql/java-examples/) +codeql/java-queries (//qlpacks/codeql/java-queries/) +codeql/javascript-all (//qlpacks/codeql/javascript-all/) +codeql/javascript-examples (//qlpacks/codeql/javascript-examples/) +codeql/javascript-queries (//qlpacks/codeql/javascript-queries/) +codeql/python-all (//qlpacks/codeql/python-all/) +codeql/python-examples (//qlpacks/codeql/python-examples/) +codeql/python-queries (//qlpacks/codeql/python-queries/) +codeql/ruby-all (//qlpacks/codeql/ruby-all/) +codeql/ruby-examples (//qlpacks/codeql/ruby-examples/) +codeql/ruby-queries (//qlpacks/codeql/ruby-queries/) +... +``` + +You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted {% data variables.product.prodname_codeql_cli %} bundle, shown in the earlier example as ``, unless you are using a checkout of `github/codeql`. If the {% data variables.product.prodname_codeql_cli %} is unable to locate the qlpacks for the expected languages, check that you downloaded the {% data variables.product.prodname_codeql %} bundle and not a standalone copy of the {% data variables.product.prodname_codeql_cli %}. + +You can also run `codeql resolve languages` to show which languages are available for database creation. This will list the languages supported by default in your {% data variables.product.prodname_codeql_cli %} package. + +{% ifversion codeql-packs %} +(Optional) You can download some "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)" containing pre-compiled queries you would like to run. To do this, run `codeql pack download [...pack-name]`, where `pack-name` is the name of the pack you want to download. The core query packs are a good place to start. They are: - `codeql/cpp-queries` - `codeql/csharp-queries` @@ -123,10 +151,15 @@ At this point, you can execute {% data variables.product.prodname_codeql %} comm - `codeql/python-queries` - `codeql/ruby-queries` +Alternatively, you can download query packs during the analysis by using the `--download` flag of the `codeql database analyze` command. + {% endif %} -Alternatively, you can download query packs during the analysis by using the `--download` flag of the `codeql database analyze` - command. +## Generating a token for authentication with {% data variables.product.product_name %} + +If you eventually want to upload your results to {% data variables.product.product_name %} to display as code scanning alerts, you will need to generate a {% data variables.product.pat_generic %} with the `security_events` write permission. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." + +If you have installed the {% data variables.product.prodname_codeql_cli %} in a third-party CI system to create results to display in {% data variables.product.prodname_dotcom %} as code scanning alerts, you can use a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} to upload results to {% data variables.product.product_name %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system#generating-a-token-for-authentication-with-github)." ## Checking out the {% data variables.product.prodname_codeql %} source code directly @@ -173,7 +206,7 @@ For more information, see the [Relocation announcement](https://github.com/githu Within this repository, the queries and libraries are organized into {% data variables.product.prodname_codeql %} packs. Along with the queries themselves, {% data variables.product.prodname_codeql %} packs contain important metadata that tells the {% data variables.product.prodname_codeql_cli %} how to process the query files. For more information, -see "[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)." +see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)." {% endif %} {% note %} diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md new file mode 100644 index 0000000000..c41e29f694 --- /dev/null +++ b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md @@ -0,0 +1,112 @@ +--- +title: Uploading CodeQL analysis results to GitHub +shortTitle: Uploading results to GitHub +intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to upload {% data variables.product.prodname_codeql %} analysis results to {% data variables.product.product_name %}.' +product: '{% data reusables.gated-features.codeql %}' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +--- + +## About SARIF output + +{% data variables.product.prodname_dotcom %} creates {% data variables.product.prodname_code_scanning %} alerts in a repository using information from Static Analysis Results Interchange Format (SARIF) files. SARIF is designed to represent the output of a broad range of static analysis tools, and there are many features in the SARIF specification that are considered "optional". The results must use SARIF version 2.1.0. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)." + +After analyzing a CodeQL database using the CodeQL CLI, you will have a SARIF file that contains the results. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries)." You can then use the {% data variables.product.prodname_codeql_cli %} to upload results to {% data variables.product.prodname_dotcom %}. + +If you used a method other than the {% data variables.product.prodname_codeql_cli %} to generate results, you can use other upload methods. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)." + +## Uploading results to {% data variables.product.product_name %} + +{% data reusables.code-scanning.upload-sarif-alert-limit %} + +Before you can upload results to {% data variables.product.product_name %}, you must determine the best way to pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} you created earlier to the {% data variables.product.prodname_codeql_cli %} (see "[AUTOTITLE](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system#generating-a-token-for-authentication-with-github)"). We recommend that you review your CI system's guidance on the secure use of a secret store. The {% data variables.product.prodname_codeql_cli %} supports: + +- Interfacing with a secret store using the `--github-auth-stdin` option (recommended). +- Saving the secret in the environment variable `GITHUB_TOKEN` and running the CLI without including the `--github-auth-stdin` option. +- For testing purposes you can pass the `--github-auth-stdin` command-line option and supply a temporary token via standard input. + +When you have decided on the most secure and reliable method for your configuration, run `codeql github upload-results` on each SARIF results file and include `--github-auth-stdin` unless the token is available in the environment variable `GITHUB_TOKEN`. + +```shell +# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available from a secret store +<call-to-retrieve-secret> | codeql github upload-results \ + --repository=<repository-name> \ + --ref=<ref> --commit=<commit> \ + --sarif=<file> {% ifversion ghes or ghae %}--github-url=<URL> \ + {% endif %}--github-auth-stdin + +# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available in GITHUB_TOKEN +codeql github upload-results \ + --repository=<repository-name> \ + --ref=<ref> --commit=<commit> \ + --sarif=<file> {% ifversion ghes or ghae %}--github-url=<URL> \ + {% endif %} +``` + +| Option | Required | Usage | +|--------|:--------:|-----| +| `--repository` | {% octicon "check" aria-label="Required" %} | Specify the _OWNER/NAME_ of the repository to upload data to. The owner must be an organization within an enterprise that has a license for {% data variables.product.prodname_GH_advanced_security %} and {% data variables.product.prodname_GH_advanced_security %} must be enabled for the repository{% ifversion fpt or ghec %}, unless the repository is public{% endif %}. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)." +| `--ref` | {% octicon "check" aria-label="Required" %} | Specify the name of the `ref` you checked out and analyzed so that the results can be matched to the correct code. For a branch use: `refs/heads/BRANCH-NAME`, for the head commit of a pull request use `refs/pull/NUMBER/head`, or for the {% data variables.product.prodname_dotcom %}-generated merge commit of a pull request use `refs/pull/NUMBER/merge`. +| `--commit` | {% octicon "check" aria-label="Required" %} | Specify the full SHA of the commit you analyzed. +| `--sarif` | {% octicon "check" aria-label="Required" %} | Specify the SARIF file to load.{% ifversion ghes or ghae %} +| `--github-url` | {% octicon "check" aria-label="Required" %} | Specify the URL for {% data variables.product.product_name %}.{% endif %} +| `--github-auth-stdin` | {% octicon "x" aria-label="Optional" %} | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token. + +For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results)." + +### Basic example of uploading results to {% data variables.product.product_name %} + +The following example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch. The example assumes that the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API uses the `GITHUB_TOKEN` environment variable. + +```shell +codeql github upload-results \ + --repository=my-org/example-repo \ + --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ + --sarif=/temp/example-repo-js.sarif {% ifversion ghes or ghae %}--github-url={% data variables.command_line.git_url_example %} \ + {% endif %} +``` + +There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.product_name %} shortly afterward. You can see alerts directly in the pull request or on the **Security** tab for branches, depending on the code you checked out. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests)" and "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository)." + +{% ifversion code-scanning-tool-status-page %} +## Uploading diagnostic information to {% data variables.product.product_name %} if the analysis fails + +When {% data variables.product.prodname_codeql_cli %} finishes analyzing a database successfully, it gathers diagnostic information such as file coverage, warnings, and errors, and includes it in the SARIF file with the results. When you upload the SARIF file to {% data variables.product.company_short %} the diagnostic information is displayed on the {% data variables.product.prodname_code_scanning %} {% data variables.code-scanning.tool_status_page %} for the repository to make it easy to see how well {% data variables.product.prodname_codeql %} is working and debug any problems. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page)." + +However, if `codeql database analyze` fails for any reason there is no SARIF file to upload to {% data variables.product.company_short %} and no diagnostic information to show on the {% data variables.product.prodname_code_scanning %} {% data variables.code-scanning.tool_status_page %} for the repository. This makes it difficult for users to troubleshoot analysis unless they have access to log files in your CI system. + +We recommend that you configure your CI workflow to export and upload diagnostic information to {% data variables.product.product_name %} when an analysis fails. You can do this using the following simple commands to export diagnostic information and upload it to {% data variables.product.company_short %}. + +### Exporting diagnostic information if the analysis fails + +You can create a SARIF file for the failed analysis using "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics)", for example: + +```shell +$ codeql database export-diagnostics codeql-dbs/example-repo \ + --sarif-category=javascript --format={% ifversion fpt or ghae or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} \ + --output=/temp/example-repo-js.sarif +``` + +This SARIF file will contain diagnostic information for the failed analysis, including any file coverage information, warnings, and errors generated during the analysis. + +### Uploading diagnostic information if the analysis fails + +You can make this diagnostic information available on the {% data variables.code-scanning.tool_status_page %} by uploading the SARIF file to {% data variables.product.product_name %} using "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results)", for example: + +```shell +codeql github upload-results \ + --repository=my-org/example-repo \ + --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ + --sarif=/temp/example-repo-js.sarif {% ifversion ghes or ghae %}--github-url={% data variables.command_line.git_url_example %} \ + {% endif %} +``` + +This is the same as the process for uploading SARIF files from successful analyses. +{% endif %} \ No newline at end of file diff --git a/content/code-security/codeql-cli/index.md b/content/code-security/codeql-cli/index.md index d814ac75d2..2d5c7f28bb 100644 --- a/content/code-security/codeql-cli/index.md +++ b/content/code-security/codeql-cli/index.md @@ -13,8 +13,8 @@ topics: - Code scanning - CodeQL children: - - /using-the-codeql-cli - - /codeql-cli-reference + - /getting-started-with-the-codeql-cli + - /using-the-advanced-functionality-of-the-codeql-cli - /codeql-cli-manual --- diff --git a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md similarity index 92% rename from content/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md index e85d5b8a74..a1696cd3d2 100644 --- a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md @@ -10,6 +10,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/about-codeql-workspaces + - /code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces --- {% data reusables.codeql-cli.codeql-site-migration-note %} @@ -18,7 +19,7 @@ redirect_from: {% data reusables.code-scanning.codeql-action-version-ghes %} -You use a {% data variables.product.prodname_codeql %} workspace when you want to group multiple {% data variables.product.prodname_codeql %} packs together. A typical use case for a {% data variables.product.prodname_codeql %} workspace is to develop a set of {% data variables.product.prodname_codeql %} library and query packs that are mutually dependent. For more information on {% data variables.product.prodname_codeql %} packs, see "[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs)." +You use a {% data variables.product.prodname_codeql %} workspace when you want to group multiple {% data variables.product.prodname_codeql %} packs together. A typical use case for a {% data variables.product.prodname_codeql %} workspace is to develop a set of {% data variables.product.prodname_codeql %} library and query packs that are mutually dependent. For more information on {% data variables.product.prodname_codeql %} packs, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)." The main benefit of a {% data variables.product.prodname_codeql %} workspace is that it makes it easier for you to develop and maintain multiple {% data variables.product.prodname_codeql %} packs. When you use a {% data variables.product.prodname_codeql %} workspace, all the {% data variables.product.prodname_codeql %} packs in the workspace are available as _source dependencies_ for each other when you run a {% data variables.product.prodname_codeql %} command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related {% data variables.product.prodname_codeql %} packs. @@ -32,7 +33,7 @@ A {% data variables.product.prodname_codeql %} workspace is defined by a `codeql - The `ignore` block contains a list of glob patterns that define {% data variables.product.prodname_codeql %} packs that are not available in the workspace. -- The `registries` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing {% data variables.product.prodname_codeql %} packs. For more information, see "[Publishing and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes)." +- The `registries` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing {% data variables.product.prodname_codeql %} packs. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes)." Each entry in the `provide` or `ignore` section must map to the location of a `qlpack.yml` file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see "[@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob#patterns) ." @@ -66,7 +67,7 @@ This is particularly useful in the following situations: ## {% data variables.product.prodname_codeql %} workspaces and query resolution -All {% data variables.product.prodname_codeql %} packs in a workspace are available as source dependencies for each other when you run any {% data variables.product.prodname_codeql %} command that resolves queries or packs. For example, when you run `codeql pack install` in a pack directory in a workspace, any dependency that can be found in the workspace will be used instead of downloading that dependency to the package cache and adding it to the `codeql-pack.lock.yml` file. For more information, see "[Creating and working with {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies)." +All {% data variables.product.prodname_codeql %} packs in a workspace are available as source dependencies for each other when you run any {% data variables.product.prodname_codeql %} command that resolves queries or packs. For example, when you run `codeql pack install` in a pack directory in a workspace, any dependency that can be found in the workspace will be used instead of downloading that dependency to the package cache and adding it to the `codeql-pack.lock.yml` file. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies)." Similarly, when you publish a {% data variables.product.prodname_codeql %} query pack to the {% data variables.product.prodname_dotcom %} container registry using `codeql pack publish` the command will always use the dependencies from the workspace instead of using dependencies found in the local package cache. diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md similarity index 88% rename from content/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md index 84c1210482..ffbabda9a2 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md @@ -10,6 +10,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/creating-and-working-with-codeql-packs + - /code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs --- {% data reusables.codeql-cli.codeql-site-migration-note %} @@ -28,17 +29,17 @@ There are two types of {% data variables.product.prodname_codeql %} packs: query - Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled {% ifversion query-pack-compatibility %}separately{% else %}and there is no compilation cache included when the pack is published{% endif %}. -You can use the `pack` command in the {% data variables.product.prodname_codeql_cli %} to create {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. You can also publish and download {% data variables.product.prodname_codeql %} packs using the `pack` command. For more information, see "[Publishing and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)." +You can use the `pack` command in the {% data variables.product.prodname_codeql_cli %} to create {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. You can also publish and download {% data variables.product.prodname_codeql %} packs using the `pack` command. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)." {% ifversion query-pack-compatibility %} -For more information about compatibility between published query packs and different {% data variables.product.prodname_codeql %} releases, see "[About {% data variables.product.prodname_codeql %} pack compatibility](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." +For more information about compatibility between published query packs and different {% data variables.product.prodname_codeql %} releases, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)." {% endif %} ## Creating a {% data variables.product.prodname_codeql %} pack You can create a {% data variables.product.prodname_codeql %} pack by running the following command from the checkout root of your project: -``` +```shell codeql pack init / ``` @@ -60,13 +61,13 @@ If you already have a `qlpack.yml` file, you can edit it manually to convert it 1. Migrate the list of dependencies in `libraryPathDependencies` to the `dependencies` block. Specify the version range for each dependency. If the range is unimportant, or you are unsure of compatibility, you can specify `"\*"`, which indicates that any version is acceptable and will default to the latest version when you run `codeql pack install`. -For more information about the properties, see "[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs#about-codeql-packs)." +For more information about the properties, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)." ## Adding and installing dependencies to a {% data variables.product.prodname_codeql %} pack You can add dependencies on {% data variables.product.prodname_codeql %} packs using the command `codeql pack add`. You must specify the scope, name, and (optionally) a compatible version range. -``` +```shell codeql pack add /@x.x.x / ``` @@ -76,7 +77,7 @@ This command updates the `qlpack.yml` file with the requested dependencies and d You can also manually edit the `qlpack.yml` file to include dependencies and install the dependencies with the command: -``` +```shell codeql pack install ``` @@ -86,9 +87,9 @@ This command downloads all dependencies to the shared cache on the local disk. **Notes:** -- Running the `codeql pack add` and `codeql pack install` commands will generate or update the `codeql-pack.lock.yml` file. This file should be checked-in to version control. The `codeql-pack.lock.yml` file contains the precise version numbers used by the pack. For more information, see "[About codeql-pack.lock.yml files](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs#about-codeql-pack-lock)." +- Running the `codeql pack add` and `codeql pack install` commands will generate or update the `codeql-pack.lock.yml` file. This file should be checked-in to version control. The `codeql-pack.lock.yml` file contains the precise version numbers used by the pack. For more information, see "[About codeql-pack.lock.yml files](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files)." -- By default `codeql pack install` will install dependencies from the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. You can install dependencies from a {% data variables.product.prodname_ghe_server %} {% data variables.product.prodname_container_registry %} by creating a `qlconfig.yml` file. For more information, see "[Publishing and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)." +- By default `codeql pack install` will install dependencies from the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. You can install dependencies from a {% data variables.product.prodname_ghe_server %} {% data variables.product.prodname_container_registry %} by creating a `qlconfig.yml` file. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs)." {% endnote %} diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md similarity index 93% rename from content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md index 73e48c66e6..f33c159ff5 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md @@ -13,6 +13,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/creating-codeql-query-suites + - /code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites --- {% data reusables.codeql-cli.codeql-site-migration-note %} @@ -34,7 +35,7 @@ suite definition have been executed, the result is a set of selected queries. {% ifversion codeql-packs %} {% note %} -**Note:** Any custom queries that you want to add to a query suite must be in a [{% data variables.product.prodname_codeql %} pack](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs) and contain the correct query metadata. For more information, see "[Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." +**Note:** Any custom queries that you want to add to a query suite must be in a [{% data variables.product.prodname_codeql %} pack](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)" and contain the correct query metadata. For more information, see "[Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli)." {% endnote %} {% endif %} @@ -48,7 +49,7 @@ queries using: - A `query` instruction—tells {% data variables.product.prodname_codeql %} to look for one or more specified `.ql` files: - ``` + ```yaml - query: ``` @@ -58,7 +59,7 @@ files: - A `queries` instruction—tells {% data variables.product.prodname_codeql %} to recursively scan a directory for `.ql` files: - ``` + ```yaml - queries: ``` @@ -66,7 +67,7 @@ for `.ql` files: contains the suite definition file. To find the queries relative to a different {% data variables.product.prodname_codeql %} pack, add a `from` field: - ``` + ```yaml - queries: from: version: ^x.y.z @@ -78,7 +79,7 @@ for `.ql` files: - A `qlpack` instruction—tells {% data variables.product.prodname_codeql %} to resolve queries in the default suite of the named {% data variables.product.prodname_codeql %} pack: - ``` + ```yaml - qlpack: version: ^x.y.z ``` @@ -164,7 +165,7 @@ filter by the query `id`: This filter matches all the queries in the default suite of `codeql/cpp-queries`, except for the two queries with the excluded identifiers: -``` +```yaml - qlpack: codeql/cpp-queries - exclude: id: @@ -174,7 +175,7 @@ This filter matches all the queries in the default suite of `codeql/cpp-queries` In this example, a separate `exclude` instruction is used for each query: -``` +```yaml - qlpack: codeql/cpp-queries - exclude: id: cpp/cleartext-transmission @@ -184,7 +185,7 @@ In this example, a separate `exclude` instruction is used for each query: In this example, a regular expression excludes the same two queries. It would also exclude any future queries added to the suite with identifiers that begin: `cpp/cleartext-`: -``` +```yaml - qlpack: codeql/cpp-queries - exclude: id: @@ -195,7 +196,7 @@ To define a suite that selects all queries in the default suite of the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack, and then refines them to only include security queries, use: -``` +```yaml - qlpack: codeql/cpp-queries - include: tags contain: security @@ -204,7 +205,7 @@ security queries, use: To define a suite that selects all queries with `@kind problem` and `@precision high` from the `my-custom-queries` directory, use: -``` +```yaml - queries: my-custom-queries - include: kind: problem @@ -214,7 +215,7 @@ and `@precision high` from the `my-custom-queries` directory, use: Note that the following query suite definition behaves differently from the definition above. This definition selects queries that are `@kind problem` _or_ are `@precision very-high`: -``` +```yaml - queries: my-custom-queries - include: kind: problem @@ -226,7 +227,7 @@ To create a suite that selects all queries with `@kind problem` from the `my-custom-queries` directory except those with `@problem.severity recommendation`, use: -``` +```yaml - queries: my-custom-queries - include: kind: problem @@ -238,7 +239,7 @@ To create a suite that selects all queries with `@tag security` and `@problem.severity high` or `very-high` from the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack, use: -``` +```yaml - queries: . from: codeql/cpp-queries - include: @@ -262,7 +263,7 @@ Existing query suite definitions can be reused by specifying: - An `import` instruction—adds the queries selected by a previously defined `.qls` file to the current suite: - ``` + ```yaml - import: ``` @@ -270,7 +271,7 @@ previously defined `.qls` file to the current suite: current suite definition. If the imported query suite is in a different QL pack you can use: - ``` + ```yaml - import: from: version: ^x.y.z @@ -288,7 +289,7 @@ applied `.qls` file are executed as if they appear in place of `apply`. Any `include` and `exclude` instructions from the applied suite also act on queries added by any earlier instructions: - ``` + ```yaml - apply: ``` @@ -302,7 +303,7 @@ To use the same conditions in multiple query suite definitions, create a separate `.yml` file containing your instructions. For example, save the following in a file called `reusable-instructions.yml`: -``` +```yaml - include: kind: - problem @@ -317,7 +318,7 @@ Add `reusable-instructions.yml` to the same {% data variables.product.prodname_c suite. Then, in one or more query suites, use the `apply` instruction to apply the reusable instructions to the current suite. For example: -``` +```yaml - queries: queries/cpp/custom - apply: reusable-instructions.yml ``` @@ -329,7 +330,7 @@ queries in a different {% data variables.product.prodname_codeql %} pack. If the the queries, you can add a `from` field immediately after the `apply` instruction: -``` +```yaml # load queries from the default suite of my-org/my-other-custom-queries - qlpack: my-org/my-other-custom-queries @@ -343,7 +344,7 @@ A common use case for an `import` instruction is to apply a further filter to qu query suite. For example, this suite will further filter the `cpp-security-and-quality` suite and exclude `low` and `medium` precision queries: -``` +```yaml - import: codeql-suites/cpp-security-and-quality.qls from: codeql/cpp-queries - exclude: @@ -354,7 +355,7 @@ and exclude `low` and `medium` precision queries: If you want to `include` queries imported from another suite, the syntax is a little different: -``` +```yaml - import: codeql-suites/cpp-security-and-quality.qls from: codeql/cpp-queries - exclude: {} @@ -372,7 +373,7 @@ instruction is able to filter queries from the imported suite. You can provide a name for your query suite by specifying a `description` instruction: -``` +```yaml - description: ``` @@ -384,7 +385,7 @@ directory. For more information, see "[Specifying well-known query suites](#spec ## Saving a query suite Save your query suite in a file with a `.qls` extension and add it to a CodeQL -pack. For more information, see "[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs#custom-codeql-packs)." +pack. For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs)." ## Specifying well-known query suites @@ -395,7 +396,7 @@ without providing their full path. This gives you a simple way of specifying a set of queries, without needing to search inside {% data variables.product.prodname_codeql %} packs and distributions. To declare a directory that contains "well-known" query suites, add the directory to the `suites` property in the `qlpack.yml` file at the root of your {% data variables.product.prodname_codeql %} pack. -For more information, see "[About {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs#codeqlpack-yml-properties)." +For more information, see "[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#codeqlpack-yml-properties)." {% endif %} ## Using query suites with CodeQL @@ -404,7 +405,7 @@ You can specify query suites on the command line for any command that accepts `.qls` files. For example, you can compile the queries selected by a suite definition using `query compile`, or use the queries in an analysis using `database analyze`. For more information about analyzing {% data variables.product.prodname_codeql %} databases, see -"[Analyzing databases with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli)." +"[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries)." ## Further reading diff --git a/content/code-security/codeql-cli/codeql-cli-reference/exit-codes.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md similarity index 98% rename from content/code-security/codeql-cli/codeql-cli-reference/exit-codes.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md index 2700b00548..817c2167cd 100644 --- a/content/code-security/codeql-cli/codeql-cli-reference/exit-codes.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md @@ -13,6 +13,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/exit-codes + - /code-security/codeql-cli/codeql-cli-reference/exit-codes --- {% data reusables.codeql-cli.codeql-site-migration-note %} diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/extractor-options.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md similarity index 99% rename from content/code-security/codeql-cli/using-the-codeql-cli/extractor-options.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md index 790ecec45b..c0ce624c2a 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/extractor-options.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md @@ -13,6 +13,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/extractor-options + - /code-security/codeql-cli/using-the-codeql-cli/extractor-options --- diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/index.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md similarity index 70% rename from content/code-security/codeql-cli/using-the-codeql-cli/index.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md index 1cf0a10f8f..b4b3e1cef6 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/index.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md @@ -1,7 +1,8 @@ --- -title: Using the CodeQL CLI +title: Using the advanced functionality of the CodeQL CLI intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to locally develop, test and run CodeQL queries on software projects.' product: '{% data reusables.gated-features.codeql %}' +shortTitle: Advanced functionality versions: fpt: '*' ghes: '*' @@ -10,12 +11,9 @@ versions: topics: - Advanced Security - Code scanning + - CodeQL children: - - /about-the-codeql-cli - - /getting-started-with-the-codeql-cli - - /creating-codeql-databases - - /extractor-options - - /analyzing-databases-with-the-codeql-cli + - /about-codeql-workspaces - /using-custom-queries-with-the-codeql-cli - /creating-codeql-query-suites - /testing-custom-queries @@ -23,5 +21,11 @@ children: - /creating-and-working-with-codeql-packs - /publishing-and-using-codeql-packs - /specifying-command-options-in-a-codeql-configuration-file + - /query-reference-files + - /sarif-output + - /extractor-options + - /exit-codes +redirect_from: + - /code-security/codeql-cli/codeql-cli-reference --- diff --git a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md similarity index 53% rename from content/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md index 358b02dbc9..a463eea54e 100644 --- a/content/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md @@ -1,6 +1,6 @@ --- -title: About CodeQL packs -intro: 'You can use {% data variables.product.prodname_codeql %} packs to run {% data variables.product.prodname_codeql %} queries maintained by other people, or to share {% data variables.product.prodname_codeql %} queries that you''ve developed.' +title: Publishing and using CodeQL packs +intro: 'You can publish your own {% data variables.product.prodname_codeql %} packs and use packs published by other people.' product: '{% data reusables.gated-features.codeql %}' versions: feature: codeql-packs @@ -9,52 +9,181 @@ topics: - Code scanning - CodeQL redirect_from: - - /code-security/codeql-cli/about-codeql-packs + - /code-security/codeql-cli/publishing-and-using-codeql-packs + - /code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs --- {% data reusables.codeql-cli.codeql-site-migration-note %} {% data reusables.codeql-cli.beta-note-package-management %} -## About {% data variables.product.prodname_codeql %} packs +## Configuring the `qlpack.yml` file before publishing {% data reusables.code-scanning.codeql-cli-version-ghes %} -{% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. You can publish your own {% data variables.product.prodname_codeql %} packs and download packs created by others. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata. +You can check and modify the configuration details of your {% data variables.product.prodname_codeql %} pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor. -There are two types of {% data variables.product.prodname_codeql %} packs: query packs and library packs. +```yaml +library: # set to true if the pack is a library. Set to false or omit for a query pack +name: / +version: +description: +default-suite: # optional, one or more queries in the pack to run by default + - query: /query-file>.ql +default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack +license: # optional, the license under which the pack is published +dependencies: # map from CodeQL pack name to version range +``` +- `name:` must follow the `/` format, where `` is the {% data variables.product.prodname_dotcom %} organization that you will publish to and is the name for the pack. -- Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and {% ifversion query-pack-compatibility %}pre-compiled representations of each query, in addition to the query sources{% else %}a compilation cache{% endif %}. This ensures consistent and efficient execution of the queries in the pack. +- A maximum of one of `default-suite` or `default-suite-file` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the qlpack.yml file and the second by specifying a query suite in the pack. -- Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled {% ifversion query-pack-compatibility %}separately{% else %}and there is no compilation cache included when the pack is published{% endif %}. +## Running `codeql pack publish` -You can use the package management commands in the {% data variables.product.prodname_codeql_cli %} to create {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. For more information, see "[Creating and working with {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs#creating-and-working-with-codeql-packs)." You can also publish and download {% data variables.product.prodname_codeql %} packs using the {% data variables.product.prodname_codeql_cli %}. For more information, see "[Publishing and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs)." +When you are ready to publish a pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can run the following command in the root of the pack directory: -The standard {% data variables.product.prodname_codeql %} packages for all supported languages are published in the [{% data variables.product.prodname_container_registry %}](https://github.com/orgs/codeql/packages). -The [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql) contains source files for the standard {% data variables.product.prodname_codeql %} packs for all supported languages. +```shell +codeql pack publish +``` -## {% data variables.product.prodname_codeql %} pack structure +The published package will be displayed in the packages section of {% data variables.product.prodname_dotcom %} organization specified by the scope in the `qlpack.yml` file. -A {% data variables.product.prodname_codeql %} pack must contain a file called `qlpack.yml` in its root directory. In the `qlpack.yml` file, the `name:` field must have a value that follows the format of `/`, where `` is the {% data variables.product.prodname_dotcom %} organization or user account that the pack will be published to and `` is the name of the pack. Additionally, query packs and library packs with {% data variables.product.prodname_codeql %} tests contain a `codeql-pack.lock.yml` file that contains the resolved dependencies of the pack. This file is generated during a call to the `codeql pack install` command, is not meant to be edited by hand, and should be added to your version control system. +## Running `codeql pack download /` -The other files and directories within the pack should be logically organized. For example, typically: +To run a pack that someone else has created, you must first download it by running the following command: -- Queries are organized into directories for specific categories. +```shell +codeql pack download /@x.x.x +``` -- Queries for specific products, libraries, and frameworks are organized into -their own top-level directories. +- ``: the name of the {% data variables.product.prodname_dotcom %} organization that you will download from. +- ``: the name for the pack that you want to download. +- `@x.x.x`: an optional version number. If omitted, the latest version will be downloaded. + +This command accepts arguments for multiple packs. {% ifversion query-pack-compatibility %} +If you write scripts that specify a particular version number of a +query pack to download, keep in mind that when you update your version of +{% data variables.product.prodname_codeql %} to a newer one, you may +also need to switch to a newer version of the query pack. Newer +versions of {% data variables.product.prodname_codeql %} _may_ provide +degraded performance when used with query packs that have been pinned +to a very old version. For more information, see "[About {% data variables.product.prodname_codeql %} +pack compatibility](#about-codeql-pack-compatibility)." +{% endif %} -### About published packs +## Using a {% data variables.product.prodname_codeql %} pack to analyze a {% data variables.product.prodname_codeql %} database -When a pack is published for use in analyses, the `codeql pack create` or `codeql pack publish` command verifies that the content is complete and also adds some additional pieces of content to it: - -- For query packs, a copy of each of the library packs it depends on, in the precise versions it has been developed with. Users of the query pack won't need to download these library packs separately. +To analyze a {% data variables.product.prodname_codeql %} database with a {% data variables.product.prodname_codeql %} pack, run the following command: -- For query packs, precompiled representations of each of the queries. These are faster to execute than it would be to compile the QL source for the query at each analysis. +```shell +codeql database analyze /@x.x.x: +``` + +- ``: the {% data variables.product.prodname_codeql %} database to be analyzed. +- ``: the name of the {% data variables.product.prodname_dotcom %} organization that the pack is published to. +- ``: the name for the pack that you are using. +- `@x.x.x`: an optional version number. If omitted, the latest version will be used. +- `:`: an optional path to a query, directory, or query suite. If omitted, the pack’s default query suite will be used. + +The `analyze` command will run the default suite of any specified {% data variables.product.prodname_codeql %} packs. You can specify multiple {% data variables.product.prodname_codeql %} packs to be used for analyzing a {% data variables.product.prodname_codeql %} database. For example: + +```shell +codeql analyze / / +``` + +{% ifversion query-pack-compatibility %} +{% note %} + +**Note:** The `codeql pack download` command stores the pack it downloads in an internal location that is not intended for local modification. Unexpected (and hard to troubleshoot) behavior may result if the pack is modified after downloading. For more information about customizing packs, see "[Creating and working with {% data variables.product.prodname_codeql %} packs](#creating-and-working-with-codeql-packs)." + +{% endnote %} + +## About {% data variables.product.prodname_codeql %} pack compatibility + +When a query pack is published, it includes pre-compiled representations of all the queries in it. These pre-compiled queries are generally much faster to execute than it is to compile the QL source from scratch during the analysis. However, the pre-compiled queries also depend on certain internals of the QL evaluator, so if the version of {% data variables.product.prodname_codeql %} that performs the analysis is too different from the version that ran `codeql pack publish`, it may be necessary to compile the queries from source instead during analysis. The recompilation happens automatically and will not affect the _results_ of the analysis, but it can make the +analysis significantly slower. + +It can generally be assumed that if a pack is published with one release of {% data variables.product.prodname_codeql %}, the precompiled queries in it can be used directly by _later_ releases of {% data variables.product.prodname_codeql %}, as long as there is no more than 6 months between the release dates. We will make reasonable efforts to keep new releases compatible for longer than that, but make no promises. + +It can also be assumed that a pack published by the _latest_ public release of {% data variables.product.prodname_codeql %} will be useable by the version of {% data variables.product.prodname_codeql %} that is used by {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_actions %}, even though that is often a slightly older release. + +As an exception to the above, packs published with versions of {% data variables.product.prodname_codeql %} _earlier than 2.12.0_ are not compatible with any earlier or later versions. These old versions did not write pre-compiled queries in a format that supported compatibility between releases. Packs published by these versions can still be _used_ by newer versions, but the analysis will be slower because the queries have to be recompiled first. + +As a user of a published query pack, you can check that the {% data variables.product.prodname_codeql %} makes use of the precompiled queries in it by inspecting the terminal output from an analysis runs that uses the query pack. If it contains lines looking like the following, then the precompiled queries were used successfully: + +```shell +[42/108] Loaded /long/path/to/query/Filename.qlx. +``` + +However, if they instead look like the following, then usage of the precompiled queries failed: + +```shell +Compiling query plan for /long/path/to/query/Filename.ql. +[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql. +``` + +The results of the analysis will still be good in this case, but to get optimal performance you may need to upgrade to a newer version of the {% data variables.product.prodname_codeql %} CLI and/or of the query pack. + +If you publish query packs on the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} for others to use, we recommend that you use a recent release of {% data variables.product.prodname_codeql %} to run `codeql pack publish`, and that you publish a fresh version of your pack with an updated {% data variables.product.prodname_codeql %} version before the version you used turns 6 months old. That way you can ensure that users of your pack who keep _their_ {% data variables.product.prodname_codeql %} up to date will benefit from the pre-compiled queries in your pack. + +If you publish query packs with the intention of using them on a {% data variables.product.prodname_ghe_server %} installation that uses its bundled {% data variables.product.prodname_codeql %} binaries, use the same {% data variables.product.prodname_codeql %} version to run `codeql pack publish`. Newer versions might produce pre-compiled queries that the one in {% data variables.product.prodname_ghe_server %} may not recognize. Your {% data variables.product.prodname_ghe_server %} administrator may choose to upgrade to a newer version of {% data variables.product.prodname_codeql %} periodically. If so, follow their lead. + +{% endif %} + +{% ifversion ghes %} + +## Working with {% data variables.product.prodname_codeql %} packs on {% data variables.product.prodname_ghe_server %} + +By default, the {% data variables.product.prodname_codeql_cli %} expects to download {% data variables.product.prodname_codeql %} packs from and publish packs to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. However, you can also work with {% data variables.product.prodname_codeql %} packs in a {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_ghe_server %} by creating a `qlconfig.yml` file to tell the CLI which {% data variables.product.prodname_container_registry %} to use for each pack. + +Create a `~/.codeql/qlconfig.yml` file using your preferred text editor, and add entries to specify which registry to use for one or more package name patterns. +For example, the following `qlconfig.yml` file associates all packs with the {% data variables.product.prodname_container_registry %} for the {% data variables.product.prodname_ghe_server %} at `GHE_HOSTNAME`, except packs matching `codeql/\*`, which are associated with the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}: + +```yaml +registries: +- packages: + - 'codeql/*' + - 'other-org/*' + url: https://ghcr.io/v2/ +- packages: '*' + url: https://containers.GHE_HOSTNAME/v2/ +``` + +The {% data variables.product.prodname_codeql_cli %} will determine which registry to use for a given package name by finding the first item in the `registries` list with a `packages` property that matches that package name. +This means that you’ll generally want to define the most specific package name patterns first. The `packages` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns. + +The `registries` list can also be placed inside of a `codeql-workspace.yml` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other {% data variables.product.prodname_codeql %} users of the workspace. The `registries` list in the `codeql-workspace.yml` will be merged with and take precedence over the list in the global `qlconfig.yml`. For more information about `codeql-workspace.yml`, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces)." + +You can now use `codeql pack publish`, `codeql pack download`, and `codeql database analyze` to manage packs on {% data variables.product.prodname_ghe_server %}. + +{% endif %} + +## Authenticating to {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registries %} + +You can publish packs and download private packs by authenticating to the appropriate {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}. + +You can authenticate to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} in two ways: + +1. Pass the `--github-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} via standard input. +1. Set the `GITHUB_TOKEN` environment variable to a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %}. + +{% ifversion ghes %} + +Similarly, you can authenticate to a {% data variables.product.prodname_ghe_server %} {% data variables.product.prodname_container_registry %}, or authenticate to multiple registries simultaneously (for example, to download or run private packs from multiple registries) in two ways: + +1. Pass the `--registries-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a registry authentication string via standard input. +1. Set the `CODEQL_REGISTRIES_AUTH` environment variable to a registry authentication string. + +A registry authentication string is a comma-separated list of `=` pairs, where `registry-url` is a {% data variables.product.prodname_container_registry %} URL, such as `https://containers.GHE_HOSTNAME/v2/`, and `token` is a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} for that {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}. +This ensures that each token is only passed to the {% data variables.product.prodname_container_registry %} you specify. +For instance, the following registry authentication string specifies that the {% data variables.product.prodname_codeql_cli %} should authenticate to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} using the token `` and to the {% data variables.product.prodname_container_registry %} for the GHES instance at `GHE_HOSTNAME` using the token ``: + +```shell +https://ghcr.io/v2/=,https://containers.GHE_HOSTNAME/v2/= +``` -Most of this data is located in a directory named `.codeql` in the published pack, but precompiled queries are in files with a `.qlx` suffix next to the `.ql` source for each query. When analyzing a database with a query from a published pack, {% data variables.product.prodname_codeql %} will load these files instead of the `.ql` source. If you need to modify the content of a _published_ pack, be sure to remove all of the `.qlx` files, since they may prevent modifications in the `.ql` files from taking effect. {% endif %} ## About `qlpack.yml` files @@ -78,7 +207,6 @@ The following properties are supported in `qlpack.yml` files. - Required by all packs. - Defines the scope of the pack, where the {% data variables.product.prodname_codeql %} pack is published, and the name of the pack defined using alphanumeric characters and hyphens. It must be unique as {% data variables.product.prodname_codeql %} cannot differentiate between {% data variables.product.prodname_codeql %} packs with identical names. Use the pack name to specify queries to run using `database analyze` and to define dependencies between {% data variables.product.prodname_codeql %} packs (see examples below). For example: - ```yaml name: octo-org/security-queries ``` @@ -87,7 +215,6 @@ The following properties are supported in `qlpack.yml` files. - Required by all packs that are published. - Defines a semantic version for this {% data variables.product.prodname_codeql %} pack that must adhere to the [SemVer v2.0.0 specification](https://semver.org/spec/v2.0.0.html). For example: - ```yaml version: 0.0.0 ``` @@ -96,7 +223,6 @@ The following properties are supported in `qlpack.yml` files. - Required by packs that define {% data variables.product.prodname_codeql %} package dependencies on other packs. - Defines a map from pack references to the semantic version range that is compatible with this pack. Supported for {% data variables.product.prodname_codeql_cli %} versions v2.6.0 and later. For example: - ```yaml dependencies: codeql/cpp-all: ^0.0.2 @@ -106,7 +232,6 @@ The following properties are supported in `qlpack.yml` files. - Required by packs that export a set of default queries to run. - Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the `codeql database analyze` command. Supported from CLI version v2.6.0 and onwards. Only one of `defaultSuiteFile` or `defaultSuite` can be defined. For example: - ```yaml defaultSuiteFile: cpp-code-scanning.qls ``` @@ -115,7 +240,6 @@ The following properties are supported in `qlpack.yml` files. - Required by packs that export a set of default queries to run. - Defines an inlined query suite containing all of the queries that are run by default when this pack is passed to the `codeql database analyze` command. Supported from CLI version v2.6.0 and onwards. Only one of `defaultSuiteFile` or `defaultSuite` can be defined. For example: - ```yaml defaultSuite: queries: . @@ -127,7 +251,6 @@ The following properties are supported in `qlpack.yml` files. - Required by library packs. - Defines a boolean value that indicates whether or not this pack is a library pack. Library packs do not contain queries and are not compiled. Query packs can ignore this field or explicitly set it to `false`. For example: - ```yaml library: true ``` @@ -135,80 +258,62 @@ The following properties are supported in `qlpack.yml` files. #### `suites` - Optional for packs that define query suites. -- Defines the path to a directory in the pack that contains the query suites you want to make known to the {% data variables.product.prodname_codeql_cli %}, defined relative to the pack directory. {% data variables.product.prodname_codeql %} pack users can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. This is not supported for {% data variables.product.prodname_codeql %} packs downloaded from the Container registry. For more information about query suites, see "[Creating {% data variables.product.prodname_codeql %} query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)." For example: - +- Defines the path to a directory in the pack that contains the query suites you want to make known to the {% data variables.product.prodname_codeql_cli %}, defined relative to the pack directory. {% data variables.product.prodname_codeql %} pack users can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. This is not supported for {% data variables.product.prodname_codeql %} packs downloaded from the Container registry. For more information about query suites, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)." For example: ```yaml suites: octo-org-query-suites ``` #### `tests` - - Optional for packs containing {% data variables.product.prodname_codeql %} tests. Ignored for packs without tests. - Defines the path to a directory within the pack that contains tests, defined relative to the pack directory. Use `.` to specify the whole pack. Any queries in this directory are run as tests when `test run` is run with the `--strict-test-discovery` option. These queries are ignored by query suite definitions that use `queries` or `qlpack` instructions to ask for all queries in a particular pack. If this property is missing, then `.` is assumed. For example: - ```yaml tests: . ``` #### `extractor` - - Required by all packs containing {% data variables.product.prodname_codeql %} tests. -- Defines the {% data variables.product.prodname_codeql %} language extractor to use when running the {% data variables.product.prodname_codeql %} tests in the pack. For more information about testing queries, see "[Testing custom queries](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries)." For example: - +- Defines the {% data variables.product.prodname_codeql %} language extractor to use when running the {% data variables.product.prodname_codeql %} tests in the pack. For more information about testing queries, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)." For example: ```yaml extractor: javascript ``` #### `authors` - - Optional. - Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For example: - ```yaml authors: author1@github.com,author2@github.com ``` #### `license` - - Optional. - Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For a list of allowed licenses, see [SPDX License List](https://spdx.org/licenses/) in the SPDX Specification. For example: - ```yaml license: MIT ``` #### `description` - - Optional. - Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For example: - ```yaml description: Human-readable description of the contents of the {% data variables.product.prodname_codeql %} pack. ``` #### `libraryPathDependencies` - - Optional, deprecated. Use the `dependencies` property instead. - Previously used to define the names of any {% data variables.product.prodname_codeql %} packs that this {% data variables.product.prodname_codeql %} pack depends on, as an array. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. For example: - ```yaml libraryPathDependencies: codeql/javascript-all ``` #### `dbscheme` - - Required by core language packs only. - Defines the path to the [database schema](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) for all libraries and queries written for this {% data variables.product.prodname_codeql %} language (see example below). For example: - ```yaml dbscheme: semmlecode.python.dbscheme ``` - #### `upgrades` - - Required by core language packs only. - Defines the path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure that a database created with a different version of the {% data variables.product.prodname_codeql_cli %} is compatible with the current version of the CLI. For example: - ```yaml upgrades: . ``` @@ -216,7 +321,6 @@ The following properties are supported in `qlpack.yml` files. #### `warnOnImplicitThis` - Optional. Defaults to `false` if the `warnOnImplicitThis` property is not defined. - Defines a boolean that specifies whether or not the compiler should emit warnings about member predicate calls with implicit `this` call receivers, that is, without an explicit receiver. Supported from {% data variables.product.prodname_codeql_cli %} version 2.13.2 and onwards. For example: - ```yaml warnOnImplicitThis: true ``` @@ -246,7 +350,7 @@ dependencies: version: 1.2.4 ``` -The `codeql/cpp-all` dependency is locked to version 0.1.4. The `my-user/my-lib` dependency is locked to version 0.2.1. The `my-user/transitive-dependency`, which is a transitive dependency and is not specified in the `qlpack.yml` file, is locked to version 1.2.4. The `other-dependency/from-source` is absent from the lock file since it is resolved from source. This dependency must be available in the same {% data variables.product.prodname_codeql %} workspace as the pack. For more information about {% data variables.product.prodname_codeql %} workspaces and resolving dependencies from source, see "[About {% data variables.product.prodname_codeql %} Workspaces](/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces)." +The `codeql/cpp-all` dependency is locked to version 0.1.4. The `my-user/my-lib` dependency is locked to version 0.2.4. The `my-user/transitive-dependency`, which is a transitive dependency and is not specified in the `qlpack.yml` file, is locked to version 1.2.4. The `other-dependency/from-source` is absent from the lock file since it is resolved from source. This dependency must be available in the same {% data variables.product.prodname_codeql %} workspace as the pack. For more information about {% data variables.product.prodname_codeql %} workspaces and resolving dependencies from source, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces)." In most cases, the `codeql-pack.lock.yml` file is only relevant for query packs since library packs are non-executable and usually do not need their transitive dependencies to be fixed. The exception to this is for library packs that contain tests. In this case, the `codeql-pack.lock.yml` file is used to ensure that the tests are always run with the same versions of dependencies to avoid spurious failures when there are mismatched dependencies. @@ -285,7 +389,7 @@ suites: my-custom-suites where `codeql/cpp-all` is the name of the {% data variables.product.prodname_codeql %} pack for C/C++ analysis included in the {% data variables.product.prodname_codeql %} repository. The version range `^0.1.2` indicates that this pack is compatible with all versions of `codeql/cpp-all` that are greater than or equal to `0.1.2` and less than `0.2.0`. `my-github-user/my-custom-libraries` is the name of a {% data variables.product.prodname_codeql %} pack containing custom {% data variables.product.prodname_codeql %} libraries for C++. Any {% data variables.product.prodname_codeql %} library file (a file with a `.qll` extension) defined in this pack will be available to queries in the `my-github-user/my-custom-queries` pack. -The `suites` property indicates a directory where "well-known" query suites can be found. These suites can be used on the command line by referring to their name only, rather than their full path. For more information about query suites, see "[Creating {% data variables.product.prodname_codeql %} query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites)." +The `suites` property indicates a directory where "well-known" query suites can be found. These suites can be used on the command line by referring to their name only, rather than their full path. For more information about query suites, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)." ### {% data variables.product.prodname_codeql %} packs for custom tests @@ -295,7 +399,7 @@ databases. You may also wish to specify the `tests` property. {% data reusables.codeql-cli.test-qlpack %} -For more information about running tests, see "[Testing custom queries](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries)." +For more information about running tests, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)." ## Examples of {% data variables.product.prodname_codeql %} packs in the {% data variables.product.prodname_codeql %} repository @@ -347,7 +451,7 @@ defaultSuiteFile: codeql-suites/cpp-code-scanning.qls Some extra notes on the following properties: -- `dependencies`: This query pack depends on `codeql/cpp-all` and `codeql/suite-helpers`. Since these dependencies are resolved from source, it does not matter what version of the {% data variables.product.prodname_codeql %} pack they are compatible with. For more information about resolving dependencies from source, see "[Source Dependencies](/code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces#source-dependencies)." +- `dependencies`: This query pack depends on `codeql/cpp-all` and `codeql/suite-helpers`. Since these dependencies are resolved from source, it does not matter what version of the {% data variables.product.prodname_codeql %} pack they are compatible with. For more information about resolving dependencies from source, see "[Source Dependencies](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies)." - `suites`: Indicates the directory containing "well-known" query suites. @@ -375,4 +479,4 @@ Some extra notes on the following properties: - `tests`: This specifies the location of the tests. In this case, the tests are in the root folder (and all sub-folders) of the pack. -- `version`: There is no `version` property for the tests pack. This prevents test packs from accidentally being published. +- `version`: There is no `version` property for the tests pack. This prevents test packs from accidentally being published. \ No newline at end of file diff --git a/content/code-security/codeql-cli/codeql-cli-reference/query-reference-files.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md similarity index 92% rename from content/code-security/codeql-cli/codeql-cli-reference/query-reference-files.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md index e1f1b1c3c1..9b093cbe70 100644 --- a/content/code-security/codeql-cli/codeql-cli-reference/query-reference-files.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md @@ -13,6 +13,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/query-reference-files + - /code-security/codeql-cli/codeql-cli-reference/query-reference-files --- {% data reusables.codeql-cli.codeql-site-migration-note %} @@ -56,10 +57,10 @@ for the CodeQL pack at `javascript/ql/test` defines `codeql/javascript-queries` a dependency. So the query reference file defines the location of the query relative to the `codeql/javascript-queries` {% data variables.product.prodname_codeql %} pack: -``` +```shell AngularJS/DeadAngularJSEventListener.ql ``` {% ifversion codeql-packs %} -For another example, see [Testing custom queries](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries). +For another example, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)." {% endif %} diff --git a/content/code-security/codeql-cli/codeql-cli-reference/sarif-output.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md similarity index 99% rename from content/code-security/codeql-cli/codeql-cli-reference/sarif-output.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md index 2388284d94..15393196e1 100644 --- a/content/code-security/codeql-cli/codeql-cli-reference/sarif-output.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md @@ -14,6 +14,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/sarif-output + - /code-security/codeql-cli/codeql-cli-reference/sarif-output --- {% data reusables.codeql-cli.codeql-site-migration-note %} diff --git a/content/code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md similarity index 95% rename from content/code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md rename to content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md index a88c3bfe87..3336a13db6 100644 --- a/content/code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md @@ -13,6 +13,7 @@ topics: - CodeQL redirect_from: - /code-security/codeql-cli/specifying-command-options-in-a-codeql-configuration-file + - /code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file --- {% data reusables.codeql-cli.codeql-site-migration-note %} @@ -34,7 +35,7 @@ You need to save the `config` file under your home (Linux and macOS) or user pro The syntax for specifying options is as follows: -``` +```shell