Flext CI/CD Integration

Relevant source files

The following files were used as context for generating this wiki page:

• examples/flext_integration_example.py
• README.md
• run_action.py
• action.yml
• core.py
• entrypoint.sh
• duplicate_code_detection.py

Flext CI/CD Integration provides a robust mechanism for automated code quality analysis by detecting duplications within Flext projects. It allows developers to set quality gates that automatically fail builds or pull requests when code similarity exceeds defined thresholds. The system is designed to be utilized either as a GitHub Action or as a standalone Python library integrated into custom automation scripts.

Sources: README.md:14-16, examples/flext_integration_example.py:87-93

Architecture and Components

The integration consists of a core detection engine, a library wrapper for programmatic access, and a dedicated GitHub Action runner. In a CI/CD environment, the tool typically executes within a Docker container to analyze the source code of a repository and report results back to the version control system.

Integration Workflow

The following diagram illustrates the flow of data from a GitHub Pull Request trigger to the final comment reporting duplications.

The entrypoint.sh script manages the environment by cloning the repository and fetching the specific pull request head before handing off execution to the Python runner.
Sources: entrypoint.sh:4-21, run_action.py:126-150

GitHub Action Configuration

The tool is configured via action.yml, which defines various inputs for controlling the analysis sensitivity and reporting behavior.

Input Parameters

Parameter	Description	Default
github_token	Required token for API authentication	N/A
directories	Comma-separated list of directories to analyze	N/A
file_extensions	Extensions to check (h, c, cpp, java, py, etc.)	h, hpp, c, cpp, cc, java, py, cs
fail_above	Maximum allowed similarity % before failing the action	100
warn_above	Similarity % that triggers a warning indicator	100
ignore_below	Minimum similarity % to be reported	10
only_code	Boolean to strip comments/docstrings before analysis	false
one_comment	If true, updates a single comment instead of creating new ones	false

Sources: action.yml:4-56

Programmatic Library Integration

Flext projects can integrate the detector directly into Python-based CI scripts using the DuplicateCodeDetector class or convenience functions. This allows for fine-grained control over which modules are analyzed (e.g., flext-core, flext-ldap).

Critical Functions and Logic

1. DuplicateCodeDetector.detect_in_directories: The primary entry point for analyzing multiple Flext modules. It takes a list of directory paths and optional ignore patterns.
   Sources: core.py:145-177
2. DetectionResult.get_critical_duplications: A utility method used in CI gates to filter results for similarities exceeding a specific threshold (e.g., 50%).
   Sources: core.py:90-99
3. remove_comments_and_docstrings: A preprocessing step that ensures the tool compares logical code rather than metadata or comments, which is crucial for accurate quality metrics in Flext projects.
   Sources: duplicate_code_detection.py:73-108

CI/CD Reporting

When running as an action, the tool generates a Markdown-formatted report containing detailed tables of file similarities. It uses the GitHub API to post these results directly to the Pull Request.

Report Generation Process

The run_action.py script transforms the raw JSON similarity data into a human-readable Markdown table. It supports a "warning suffix" (⚠️) for entries exceeding the warn_above threshold and provides links to the specific files on GitHub.

If one_comment is enabled, the script searches for an existing comment starting with the header_message_start and updates it via a PATCH request rather than creating a new one.
Sources: run_action.py:82-113, run_action.py:173-195

Integration Example

A typical Flext CI/CD implementation involves creating a script that exits with a non-zero status code if critical duplications are found, thereby blocking the pipeline.

# Example CI/CD Integration snippet
detector = DuplicateCodeDetector(
    fail_threshold=80,
    ignore_threshold=20,
    file_extensions=["py"],
    only_code=True
)

result = detector.detect_in_directories(
    directories=["../flext-core/src", "../flext-ldap/src"]
)

if not result.is_success():
    print("❌ Duplication threshold exceeded!")
    sys.exit(1)

Sources: examples/flext_integration_example.py:93-131

Conclusion

Flext CI/CD Integration ensures code maintainability by providing automated oversight of code duplication. By utilizing the DuplicateCodeDetector within GitHub Actions or custom library integrations, teams can enforce quality standards across various Flext modules, ensuring that high-similarity code is refactored rather than merged.
Sources: README.md:213-215, examples/flext_integration_example.py:214-220