On ci skip if /docs folder has no docset.yml silently

action.yml

@@ -12,6 +12,9 @@ inputs:
   strict:
     description: 'Treat warnings as errors'
     required: false
+outputs:
+  skip:
+    description: "hint from the documentation tool to skip the docs build for this PR"
 
 runs:
   using: 'docker'

src/docs-builder/Cli/Commands.cs

@@ -74,12 +74,36 @@ public async Task<int> Generate(
 		pathPrefix ??= githubActionsService.GetInput("prefix");
 		var fileSystem = new FileSystem();
 		var collector = new ConsoleDiagnosticsCollector(logger, githubActionsService);
-		var context = new BuildContext(collector, fileSystem, fileSystem, path, output)
+
+		var runningOnCi = !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS"));
+		BuildContext context;
+		try
+		{
+			context = new BuildContext(collector, fileSystem, fileSystem, path, output)
+			{
+				UrlPathPrefix = pathPrefix,
+				Force = force ?? false,
+				AllowIndexing = allowIndexing != null
+			};
+		}
+		// On CI, we are running on merge commit which may have changes against an older
+		// docs folder (this can happen on out of date PR's).
+		// At some point in the future we can remove this try catch
+		catch (Exception e) when (runningOnCi && e.Message.StartsWith("Can not locate docset.yml file in"))
 		{
-			UrlPathPrefix = pathPrefix,
-			Force = force ?? false,
-			AllowIndexing = allowIndexing != null
-		};
+			var outputDirectory = !string.IsNullOrWhiteSpace(output)
+				? fileSystem.DirectoryInfo.New(output)
+				: fileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName, ".artifacts/docs/html"));
+			// we temporarily do not error when pointed to a non documentation folder.
+			_ = fileSystem.Directory.CreateDirectory(outputDirectory.FullName);
+
+			ConsoleApp.Log($"Skipping build as we are running on a merge commit and the docs folder is out of date and has no docset.yml. {e.Message}");
+
+			await githubActionsService.SetOutputAsync("skip", "true");
+			return 0;
+		}
+		if (runningOnCi)
+			await githubActionsService.SetOutputAsync("skip", "false");
 		var set = new DocumentationSet(context, logger);
 		var generator = new DocumentationGenerator(set, logger);
 		await generator.GenerateAll(ctx);