@@ -201,6 +201,18 @@ export interface AugmentationProperties {
201
201
* The overlay database mode to use.
202
202
*/
203
203
overlayDatabaseMode : OverlayDatabaseMode ;
204
+
205
+ /**
206
+ * Whether to use caching for overlay databases. If it is true, the action
207
+ * will upload the created overlay-base database to the actions cache, and
208
+ * download an overlay-base database from the actions cache before it creates
209
+ * a new overlay database. If it is false, the action assumes that the
210
+ * workflow will be responsible for managing database storage and retrieval.
211
+ *
212
+ * This property has no effect unless `overlayDatabaseMode` is `Overlay` or
213
+ * `OverlayBase`.
214
+ */
215
+ useOverlayDatabaseCaching : boolean ;
204
216
}
205
217
206
218
/**
@@ -215,6 +227,7 @@ export const defaultAugmentationProperties: AugmentationProperties = {
215
227
qualityQueriesInput : undefined ,
216
228
extraQueryExclusions : [ ] ,
217
229
overlayDatabaseMode : OverlayDatabaseMode . None ,
230
+ useOverlayDatabaseCaching : false ,
218
231
} ;
219
232
export type Packs = Partial < Record < Language , string [ ] > > ;
220
233
@@ -693,15 +706,19 @@ export async function calculateAugmentation(
693
706
rawQueriesInput ,
694
707
queriesInputCombines ,
695
708
) ;
696
- const overlayDatabaseMode = await getOverlayDatabaseMode (
697
- codeql ,
698
- repository ,
699
- features ,
700
- sourceRoot ,
701
- buildMode ,
702
- logger ,
709
+ const { overlayDatabaseMode, useOverlayDatabaseCaching } =
710
+ await getOverlayDatabaseMode (
711
+ codeql ,
712
+ repository ,
713
+ features ,
714
+ sourceRoot ,
715
+ buildMode ,
716
+ logger ,
717
+ ) ;
718
+ logger . info (
719
+ `Using overlay database mode: ${ overlayDatabaseMode } ` +
720
+ `${ useOverlayDatabaseCaching ? "with" : "without" } caching.` ,
703
721
) ;
704
- logger . info ( `Using overlay database mode: ${ overlayDatabaseMode } ` ) ;
705
722
706
723
const qualityQueriesInput = parseQueriesFromInput (
707
724
rawQualityQueriesInput ,
@@ -723,6 +740,7 @@ export async function calculateAugmentation(
723
740
qualityQueriesInput,
724
741
extraQueryExclusions,
725
742
overlayDatabaseMode,
743
+ useOverlayDatabaseCaching,
726
744
} ;
727
745
}
728
746
@@ -750,17 +768,25 @@ function parseQueriesFromInput(
750
768
}
751
769
752
770
/**
753
- * Calculate and validate the overlay database mode to use.
771
+ * Calculate and validate the overlay database mode and caching to use.
754
772
*
755
773
* - If the environment variable `CODEQL_OVERLAY_DATABASE_MODE` is set, use it.
774
+ * In this case, the workflow is responsible for managing database storage and
775
+ * retrieval, and the action will not perform overlay database caching. Think
776
+ * of it as a "manual control" mode where the calling workflow is responsible
777
+ * for making sure that everything is set up correctly.
756
778
* - Otherwise, if `Feature.OverlayAnalysis` is enabled, calculate the mode
757
- * based on what we are analyzing.
758
- * - If we are analyzing a pull request, use `Overlay`.
759
- * - If we are analyzing the default branch, use `OverlayBase`.
779
+ * based on what we are analyzing. Think of it as a "automatic control" mode
780
+ * where the action will do the right thing by itself.
781
+ * - If we are analyzing a pull request, use `Overlay` with caching.
782
+ * - If we are analyzing the default branch, use `OverlayBase` with caching.
760
783
* - Otherwise, use `None`.
761
784
*
762
785
* For `Overlay` and `OverlayBase`, the function performs further checks and
763
786
* reverts to `None` if any check should fail.
787
+ *
788
+ * @returns An object containing the overlay database mode and whether the
789
+ * action should perform overlay-base database caching.
764
790
*/
765
791
async function getOverlayDatabaseMode (
766
792
codeql : CodeQL ,
@@ -769,8 +795,12 @@ async function getOverlayDatabaseMode(
769
795
sourceRoot : string ,
770
796
buildMode : BuildMode | undefined ,
771
797
logger : Logger ,
772
- ) : Promise < OverlayDatabaseMode > {
798
+ ) : Promise < {
799
+ overlayDatabaseMode : OverlayDatabaseMode ;
800
+ useOverlayDatabaseCaching : boolean ;
801
+ } > {
773
802
let overlayDatabaseMode = OverlayDatabaseMode . None ;
803
+ let useOverlayDatabaseCaching = false ;
774
804
775
805
const modeEnv = process . env . CODEQL_OVERLAY_DATABASE_MODE ;
776
806
// Any unrecognized CODEQL_OVERLAY_DATABASE_MODE value will be ignored and
@@ -791,21 +821,28 @@ async function getOverlayDatabaseMode(
791
821
) {
792
822
if ( isAnalyzingPullRequest ( ) ) {
793
823
overlayDatabaseMode = OverlayDatabaseMode . Overlay ;
824
+ useOverlayDatabaseCaching = true ;
794
825
logger . info (
795
826
`Setting overlay database mode to ${ overlayDatabaseMode } ` +
796
- "because we are analyzing a pull request." ,
827
+ "with caching because we are analyzing a pull request." ,
797
828
) ;
798
829
} else if ( await isAnalyzingDefaultBranch ( ) ) {
799
830
overlayDatabaseMode = OverlayDatabaseMode . OverlayBase ;
831
+ useOverlayDatabaseCaching = true ;
800
832
logger . info (
801
833
`Setting overlay database mode to ${ overlayDatabaseMode } ` +
802
- "because we are analyzing the default branch." ,
834
+ "with caching because we are analyzing the default branch." ,
803
835
) ;
804
836
}
805
837
}
806
838
839
+ const nonOverlayAnalysis = {
840
+ overlayDatabaseMode : OverlayDatabaseMode . None ,
841
+ useOverlayDatabaseCaching : false ,
842
+ } ;
843
+
807
844
if ( overlayDatabaseMode === OverlayDatabaseMode . None ) {
808
- return OverlayDatabaseMode . None ;
845
+ return nonOverlayAnalysis ;
809
846
}
810
847
811
848
if ( buildMode !== BuildMode . None ) {
@@ -814,26 +851,29 @@ async function getOverlayDatabaseMode(
814
851
`build-mode is set to "${ buildMode } " instead of "none". ` +
815
852
"Falling back to creating a normal full database instead." ,
816
853
) ;
817
- return OverlayDatabaseMode . None ;
854
+ return nonOverlayAnalysis ;
818
855
}
819
856
if ( ! ( await codeQlVersionAtLeast ( codeql , CODEQL_OVERLAY_MINIMUM_VERSION ) ) ) {
820
857
logger . warning (
821
858
`Cannot build an ${ overlayDatabaseMode } database because ` +
822
859
`the CodeQL CLI is older than ${ CODEQL_OVERLAY_MINIMUM_VERSION } . ` +
823
860
"Falling back to creating a normal full database instead." ,
824
861
) ;
825
- return OverlayDatabaseMode . None ;
862
+ return nonOverlayAnalysis ;
826
863
}
827
864
if ( ( await getGitRoot ( sourceRoot ) ) === undefined ) {
828
865
logger . warning (
829
866
`Cannot build an ${ overlayDatabaseMode } database because ` +
830
867
`the source root "${ sourceRoot } " is not inside a git repository. ` +
831
868
"Falling back to creating a normal full database instead." ,
832
869
) ;
833
- return OverlayDatabaseMode . None ;
870
+ return nonOverlayAnalysis ;
834
871
}
835
872
836
- return overlayDatabaseMode ;
873
+ return {
874
+ overlayDatabaseMode,
875
+ useOverlayDatabaseCaching,
876
+ } ;
837
877
}
838
878
839
879
/**
0 commit comments