The new DevOps integrations work for GitLab, GitHub, Azure DevOps (Cloud and Server), Bitbucket (Cloud and Server) and allow you to:
- Improve navigation between several tools. Branches, merge requests (MRs) and pull requests (PRs) are automatically linked to any Targetprocess entities by IDs.
- Automate workflow based on branches or merge requests modifications.
- Create reports based on the information from repositories.
How does it work?
We do not download the code. These new Integrations have nothing in common with the existing Targetprocess source control integrations plugins, which import commits and code diffs to user stories.
The new integrations use webhooks to link entities with branches and pull requests, and then make additional APIs calls to get more details for branches and merge requests.
When a branch is created, it's linked to a Targetprocess entity. All its merge requests or pull requests will be linked to the same entity automatically despite the other IDs mentioned in their names.
In the entity view the links to branches, merge and pull requests are shown along with the statuses of their pipelines, code reviews and merge conflicts.
You can see the status of the last pipeline – failed, successful, running or cancelled. The Approval icon is in gray until the required number of approvals are received. The exclamation alert shows if merge/pull requests are in progress, have failed pipelines or have conflicts and cannot be merged automatically.
When a merge/pull request attaches to an entity, a comment with a link to Targetprocess is added to the merge/pull request:
Why an integration profile requires a personal access token?
Webhooks provide limited information from the tools. An Integration profile with a personal token allows you to send API requests for additional information, which is not available with webhooks. For example, to show pipeline statuses on user stories, or a number of received code review approvals. These details are also used to automate cross-system scenarios with Automation Rules.
We considered implementing a lite version of integration, without personal access tokens, based just on webhooks. This kind of Integration will only allow the linking of branches to Targetprocess items. Vote for the idea and let us know if it's important for you.
How to start
Any integration can start working within a couple of minutes. To achieve this, an integration profile should be created in Settings > Integrations.
To add an integration profile, provide a URL to the repository and the personal access token of an admin user (if all projects/repositories will be followed), or a user who is a member of the required projects/repositories, and his access level is Owner / Maintainer.
We recommend creating a new user in the repository – for example, DevOps Integration – and then grant him Administrator permissions. In this case, there will be no need to add this user to all the projects as a maintainer, webhooks will be created properly, and comments with the link to Targetprocess related entities will be posted on behalf of this user.
This user’s token allows you to sync updates for the linked branches and to request additional details of merge requests.
How to create a personal access token in different tools.
How to link a branch
New branches will be linked automatically, if related entity IDs are recognized from the branch's name.
If the branch name contains numbers with any of the prefixes, this number is considered as the Targetprocess entity ID: #, tp, story, us, bug, bugfix, feature, rel, release, task. All the other solo numbers in the name will be ignored.
Prefixes are case insensitive and might be followed by a dash '-', slash '/', backslash '', sharp '#' or underscore '_' .
For, example, if you have a branch named 'tp-209-Bug222343-new-landing-page', it will be linked to an entity with ID #209 and bug with id #222343. And branch name 'Release/3.13.3_TP_222343' will be attached to ID #222343 and release with ID 3.
Only numbers with prefixes will be considered for Targetprocess entity ID
Supported prefixes: #, tp, us, userstory, story, bug, task, feature, release.
Prefixes could be followed by separators: '-', '/', '', '_'
Link a Pull Request or Merge Request
When a branch is linked to a Targetprocess entity, then all merge/pull requests will be linked to it automatically. Even if they have different IDs in the name – the branch is already attached to a different entity. The same applies to a Merge or Pull Request.
Pull Requests / Merge Requests will be linked automatically to the correspondent entity by ID, if their parent branches don’t have any numbers in their names and are not linked to any Targetprocess entities yet.
Branch or merge request could be attached to multiple entities and detached from the Targetprocess view. However, detach from the view doesn't remove matching entity ID from the pull request, merge request name and with the next change they will be attached again.
Customize cards with DevOps unit
To see branch details – pipeline status, approvals, mergeability – on the cards, you have to go to Board View Setup > Customize Cards and add a new DevOps unit to the cards.
When multiple branches and requests are attached, unit value is calculated based on all not closed/merged items.
If at least one branch/MR pipeline or approval status is not successful, then the unit on the card reflects it. The same happens for merge conflicts – if at least one related merge request cannot be merged, then the unit on the card will show that.
Having the DevOps Integration Profile installed means you can create automation rules and automate any workflows. For example, Rule can trigger CI/CD job start, when use story is updated in Targetprocess. Or vice versa, the rule can trigger an update in Targetprocess when the related branch modifies.
In this example we explain four basic scenarios that are supported:
- WIP status is removed from Merge Request – this means code is ready for review, so entity state will be changed to 'Code Review';
- Branch is closed without any code merged – user story should return to backlog, so the state will be changed to 'Open';
- Merge request is approved – development is completed and the user story, bug or feature is ready for testing, state is changed to ' To Test';
- Branch was merged, card's state will be changed to final or 'Integrated'.
Create a new branch / merge request from entity view via custom field
You can add an Automation Rule which will trigger branches (and merge requests) auto creation.
To support branch creation from the view, you need to create a drop down custom field for required entities and list the repositories here. Repositories should be listed without parent sub-groups.
Here is an example of the automation rule. You can copy it completely using ‘raw json’ editor mode and paste into your account’s rule.
Customize entity views
By default, the DevOps section appears in the feature, user story, task or bug view as soon as any branch or merge/pull request is linked with this entity ID. However, branch or request might be linked with any entity in Targetprocess. With the customized layout feature, there is an option to show 'DevOps Integrations' not only on these four views, supported by default, but on any other entity view.
If you have been using the Customized Entity Layout for features, stories, bugs or tasks, then after adding the Integration profile, you will need to add a DevOps section manually into all customized entity views.
Watch the recording of our webinar “How to Define the Right DevOps Metrics” we hosted together with Icon Agility Services to learn how to define and collect the right metrics to see a full picture of your value streams, including DevOps.