CRAVEX GitLab workflow integration #346 (#374)

Signed-off-by: tdruez <tdruez@nexb.com>

Author: tdruez

CHANGELOG.rst

@@ -42,6 +42,14 @@ Release notes
   * `/products/{uuid}/imports/`
   https://github.com/aboutcode-org/dejacode/issues/273
 
+- Add GitHub workflow Request integration.
+  Documentation: https://dejacode.readthedocs.io/en/latest/integrations-github.html
+  https://github.com/aboutcode-org/dejacode/issues/349
+
+- Add GitLab workflow Request integration.
+  Documentation: https://dejacode.readthedocs.io/en/latest/integrations-github.html
+  https://github.com/aboutcode-org/dejacode/issues/346
+
 ### Version 5.3.0
 
 - Rename ProductDependency is_resolved to is_pinned.

dje/admin.py

@@ -24,6 +24,7 @@
 from django.contrib.admin.utils import unquote
 from django.contrib.admin.views.main import ChangeList
 from django.contrib.admin.widgets import AdminDateWidget
+from django.contrib.admin.widgets import AdminTextInputWidget
 from django.contrib.auth.admin import GroupAdmin
 from django.contrib.auth.admin import UserAdmin
 from django.contrib.auth.models import Group
@@ -1034,7 +1035,7 @@ def has_activity_log(self):
             return True
 
 
-class HiddenValueWidget(forms.TextInput):
+class HiddenValueWidget(AdminTextInputWidget):
     """Render a hidden value in the UI."""
 
     HIDDEN_VALUE = "*******"
@@ -1057,6 +1058,7 @@ class DataspaceConfigurationForm(forms.ModelForm):
         "vulnerablecode_api_key",
         "purldb_api_key",
         "github_token",
+        "gitlab_token",
     ]
 
     def __init__(self, *args, **kwargs):
@@ -1105,6 +1107,14 @@ class DataspaceConfigurationInline(DataspacedFKMixin, admin.StackedInline):
                 ]
             },
         ),
+        (
+            "GitLab Integration",
+            {
+                "fields": [
+                    "gitlab_token",
+                ]
+            },
+        ),
     ]
     can_delete = False
 

dje/migrations/0009_dataspaceconfiguration_gitlab_token.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.4 on 2025-07-31 10:43
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dje', '0008_dataspaceconfiguration_github_token'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='dataspaceconfiguration',
+            name='gitlab_token',
+            field=models.CharField(blank=True, help_text="Personal access token (PAT) used to authenticate API requests for the GitLab integration. This token must have 'api' scope. Keep this token secure.", max_length=255, verbose_name='GitLab token'),
+        ),
+    ]

dje/models.py

@@ -528,6 +528,17 @@ class DataspaceConfiguration(models.Model):
         ),
     )
 
+    gitlab_token = models.CharField(
+        _("GitLab token"),
+        max_length=255,
+        blank=True,
+        help_text=_(
+            "Personal access token (PAT) used to authenticate API requests for the "
+            "GitLab integration. This token must have 'api' scope. "
+            "Keep this token secure."
+        ),
+    )
+
     def __str__(self):
         return f"Configuration for {self.dataspace}"
 

docs/index.rst

@@ -49,6 +49,7 @@ Welcome to the very start of your DejaCode journey!
     :caption: Integrations
 
     integrations-github
+    integrations-gitlab
 
 .. toctree::
    :maxdepth: 1

docs/integrations-github.rst

@@ -7,8 +7,15 @@ DejaCode's integration with GitHub allows you to automatically forward
 **Workflow Requests** to GitHub repository **Issues**.
 This behavior can be selectively applied to any **Request Template** of your choice.
 
-GitHub Account and Personal Access Token
-----------------------------------------
+Prerequisites
+-------------
+
+- A **GitHub repository** that you want to integrate with DejaCode.
+- A **GitHub user account** with sufficient permissions (at least write access) to
+  create and manage issues in that repository.
+
+GitHub Personal Access Token
+----------------------------
 
 To enable integration, you need a GitHub **fine-grained personal access token (PAT)**.
 

docs/integrations-gitlab.rst

@@ -0,0 +1,74 @@
+.. _integrations_gitlab:
+
+GitLab Integration
+==================
+
+DejaCode's integration with GitLab allows you to automatically forward
+**Workflow Requests** to GitLab project **Issues**.
+This behavior can be selectively applied to any **Request Template** of your choice.
+
+Prerequisites
+-------------
+
+- A **GitLab project** that you want to integrate with DejaCode.
+- A **GitLab user account** with sufficient permissions to create and manage issues in
+  the target project.
+
+GitLab Personal Access Token
+----------------------------
+
+To enable integration, you need a GitLab **personal access token (PAT)** with
+appropriate permissions.
+
+1. **Access GitLab Personal Access Tokens**:
+
+   - Go to: https://gitlab.com/-/user_settings/personal_access_tokens
+   - Click the **"Add new token"** button
+   - Provide a **name** (e.g., ``DejaCode Integration``) and **expiration date**
+     (recommended)
+
+2. **Permissions**:
+
+   Under **Scopes**, select:
+
+   - ``api`` — Full access to create, update, and comment on issues
+
+.. note::
+
+   It is recommended to **create a dedicated GitLab user** with a clear, descriptive
+   name such as ``dejacode-integration``. This ensures that all GitLab issues managed by
+   the integration are clearly attributed to that user, improving traceability and
+   auditability.
+
+3. **Generate the Token**:
+
+   - Click **Create token**
+   - Copy the token and store it securely — you’ll need it for the next step
+
+DejaCode Dataspace Configuration
+--------------------------------
+
+To use your GitLab token in DejaCode:
+
+1. Go to the **Administration dashboard**
+2. Navigate to **Dataspaces**, and select your Dataspace
+3. Scroll to the **GitLab Integration** section under **Configuration**
+4. Paste your GitLab token in the **GitLab token** field
+5. Save the form
+
+Activate GitLab Integration on Request Templates
+------------------------------------------------
+
+1. Go to the **Administration dashboard**
+2. Navigate to **Workflow** > **Request templates**
+3. Create or edit a Request Template in your Dataspace
+4. Set the **Issue Tracker ID** field to your GitLab project URL, e.g.::
+
+       https://gitlab.com/group/project_name
+
+Once the integration is configured:
+
+- New **Requests** using this template will be automatically pushed to GitLab
+- Field updates (like title or priority) and **status changes** (e.g. closed) will be
+  synced
+- New **Comments** on a DejaCode Request will be propagated to the GitLab Issue.

workflow/integrations/__init__.py

@@ -5,3 +5,70 @@
 # See https://github.com/aboutcode-org/dejacode for support or download.
 # See https://aboutcode.org for more information about AboutCode FOSS projects.
 #
+
+from django.conf import settings
+
+import requests
+
+DEJACODE_SITE_URL = settings.SITE_URL.rstrip("/")
+
+
+class BaseIntegration:
+    """Base class for managing issue tracker integrations from DejaCode requests."""
+
+    default_timeout = 10
+
+    def __init__(self, dataspace):
+        if not dataspace:
+            raise ValueError("Dataspace must be provided.")
+        self.dataspace = dataspace
+        self.session = self.get_session()
+
+    def get_session(self):
+        session = requests.Session()
+        session.headers.update(self.get_headers())
+        return session
+
+    def get_headers(self):
+        """
+        Return authentication headers specific to the integration.
+        Must be implemented in subclasses.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def make_issue_title(request):
+        return f"[DEJACODE] {request.title}"
+
+    @staticmethod
+    def make_issue_body(request):
+        request_url = f"{DEJACODE_SITE_URL}{request.get_absolute_url()}"
+        label_fields = [
+            ("📝 Request Template", request.request_template),
+            ("📦 Product Context", request.product_context),
+            ("📌 Applies To", request.content_object),
+            ("🙋 Submitted By", request.requester),
+            ("👤 Assigned To", request.assignee),
+            ("🚨 Priority", request.priority),
+            ("🗒️ Notes", request.notes),
+            ("🔗️ DejaCode URL", request_url),
+        ]
+
+        lines = []
+        for label, value in label_fields:
+            if value:
+                lines.append(f"### {label}\n{value}")
+
+        lines.append("----")
+
+        for question in request.get_serialized_data_as_list():
+            label = question.get("label")
+            value = question.get("value")
+            input_type = question.get("input_type")
+
+            if input_type == "BooleanField":
+                value = "Yes" if str(value).lower() in ("1", "true", "yes") else "No"
+
+            lines.append(f"### {label}\n{value}")
+
+        return "\n\n".join(lines)

workflow/integrations/github.py

@@ -8,33 +8,18 @@
 
 from urllib.parse import urlparse
 
-from django.conf import settings
-
-import requests
+from workflow.integrations import BaseIntegration
 
 GITHUB_API_URL = "https://api.github.com"
-DEJACODE_SITE_URL = settings.SITE_URL.rstrip("/")
 
 
-class GitHubIntegration:
+class GitHubIntegration(BaseIntegration):
     """
     A class for managing GitHub issue creation, updates, and comments
     from DejaCode requests.
     """
 
     api_url = GITHUB_API_URL
-    default_timeout = 10
-
-    def __init__(self, dataspace):
-        if not dataspace:
-            raise ValueError("Dataspace must be provided.")
-        self.dataspace = dataspace
-        self.session = self.get_session()
-
-    def get_session(self):
-        session = requests.Session()
-        session.headers.update(self.get_headers())
-        return session
 
     def get_headers(self):
         github_token = self.dataspace.get_configuration(field_name="github_token")
@@ -61,6 +46,7 @@ def sync(self, request):
                 title=self.make_issue_title(request),
                 body=self.make_issue_body(request),
                 state="closed" if request.is_closed else "open",
+                labels=labels,
             )
         else:
             issue = self.create_issue(
@@ -93,7 +79,7 @@ def create_issue(self, repo_id, title, body="", labels=None):
         response.raise_for_status()
         return response.json()
 
-    def update_issue(self, repo_id, issue_id, title=None, body=None, state=None):
+    def update_issue(self, repo_id, issue_id, title=None, body=None, state=None, labels=None):
         """Update an existing GitHub issue."""
         url = f"{self.api_url}/repos/{repo_id}/issues/{issue_id}"
         data = {}
@@ -103,6 +89,8 @@ def update_issue(self, repo_id, issue_id, title=None, body=None, state=None):
             data["body"] = body
         if state:
             data["state"] = state
+        if labels:
+            data["labels"] = labels
 
         response = self.session.patch(
             url,
@@ -137,40 +125,3 @@ def extract_github_repo_path(url):
             raise ValueError("Incomplete GitHub repository path.")
 
         return f"{path_parts[0]}/{path_parts[1]}"
-
-    @staticmethod
-    def make_issue_title(request):
-        return f"[DEJACODE] {request.title}"
-
-    @staticmethod
-    def make_issue_body(request):
-        request_url = f"{DEJACODE_SITE_URL}{request.get_absolute_url()}"
-        label_fields = [
-            ("📝 Request Template", request.request_template),
-            ("📦 Product Context", request.product_context),
-            ("📌 Applies To", request.content_object),
-            ("🙋 Submitted By", request.requester),
-            ("👤 Assigned To", request.assignee),
-            ("🚨 Priority", request.priority),
-            ("🗒️ Notes", request.notes),
-            ("🔗️ DejaCode URL", request_url),
-        ]
-
-        lines = []
-        for label, value in label_fields:
-            if value:
-                lines.append(f"### {label}\n{value}")
-
-        lines.append("----")
-
-        for question in request.get_serialized_data_as_list():
-            label = question.get("label")
-            value = question.get("value")
-            input_type = question.get("input_type")
-
-            if input_type == "BooleanField":
-                value = "Yes" if str(value).lower() in ("1", "true", "yes") else "No"
-
-            lines.append(f"### {label}\n{value}")
-
-        return "\n\n".join(lines)