Git lab add trigger pipeline command

Packs/GitLab/Integrations/GitLabv2/GitLabv2.py

@@ -19,9 +19,10 @@
 
 
 class Client(BaseClient):
-    def __init__(self, project_id, base_url, verify, proxy, headers):
+    def __init__(self, project_id, base_url, verify, proxy, headers, trigger_token=None):
         super().__init__(base_url=base_url, verify=verify, proxy=proxy, headers=headers)
         self.project_id = project_id
+        self.trigger_token = trigger_token
 
     def group_projects_list_request(self, params: dict | None, group_id: str | None) -> dict:
         headers = self._headers
@@ -314,6 +315,19 @@ def get_job_artifact_request(self, project_id: str, job_id: str, artifact_path_s
         suffix = f'projects/{project_id}/jobs/{job_id}/artifacts/{artifact_path_suffix}'
         return self._http_request('get', suffix, headers=headers, resp_type='text')
 
+    def gitlab_trigger_pipeline(self, project_id: str, data: dict) -> dict:
+        """Triggers a pipeline on GitLab.
+
+        Args:
+            project_id: Project ID on winch to run the pipeline.
+            data: The request body in JSON format.
+
+        Returns:
+            dict: The response in JSON format.
+        """
+        suffix = f'projects/{project_id}/trigger/pipeline'
+        return self._http_request('POST', suffix, data=data)
+
 
 ''' HELPER FUNCTIONS '''
 
@@ -1698,6 +1712,42 @@ def gitlab_artifact_get_command(client: Client, args: Dict[str, Any]) -> Command
     )
 
 
+def gitlab_trigger_pipeline_command(client: Client, args: dict[str, str]) -> CommandResults:
+    """
+    Triggers a GitLab pipeline on a selected project and branch.
+    Args:
+        client (Client): Client to perform calls to GitLab services.
+        args (dict) XSOAR arguments:
+            - 'project_id': Project ID on which to run the pipeline.
+            - 'ref_branch': The branch on which to run the pipeline. Default is 'master'
+
+    Returns:
+        (CommandResults).
+    """
+    project_id = args.get('project_id') or client.project_id
+    if not client.trigger_token:
+        return_error("A trigger token is required in the integration instance configuration")
+    data = {
+        'token': client.trigger_token,
+        'ref': args.get('ref_branch', 'master'),
+    }
+    for key, value in json.loads(args.get('trigger_variables', '{}')).items():
+        data[f'variables[{key}]'] = value
+
+    response = client.gitlab_trigger_pipeline(project_id, data)
+
+    outputs = {k: v for k, v in response.items() if k in PIPELINE_FIELDS_TO_EXTRACT}
+    human_readable = tableToMarkdown('GitLab Pipeline', outputs, removeNull=True)
+
+    return CommandResults(
+        outputs_prefix='GitLab.Pipeline',
+        outputs_key_field='id',
+        outputs=outputs,
+        raw_response=response,
+        readable_output=human_readable
+    )
+
+
 def check_for_html_in_error(e: str):
     """
     Args:
@@ -1723,6 +1773,7 @@ def main() -> None:  # pragma: no cover
     LOG(f'Command being called is {command}')
     server_url = params.get('url', '')
     project_id = arg_to_number(params.get('project_id'), required=True)
+    trigger_token = params.get('trigger_token', {}).get('password')
     commands = {'gitlab-group-project-list': group_project_list_command,
                 'gitlab-issue-create': create_issue_command,
                 'gitlab-branch-create': branch_create_command,
@@ -1758,10 +1809,11 @@ def main() -> None:  # pragma: no cover
                 'gitlab-pipelines-schedules-list': gitlab_pipelines_schedules_list_command,
                 'gitlab-jobs-list': gitlab_jobs_list_command,
                 'gitlab-artifact-get': gitlab_artifact_get_command,
+                'gitlab-trigger-pipeline': gitlab_trigger_pipeline_command,
                 }
 
     try:
-        client = Client(project_id, urljoin(server_url, ""), verify_certificate, proxy, headers=headers)
+        client = Client(project_id, urljoin(server_url, ""), verify_certificate, proxy, headers, trigger_token)
         if project_id and verify_project_id(client, project_id):
             if demisto.command() == 'test-module':
                 return_results(test_module(client))

Packs/GitLab/Integrations/GitLabv2/GitLabv2.yml

@@ -13,6 +13,12 @@ configuration:
   hiddenusername: true
   required: true
   type: 9
+- displaypassword: Trigger Token
+  additionalinfo: The trigger token to run pipelines. For more info see https://docs.gitlab.com/ee/ci/triggers
+  name: trigger_token
+  hiddenusername: true
+  required: false
+  type: 9
 - display: Project ID
   additionalinfo: The project ID, it can be found under the project name.
   name: project_id
@@ -3569,7 +3575,7 @@ script:
       type: String
     - contextPath: GitLab.PipelineSchedule.last_pipeline.status
       description: Status of the last pipeline that was run by the scheduled pipeline. Relevant only when the pipeline schedule ID is given.
-      type: String 
+      type: String
   - name: gitlab-jobs-list
     arguments:
     - default: false
@@ -3651,7 +3657,7 @@ script:
       isArray: false
       name: artifact_path_suffix
       required: true
-      secret: false 
+      secret: false
     description: Gets an artifact from a given artifact path, corresponding to a given job ID.
     execution: false
     outputs:
@@ -3664,6 +3670,80 @@ script:
     - contextPath: GitLab.Artifact.artifact_data
       description: Data of the artifact requested.
       type: String
+  - name: gitlab-trigger-pipeline
+    arguments:
+    - default: false
+      description: Project ID on which to run the pipeline.
+      isArray: false
+      name: project_id
+      required: false
+      secret: false
+    - default: false
+      description: The branch on which to run the pipeline. Default is 'master'.
+      isArray: false
+      name: ref_branch
+      required: false
+      secret: false
+    - default: false
+      description: JSON containing the pipeline variables.
+      isArray: false
+      name: trigger_variables
+      required: false
+      secret: false
+    description: Triggers a GitLab pipeline on a selected project and branch.
+    execution: false
+    outputs:
+    - contextPath: GitLab.Pipeline.id
+      description: Pipeline ID.
+      type: Number
+    - contextPath: GitLab.Pipeline.project_id
+      description: Project ID that the pipeline belongs to.
+      type: Number
+    - contextPath: GitLab.Pipeline.status
+      description: Status of the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.ref
+      description: Reference of the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.sha
+      description: SHA of the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.created_at
+      description: Time when the pipeline was created.
+      type: Date
+    - contextPath: GitLab.Pipeline.updated_at
+      description: Time when the pipeline was last updated.
+      type: Date
+    - contextPath: GitLab.Pipeline.started_at
+      description: Time when the pipeline was started.
+      type: Date
+    - contextPath: GitLab.Pipeline.finished_at
+      description: Time when the pipeline was finished.
+      type: Date
+    - contextPath: GitLab.Pipeline.duration
+      description: Duration of the pipeline in seconds.
+      type: Number
+    - contextPath: GitLab.Pipeline.web_url
+      description: Web URL of the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.user.name
+      description: Name of the user who triggered the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.user.username
+      description: Username that triggered the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.user.id
+      description: ID of the user who triggered the pipeline.
+      type: Number
+    - contextPath: GitLab.Pipeline.user.state
+      description: State of the user who triggered the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.user.avatar_url
+      description: Avatar URL of the user who triggered the pipeline.
+      type: String
+    - contextPath: GitLab.Pipeline.user.web_url
+      description: Web URL of the user who triggered the pipeline.
+      type: String
   isfetch: false
   runonce: false
   script: '-'

Packs/GitLab/Integrations/GitLabv2/GitLabv2_test.py

@@ -986,3 +986,45 @@ def test_return_date_arg_as_iso(arg, isValidDate, expected_response):
             return_date_arg_as_iso(arg)
 
         assert str(e.value) == expected_response
+
+
+@pytest.mark.parametrize('trigger_token, args, expected_result', [
+    ('', {}, util_load_json('test_data/commands_test_data.json').get('trigger_pipeline1')),
+    (1111, {'project_id': 2222, 'ref_branch': 'test'}, util_load_json('test_data/commands_test_data.json').get('trigger_pipeline2'))
+])
+def test_trigger_pipeline(mocker, trigger_token, args, expected_result):
+    """
+    Given:
+        - client and demisto args
+            - case 1 - client without trigger token.
+            - case 2 - client with trigger token and args with a different project ID than the instance.
+    When:
+        - gitlab_trigger_pipeline_command
+    Then:
+        - The response is as expected
+            - case 1 - Throws an error about the trigger token that is missing
+            - case 2 - The response is correct with the same branch and project_id as in the args.
+    """
+    from GitLabv2 import Client, gitlab_trigger_pipeline_command
+    client = Client(project_id=1234,
+                    base_url="base_url",
+                    verify=False,
+                    proxy=False,
+                    headers={'PRIVATE-TOKEN': 'api_key'},
+                    trigger_token=trigger_token)
+    expected_outputs: List[Dict] = expected_result['expected_outputs']
+    expected_prefix: str = expected_result['expected_prefix']
+    expected_key_field: str = expected_result['expected_key_field']
+    mocker.patch.object(Client, '_http_request', return_value=expected_result['mock_response'])
+    mock_error = mocker.patch('GitLabv2.return_error')
+
+    command_result = gitlab_trigger_pipeline_command(client, args)
+
+    if not trigger_token:
+        assert mock_error.call_args[0][0] == 'A trigger token is required in the integration instance configuration'
+    else:
+        assert command_result.outputs_prefix == expected_prefix
+        assert command_result.outputs_key_field == expected_key_field
+        assert command_result.outputs == expected_outputs
+        assert command_result.outputs.get('ref') == args.get('ref_branch')
+        assert command_result.outputs.get('project_id') == args.get('project_id')

Packs/GitLab/Integrations/GitLabv2/README.md

@@ -16,6 +16,7 @@ This integration enables you to:
 - Get a list of files in the GitLab project.
 - Get the contents and details of a file in GitLab.
 - Search for code in the GitLab project.
+- Trigger a pipeline in the GitLab project.
 
 #### Create a Personal Access Token 
 Personal access tokens (PATs) are an alternative to using passwords for authentication to GitLab when using the GitLab API. 
@@ -28,6 +29,18 @@ To generate a new token:
 6. Select the **scopes**, or **permissions**, you want to grant this token. The minimum is read-only on repo.
 7. Click **Create personal access token** and copy the api key generated.-+
 
+#### Create a Trigger Token
+Trigger tokens allows you to trigger a pipeline for a branch using it to authenticate on an API call.
+Prerequisite:
+- You must have at least the Maintainer role for the project.
+To generate a new token:
+1. Navigate to your project.
+2. Select Settings > CI/CD.
+3. Expand Pipeline triggers.
+4. Enter a description and select Add trigger.
+   - You can view and copy the full token for all triggers you have created.
+   - You can only see the first 4 characters for tokens created by other project members.
+
 #### Get Project ID
 1. Go to the desired project example gitlab.com/username/project1.
 2. Under the project name get the argument project_id
@@ -42,6 +55,7 @@ To generate a new token:
     | --- | --- | --- |
     | Server URL (e.g. https://gitlab.com/api/v4) |  | False |
     | API Key | The API Key to use for connection | True |
+    | Trigger Token | The trigger token to run pipelines | False |
     | Project ID |  | True |
     | Trust any certificate (not secure) |  | False |
     | Use system proxy settings |  | False |
@@ -2144,3 +2158,42 @@ Gets an artifact from a given artifact path, corresponding to a given job ID.
 | GitLab.Artifact.job_id | String | Job ID from which the artifact was taken. | 
 | GitLab.Artifact.artifact_path_suffix | String | Suffix of the given artifact path. | 
 | GitLab.Artifact.artifact_data | String | Data of the artifact requested. | 
+
+### gitlab-trigger-pipeline
+
+***
+Triggers a GitLab pipeline on a selected project and branch.
+
+#### Base Command
+
+`gitlab-trigger-pipeline`
+
+#### Input
+
+| **Argument Name** | **Description** | **Required** |
+| --- | --- | --- |
+| project_id | Project ID on which to run the pipeline. | Optional | 
+| ref_branch | The branch on which to run the pipeline. Default is 'master'. | Optional | 
+| trigger_variables | JSON containing the pipeline variables. | Optional | 
+
+#### Context Output
+
+| **Path** | **Type** | **Description** |
+| --- | --- | --- |
+| GitLab.Pipeline.id | Number | Pipeline ID. | 
+| GitLab.Pipeline.project_id | Number | Project ID that the pipeline belongs to. | 
+| GitLab.Pipeline.status | String | Status of the pipeline. | 
+| GitLab.Pipeline.ref | String | Reference of the pipeline. | 
+| GitLab.Pipeline.sha | String | SHA of the pipeline. | 
+| GitLab.Pipeline.created_at | Date | Time when the pipeline was created. | 
+| GitLab.Pipeline.updated_at | Date | Time when the pipeline was last updated. | 
+| GitLab.Pipeline.started_at | Date | Time when the pipeline was started. | 
+| GitLab.Pipeline.finished_at | Date | Time when the pipeline was finished. | 
+| GitLab.Pipeline.duration | Number | Duration of the pipeline in seconds. | 
+| GitLab.Pipeline.web_url | String | Web URL of the pipeline. | 
+| GitLab.Pipeline.user.name | String | Name of the user who triggered the pipeline. | 
+| GitLab.Pipeline.user.username | String | Username that triggered the pipeline. | 
+| GitLab.Pipeline.user.id | Number | ID of the user who triggered the pipeline. | 
+| GitLab.Pipeline.user.state | String | State of the user who triggered the pipeline. | 
+| GitLab.Pipeline.user.avatar_url | String | Avatar URL of the user who trigerred the pipeline. | 
+| GitLab.Pipeline.user.web_url | String | Web URL of the user who triggered the pipeline. | 

Packs/GitLab/Integrations/GitLabv2/test_data/commands_test_data.json

@@ -1193,5 +1193,55 @@
     "expected_prefix": "GitLab.PipelineSchedule",
     "expected_url_mock_suffix": "projects/1/pipeline_schedules",
     "expected_key_field": "id"
+  },
+  "trigger_pipeline1": {
+    "mock_response": {
+        "id": 1,
+        "project_id": 1234,
+        "sha": "skd5h31245ljkasl4kj45l324",
+        "ref": "master",
+        "status": "running",
+        "created_at": "2021-06-15T14:31:29.607Z",
+        "updated_at": "2021-06-15T14:31:32.964Z",
+        "web_url": "https://server_url/project/-/pipelines/1"
+    },
+    "expected_outputs": {
+        "id": 1,
+        "project_id": 1234,
+        "sha": "skd5h31245ljkasl4kj45l324",
+        "ref": "master",
+        "status": "running",
+        "created_at": "2021-06-15T14:31:29.607Z",
+        "updated_at": "2021-06-15T14:31:32.964Z",
+        "web_url": "https://server_url/project/-/pipelines/1"
+    },
+    "expected_prefix": "GitLab.Pipeline",
+    "expected_url_mock_suffix": "projects/1234/pipelines",
+    "expected_key_field": "id"
+  },
+  "trigger_pipeline2": {
+    "mock_response": {
+        "id": 1,
+        "project_id": 2222,
+        "sha": "skd5h31245ljkasl4kj45l324",
+        "ref": "test",
+        "status": "running",
+        "created_at": "2021-06-15T14:31:29.607Z",
+        "updated_at": "2021-06-15T14:31:32.964Z",
+        "web_url": "https://server_url/project/-/pipelines/1"
+    },
+    "expected_outputs": {
+        "id": 1,
+        "project_id": 2222,
+        "sha": "skd5h31245ljkasl4kj45l324",
+        "ref": "test",
+        "status": "running",
+        "created_at": "2021-06-15T14:31:29.607Z",
+        "updated_at": "2021-06-15T14:31:32.964Z",
+        "web_url": "https://server_url/project/-/pipelines/1"
+    },
+    "expected_prefix": "GitLab.Pipeline",
+    "expected_url_mock_suffix": "projects/2222/pipelines",
+    "expected_key_field": "id"
   }
 }

Packs/GitLab/ReleaseNotes/2_2_11.md

@@ -0,0 +1,4 @@
+
+#### Integrations
+##### GitLab v2
+Added the new ***gitlab-trigger-pipeline*** command to trigger a GitLab pipeline.