Configure mergebots using config files
As you know, we're extremely happy to announce that the Plastic SCM Server is now a DevOps orchestrator!
It can now coordinate information flows from/to your issue trackers, continuous integration systems, notification services and much more!
You can configure mergebots using our webadmin interface.
But today I'm going to explain how to configure the entire system using config files.
What are mergebots?
Just in case you missed the previous blogposts :-)
A mergebot is a virtual team member that plays the "integrator role".
Instead of having a team member doing all the merges for the team, or having everyone merging their own branches, the mergebot monitors the repository and runs merges for you.
mergebots save precious time by:
- Automating manual work
- Avoiding costly context switches (you know, productivity loss, stress and much more)
- Launching builds and tests (in your CI system) and checking in the merge only if the tests pass
- Coding your task and release workflow
- Notifying status by email, Slack and more
To achieve all that, mergebots communicate with your issue trackers, chat systems and CI systems (Jenkins and TeamCity at the time of writing this, with Bamboo coming shortly).
A sample mergebot
A typical mergebot behaves as follows:
- Checks that main/PRJ-1213 branch is marked as done in a branch attribute.
- Checks that the associated JIRA task is set to reviewed.
- If the two previous conditions are met, merges the task into main but inside a shelve (temporary checkin).
- Tells Jenkins to build the shelve.
- If build and tests pass, checkins the shelve so builds are never broken.
- Notifies the team by Slack.
This preview includes a sample mergebot, and our goal is to create a gallery of mergebots so customers can choose the one that best suits their needs.
Custom mergebots can also be created (and we are going to publish the source code of the mergebots in our gallery to make development simpler).
plugs
To provide the mergebot capability to check the issue tracker status, trigger CI builds and notify users, we developed what we called plugs.
There are three kinds of plugs: Issue Tracker plugs, Continuous Integration Plugs and Notifier Plugs.
This provides a huge opportunity for extensions and enables developers to tailor their particular DevOps process to their needs.
Of course, you're not on your own; while you can develop your own mergebots and plugs, Plastic SCM ships with a built-in mergebot that implements all this cycle and several built-in plugs to allow out-of-the-box configurations. Jira, Jenkins, TeamCity, Bamboo, Slack and Email plug types are at your disposal and ready to be configured.
How to configure the system
If you'd like to start configuring your DevOps cycle you'll need to configure the profile template for your users.
We provide a sample "template" but you can edit it as follows: go to the profile directory next to the devops one and write these contents into a new file called profiletemplate.conf:
[{
"name": "email",
"displayName": "User email",
"type": "email",
"description": "The email where you'd like to receive mergebot emails"
},
{
"name": "slack",
"displayName": "Slack configuration",
"type": "group",
"items": [{
"name": "username",
"displayName": "Slack username",
"type": "string",
"description": "The name of your slack user in the team workspace"
}]
}]
You can tweak the description as you like. We'll see later* the available types of profile fields.
Once you are comfortable with the template, save it to the following path:
- Windows:
%PROGRAMFILES%/PlasticSCM5/server/profiles/profiletemplate.conf - Linux / macOS:
/var/lib/plasticscm/profiles/profiletemplate.conf
SYSTEM in Windows, plasticscm in Linux or macOS) must have permissions to write in the devops and profiles directories, and have a Plastic SCM CLI client available with a valid configuration. That is, the user that runs the server must be able to execute cm checkconnection successfully.
Restart your server and access the Plastic SCM Server Web Admin: http://my.plastic.server.com:7178/devops/intro. You'll see a nice little introduction guide that we prepared for you to explain the mergebot cycle in a more visual way!
When you're ready to begin, move forward to the dashboard by clicking on the Configure now button or just navigating to http://my.plastic.server.com:7178/devops. You'll see that you have no current mergebot configurations. Click the Configure a mergebot now button to start setting up your custom mergebot configuration.
The trunkbot default mergebot
The built-in mergebot has four specific configuration blocks:
-
Plastic SCM:
- Repository: The one to be monitored by the mergebot.
- Trunk branch: The branch into which all task branches will be merged.
- Branch prefix: The prefix of the branches to be merged. Example: PRJ- will take PRJ-1234. This is the same prefix that you use to link branches to the issue tracker.
- Bot User: The Plastic SCM user that the mergebot will use to perform actions (merge, checkin, etc.).
- Path to cm.exe: Since the REST API is still a work in progress, the mergebot needs access to a Plastic SCM CLI client to perform some operations.
- Branch status attribute name: The attribute that describes the lifecycle status of a branch.
- Resolved status value: The attribute value that means a branch task is resolved.
- Testing status value: The attribute value that means a branch task is being processed.
- Failed status value: The attribute value that means a branch task processing has failed at some point.
- Merged status value: The attribute value that means a branch task processing has been successfully merged on a specified trunk branch.
-
Issue Tracker Integration:
- Plug: Which plug configuration to use.
- Project Key: Key of the project whose issues will be related to the Plastic branches.
- Task title field: The name of the task field considered as title in the issue tracker.
- Task status field name: The name of the task field to store its lifecycle status.
- Resolved status value: The status value to check if a task is resolved before trying to merge it.
- Testing status value: The status value to set while a branch is being processed.
- Failed status value: The status value to set after the processing of a task failed at some point.
- Merged status value: The status value to set after the task branch has been successfully merged.
-
CI Integration:
- Plug: Which plug configuration to use.
- Plan: The name of the plan to run to test a task branch.
-
Notifications:
- Plug: Which plug configuration to use.
- User: Which profile field used as the recipient of the notification.
- Always notify to: A comma-separated list of users to notify on every event, besides the branch owner.
As you probably noticed, you'll need to create plug configurations for each of the three mergebot connections: Issue tracker, CI and notifier.
You can create them directly from the "New Mergebot Configuration" page or in the "Plug Types" page (see the navigation menu on the left hand side of the screen).
Each configuration, either mergebot or plug, will start a new process that will be listening to requests and performing actions.
The mergebot/plug binaries to run are defined in the type; built-in ones are included in the default Plastic SCM Server installation.
Regarding types, you can check the built-in ones or create your own from the types pages. The built-in ones include a nice Learn more link where you can find additional info about them!
Structure of the configuration directory
If you wonder where all this is stored, you can check the devops directory in the server data directory. This is %PROGRAMFILES%/PlasticSCM5/server/devops in Windows and /var/lib/plasticscm/devops in macOS and Linux. It initially contains two directories (builtin and config) out of these five:
builtin: Contains the mergebot and plug binaries shipped with Plastic SCM Server.config: Contains the mergebot/plug types and configurations, as well as the API keys.data: Contains statistics and usage data.logs: Contains the mergebot and plugs logs.run: Contains files to store the PID of running mergebot/plug processes.
If you look in the /devops/config directory, you'll see three directories: apikeys, mergebots and plugs, each with a self-describing name. Let's see what there's inside them.
API keys
The API keys directory has its contents divided into conn keys and user keys, each one in its own directory. The conn directory contains the API Keys that are used only to access the server REST API. They are files whose name matches the key and the '.key' extension. Here's an example:
{
"key": "014B6147A6391E9F4F9AE67501ED690DC2D814FECBA0C1687D016575D4673EE3"
}
In the user directory, the user keys include a Plastic SCM SEID to be impersonated by REST API calls and they have the same naming pattern as the conn keys. Here's an example:
{
"key": "3AC17D06A2477F3F4FF2B569EC8246981B52CE5180A4D5F3E6712570B413BF9B",
"description": "The Mergebot impersonator key",
"seid": "mergebot-user"
}
mergebots and plugs
Now, onto the mergebots and plugs. Both have the same structure, an available directory to store the mergebot/plug types and a start directory to store the configurations.
Each file (either type or configuration) should have the '.conf' extension and its name should match the 'name' field inside. This is the definition of the built-in mergebot type:
{
"name" : "trunkbot", // internal name of the mergebot/plug type
"type" : "mergebot", // type of the plug - mergebots should always have this set to 'mergebot'
"builtIn" : true,
"displayName": "trunk-bot", // The name used to display this bot on the WebAdmin
"description": "each task branch is built, tested and merged to main",
"command": "${builtin}/mergebots/trunk-bot/trunkbot", // The full command to run for each configuration
"template": "${builtin}/mergebots/trunk-bot/trunkbot.config.template" // Where to find the template of the mergebot (i.e. the definition of its configuration)
}
And these are examples of configurations:
-
Mergebot configuration:
{ "name": "integratorbot", // the name of this particular configuration "description": "it builds/tests each branch marked ready and merges it to main if everything went alright", "type": "trunkbot", // the name of the mergebot type instantiated by this configuration "apiKey": "CE01502283B0854123917FD9F20098F9A28A63DA7FDF01A04CB42425F39D0E82", // a 'conn' API key "start": "yes", // whether the server should start the mergebot "configuration": { // the definition of this object is given by the mergebot template "repository": "quake3-mergebot", "trunk_branch": "/main", "branch_prefix": "scm", "bot_user": "3AC17D06A2477F3F4FF2B569EC8246981B52CE5180A4D5F3E6712570B413BF9B", "plastic_group": { "cm_path": "C:/Program Files/PlasticSCM5/client/cm.exe", "status_attribute_group": { "name": "status", "resolved_value": "resolved", "testing_value": "testing", "failed_value": "failed", "merged_value": "merged" } }, "issues_group": { "plug": "jira-mergebot-test", // the name of the plug configuration to use "project_key": "JMT", "title_field": "summary", "status_field_group": { "name": "status", "resolved_value": "Done", "testing_value": "Testing", "failed_value": "To Do", "merged_value": "Merged" } }, "ci_group": { "plug": "jenkins-mergebot-test", // the name of the plug configuration to use "plan": "quake-mergebot-test" }, "notifier_group": { "plug": "slack-mergebot-test", // the name of the plug configuration to use "user": "slack.username", // the qualified name of the profile property where the slack username is stored "fixed_recipients": "#general, #random" } } } -
Plug configuration:
{ "name": "jira-mergebot-test", // the plug configuration name "plug": "jira", // the plug type instantiated by this configuration "type": "issuetracker", // it can be 'issuetracker', 'ci' or 'notifier' "apikey": "67407BDFE6952359D371D68BC34F7B01978AF40BDB35DE19D247E97AF872D96A", // a 'conn' API key "start": "yes", "configuration": { // the definition of this object is given by the mergebot template "url": "https://my.jira.server.net", "user": "my-user", "password": "my-password" // encrypted if set through the WebAdmin } }
We'll publish a guide in the upcoming weeks about how to create your own mergebots and plugins, including interfaces, code guidelines and template formats. In the meantime, give a try to this new step in DevOps automation and tell us what you think! We'd love to have your feedback!
[*] Profile field types
The profiletemplate.conf file contains a JSON array of field objects. Each object has 4 required properties: name, displayName, type and description, and one optional property items. These are the available values for the type property:
bool: A regular on/off field.int: A numeric field.string: A text field.email: A text field with email format.password: A secured text field to encrypt data upon saving.combobox: A list of text items to choose from, defined in the 'items' property of the field definition:{ "name": "key-When a branch is merged", "displayName": "When a branch is merged...", "type": "combobox", "description": "Decide what the bot will do when one of your branches is merged", "items": [ { "name": "key-Send me a Slack", "displayName": "Send me a Slack", "type": "string" }, { "name": "key-Send me an Email", "displayName": "Send me an Email", "type": "string" } ] }- group: A way to hierarchically group profile fields. The 'items' property will contain an array of additional fields:
{ "name": "key-Jira", "displayName": "Jira", "type": "group", "description": "Enter your Jira credentials", "items": [ { "name": "key-User", "displayName": "User", "type": "string" }, { "name": "key-Password", "displayName": "Password", "type": "password" } ] }
0 comentarios: