README.md

GitLab Integration for XL Release

XLR GitLab plugin is deprecated now as the plugin is insourced to Digital.ai organization. The plugin is available on https://github.com/xebialabs/xlr-gitlab-plugin

Table of Contents

• Background
• Installation
  • Requirements
  • Building the plugin
  • Adding the plugin to XL Release
• Usage
  • Configuration
  • Tasks
  • Webhooks
  • Triggers
  • Tiles
• Contributing
• License

Background

This document describes the functionality provided by the xlr-gitlab-plugin.

Please see the XL Release Documentation for background information on XL Release and release concepts.

Installation

Requirements

1. XL Release 9.0+

Building the plugin

The gradle wrapper facilitates building the plugin. Use the following command to build using Gradle:

./gradlew clean build

The built plugin, along with other files from the build, can then be found in the build folder.

Adding the plugin to XL Release

Download the latest version of the plugin from the releases page. The plugin can then be installed through the XL Release graphical interface or the server backend. For additional detail, please refer to the docs.xebialabs.com documentation on XLR plugin installation

Usage

Available Tasks: Accept Merge Request, Create Branch, Create Group, Create Merge Request, Create Project, Create Project Webhook, Create Tag, Query Commits, Query Data, Query Merge Requests, Query Pipelines, Query Project, Query Secure Data, Query Tags, Trigger Pipeline

Available Triggers: Commit Trigger, Tag Trigger

Available Dashboard Tiles: Commits Tile, Contributions Tile, Merge Requests Tile, Pipelines Tile, Tags Timeline Tile, Timeline Tile

Configuration

Tasks

Accept Merge Request

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Merge ID (This is visible in the GUI and should be an integer)

Create Branch

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input New Branch Name
• input Reference (Branch name or commit hash to the create branch from)
• output Commit Source (Commit hash used to generate the new branch)

Create Group

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Group Name
• input Group Path
• input Group Description
• input Group Visibility
• output Group ID

Create Merge Request

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Source Branch
• input Target Branch
• input Merge Request Title
• input Target Project ID
• output Merge Request ID

Create Project

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project Name
• input Project Path
• input Namespace (Namespace ID for the project. This will default to the configuration user namespace if not provided)
• input Project Description
• input Import URL (Note: If your HTTP repository is not publicly accessible, then add authentication information to the URL (e.g. https://username:password@gitlab.company.com/group/project.git))
• input Project Visibility
• output Project ID

Create Project Webhook

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input URL (The webhook URL)
• input Push Events (Trigger hook on push events)
• input Issues Events (Trigger hook on issues events)
• input Confidential Issues Events (Trigger hook on confidential issues events)
• input Merge Requests Events (Trigger hook on merge requests events)
• input Tag Push Events (Trigger hook on tag push events)
• input Note Events (Trigger hook on note events)
• input Job Events (Trigger hook on job events)
• input Pipeline Events (Trigger hook on pipeline events)
• input Wiki Page Events (Trigger hook on wiki events)
• input Verify SSL (Do SSL verification when triggering the hook)
• input Token (Secret token to validate received payloads)
• output Hook ID

Create Tag

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Reference (Commit hash, another tag name, or branch name from which to create the tag)
• input Tag Name
• input Message (An optional description for the tag)
• output Commit ID (The hash of the commit for the tag)

Query Commits

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Branch Name (If not provided, the default branch will be used)
• input Results Limit (Upper limit on the number of commits to return from the query)
• output Commits

Query Data

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input API Endpoint URI (URI for the API endpoint - for example /api/v4/projects/1/triggers. Do not include URL parameters)
• input JSON Path (The JSON path expression for locating the value of interest)
• output Value

Query Merge Requests

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Results Limit (Upper limit on the number of pull requests to return from the query)
• input Sorting (Approach for sorting query results)
• input Simple View (If simple view is enabled, only the iid, URL, title, description, and basic state of the merge request are extracted)
• input Source Branch (If a merge request source branch is provided, only matching merge requests will be returned. For the value, provide a branch name, such as "master")
• input Target Branch (If a merge request target branch is provided, only matching merge requests will be returned. For the value, provide a branch name, such as "master")
• input Milestone (Filter results by milestone. For the value, provide a specific milestone, the value "Any", or the value "None")
• input State
• output Merge Requests

Query Pipelines

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• output Pipelines

Query Project

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project Name
• input Namespace
• output Project ID

Query Secure Data

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input API Endpoint URI (URI for the API endpoint - for example /api/v4/projects/1/triggers. Do not include URL parameters)
• input JSON Path (The JSON path expression for locating the value of interest)
• output Value

Query Tags

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• Repository Search (Optionally, specify a search to filter what tags will be processed. This uses the standard GitLab tags search criteria, so consult GitLab documentation on the syntax)
• input Results Limit (Upper limit on the number of tags to return from the query)
• output Tags

Trigger Pipeline

Properties:

• input GitLab Server
• input API Key (Optionally, override the GitLab Server configuration API token)
• input Project ID (This is visible in the GUI and should be an integer)
• input Ref (Commit hash, tag name, or branch name from which to trigger the pipeline)
• input Token (The token for the pipeline trigger. This is not the same as the GitLab API access token)
• input Variables (Optionally, provide variables to the pipeline execution)
• output Pipeline ID
• output Pipeline Status
• output Pipeline Web URL

Webhooks

Code Commit/Push Webhook

Gitlab Webhook Configuration

Here's the URL Format :

http://username:password@xlrserver:port/api/extension/gitlab/commit_webhook?template=<templateName/prefix>

Release Summary view in XL Release

Release Variables created

Merge Pull Request Webhook

Gitlab Webhook Configuration

http://username:password@xlrserver:port/api/extension/gitlab/pr_webhook?template=<templateName/prefix>

Release Summary view in XL Release

Release Variables created

Triggers

Commit Trigger

Properties:

• Repository GitLab Server
• Repository API Key (Optionally, provide an API token to override the server configuration)
• Repository Project ID (GitLab project to monitor - should be an integer)
• Repository Branch Name (Optionally, specify a branch name if only listening for commits on a single branch)
• variables Commit Id (Commit hash)
• variables Branch (Branch where the commit occurred)

Tag Trigger

Properties:

• Repository GitLab Server
• Repository API Key (Optionally, provide an API token to override the server configuration)
• Repository Project ID (GitLab project to monitor - should be an integer)
• Repository Search (Optionally, specify a search to filter what tags will be processed. This uses the standard GitLab tags search criteria, so consult GitLab documentation on the syntax)
• variables Tag Name
• variables Tag Message
• variables Commit Id
• variables Commit Title
• variables Commit Message
• variables Commit Author
• variables Commit Committer
• variables Commit Creation Datetime
• variables Commit Authored Datetime
• variables Commit Committed Datetime

Tiles

Dashboard tiles are included in this plugin, to visualize commit, merge request, and pipelines information. These tiles use the existing XL Release GitLab server configuration/connection and can be configured using the usual dashboard setup approach. These dashboard titles are available for all dashboard scopes - release, folder, and global.

Commits Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)
• input Branch Name (If not provided, the default branch will be used)
• input Results Limit (Upper limit on the number of pull requests to return from the query)

Contributions Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)
• input Branch Name (If not provided, the default branch will be used)
• input Results Limit (Upper limit on the number of pull requests to return from the query)

Merge Requests Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)
• input Results Limit (Upper limit on the number of pull requests to return from the query)
• input Source Branch (If a merge request source branch is provided, only matching merge requests will be returned. For the value, provide a branch name, such as "master")
• input Target Branch (If a merge request target branch is provided, only matching merge requests will be returned. For the value, provide a branch name, such as "master")

Pipelines Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)

Pipelines Timeline Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)

Tags Timeline Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)
• input Search (Optionally, specify a search to filter the tags. This uses the standard GitLab tags search criteria, so consult GitLab documentation on the syntax)
• input Results Limit (Upper limit on the count of latest tags to return from the query)

Timeline Tile

Properties:

• Title
• input GitLab Server
• input API Key (Optionally, provide an API token to override the server configuration)
• input Project ID (This is visible in the GUI and should be an integer)
• input Branch Name (If not provided, the default branch will be used)
• input Results Limit (Upper limit on the number of pull requests to return from the query)

Contributing

Please review the contributing guidelines for xebialabs-community at http://xebialabs-community.github.io/

License

This community plugin is licensed under the MIT license.

See license in LICENSE.md

References

How to release a new candidate version

$./gradlew candidate

This command automaticaly tags the version, pushes it remotely and trigger a release build. The script: ./buildViaTravis.sh manages to run the right command.

How to release a new version

$./gradlew final

This command automaticaly tags the version, pushes it remotely and trigger a release build. The script: ./buildViaTravis.sh manages to run the right command.