Document public reuseable workflow

Author: JohT

.github/workflows/internal-check-links-in-documentation.yml

@@ -9,6 +9,7 @@ on:
       - 'README.md'
       - 'COMMANDS.md'
       - 'GETTING_STARTED.md'
+      - 'INTEGRATION.md'
       - '.github/workflows/check-links-in-documentation.yml' # also run when this file was changed
   schedule:
     - cron: "15 6 1 * *" # On the first day of each month at 6:15 o'clock
@@ -36,6 +37,6 @@ jobs:
 
     - name: Check links in top level documentation Markdown files
       if: ${{ ! env.skip_link_check}}
-      run: npx --yes [email protected] --verbose --alive=200,202,206 --retry README.md COMMANDS.md GETTING_STARTED.md
+      run: npx --yes [email protected] --verbose --alive=200,202,206 --retry README.md COMMANDS.md GETTING_STARTED.md INTEGRATION.md
       # Temporarily, everything is done using command line options rather than with the config file, which doesn't seem to work.
       # Maybe related to https://github.com/tcort/markdown-link-check/issues/379 ?

COMMANDS.md

@@ -193,7 +193,7 @@ Change into the [scripts](./scripts/) directory e.g. with `cd scripts` and then
 The following command shows how to use [markdown-link-check](https://github.com/tcort/markdown-link-check) to for example check the links in the [README.md](./README.md) file:
 
 ```script
-npx --yes markdown-link-check --quiet --progress --config=markdown-lint-check-config.json README.md COMMANDS.md GETTING_STARTED.md
+npx --yes markdown-link-check --quiet --progress --config=markdown-lint-check-config.json README.md COMMANDS.md GETTING_STARTED.md INTEGRATION.md
 ```
 
 ## Manual Setup

INTEGRATION.md

@@ -0,0 +1,39 @@
+# Code Graph Analysis Pipeline - Integration guide
+
+This document describes the steps to get started as quickly as possible.  
+:point_right: For more details on what else you can do see [README](./README.md).  
+:point_right: For more details on how to analyze your code locally see [GETTING_STARTED](./GETTING_STARTED.md).  
+
+## :rocket: How to use it
+
+This repository provides a reusable GitHub Actions Workflow to analyze code. The workflow is defined in [public-analyze-code-graph.yml](./.github/workflows/public-analyze-code-graph.yml).
+
+The main idea is to have three workflow jobs:
+
+1. **Collect source code and build artifacts**: Gather the source code and any build artifacts.
+2. **Run the analysis**: Use the reusable workflow to analyze the collected code and artifacts.
+3. **Download the reports**: Retrieve the analysis reports generated by the workflow.
+
+The workflow requires the names of the uploaded artifacts (source code and build artifacts) and provides the names of the artifact containing the analysis results for download.
+
+You can find examples in:
+
+- [internal-java-code-analysis.yml](./.github/workflows/internal-java-code-analysis.yml)
+- [internal-typescript-code-analysis.yml](./.github/workflows/internal-typescript-code-analysis.yml)
+
+:warning: Note: Workflows with names starting with `internal-` are private and should not be used outside this repository. They may change at any time without notice.
+
+## :gear: Parameters
+
+The workflow parameters are as follows:
+
+- **analysis-name**: The name of the project to analyze. Example: MyProject-1.0.0. This parameter is required and should be a string.
+- **artifacts-upload-name**: The name of the artifacts uploaded with [actions/upload-artifact](https://github.com/actions/upload-artifact/tree/65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08) containing the content of the 'artifacts' directory for the analysis. This is used to analyze Java JARs, WARs, EARs, etc. This parameter is optional and defaults to an empty string.
+- **sources-upload-name**: The name of the sources uploaded with [actions/upload-artifact](https://github.com/actions/upload-artifact/tree/65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08) containing the content of the 'source' directory for the analysis. It also supports sub-folders for multiple source code bases. This parameter is optional and defaults to an empty string.
+- **ref**: The branch, tag, or SHA of the code-graph-analysis-pipeline to checkout. This parameter is optional and defaults to "main".
+- **analysis-arguments**: The arguments to pass to the analysis script. This parameter is optional and defaults to '--profile Neo4jv5-low-memory'.
+- **typescript-scan-heap-memory**: The heap memory size in MB to use for the TypeScript code scans. This value is only used for the TypeScript code scans and is ignored for other scans. This parameter is optional and defaults to '4096'.
+
+The workflow also provides an output parameter:
+
+- **uploaded-analysis-results**: The name of the artifact uploaded with 'actions/upload-artifact' containing all analysis

README.md

@@ -14,6 +14,7 @@ Contained within this repository is a comprehensive and automated code graph ana
 - Fully automated [pipeline for Java](./.github/workflows/java-code-analysis.yml) from tool installation to report generation
 - Fully automated [pipeline for Typescript](./.github/workflows/typescript-code-analysis.yml) from tool installation to report generation
 - Fully automated [local run](./GETTING_STARTED.md)
+- Easy integratable in your [continuous integration pipeline](./INTEGRATION.md)
 - More than 130 CSV reports for dependencies, metrics, cycles, annotations, algorithms and many more
 - Jupyter notebook reports for dependencies, metrics, visibility and many more
 - Graph structure visualization
@@ -105,6 +106,11 @@ This could be as simple as running the following command in your Typescript proj
 
 See [GETTING_STARTED.md](./GETTING_STARTED.md) on how to get started on your local machine.
 
+## :rocket: Integration
+
+See [INTEGRATION.md](./INTEGRATION.md) on how to integrate code analysis in your continuous integration pipeline.
+Currently (2025), only GitHub Actions are supported.
+
 ## :building_construction: Pipeline and Tools
 
 The [Code Structure Analysis Pipeline](./.github/workflows/java-code-analysis.yml) utilizes [GitHub Actions](https://docs.github.com/de/actions) to automate the whole analysis process: