Organization/Product/Project Mapping Best Practices

Introduction to Branching Strategy

In order to understand how Mend Products and Projects should be mapped to an application, we first need to understand a development team's branching strategy. The following articles explain a common branching strategy referred to as the GitFlow Methodology. There are many other branching strategies, however, GitFlow is extremely common and one of the most robust examples so it will be used to cover the majority of questions.

GitFlow Primer

• Gitflow Workflow | Atlassian Git Tutorial

  • Git, Gitflow and Pull Requests - {Pro}Coders Best Practice Series

  • A successful Git branching model

Other Branching Examples

• GitHub Flow is a simpler branching strategy and the difference between the two is explained in Getting started with branching workflows, Git Flow and GitHub Flow

• A breakdown of different common branching models - 4 branching workflows for Git

Mend Organizations & Development Branches

Planning and implementing source code branching is a complex topic.  When done properly, it’s easy to manage, otherwise it can be a nightmare.  The same applies to how you manage and name your Mend organizations and the products and projects within them.

There are typically three common goals an end-user is looking to see from a Mend scan/project.

• A Software Bill of Materials (SBOM) of a released application and its associated vulnerabilities and licenses

  • Release branches &/or tags

• Vulnerabilities and licenses introduced or remediated through features or hotfixes

  • Feature/Hotfix branches

• The current state of vulnerabilities and licenses for an application that is in development

  • Mainline branches (Main,Master, Dev)

Each of these end goals is accomplished through a different Mend Organization.

There are several ways to implement the Mend software.  These are the two most common:

• Repository Integration

  • When configured properly, the Repository Integration already provides a clean structure.  All results appear in the SCM tool and the “Production” results will appear in the Mend UI.

  • An unseen SHADOW organization is created automatically by the repository integration and automatically purges data that is 30 days old.

• Pipeline/Unified Agent Integration

  • The pipeline determines which organization to send the results and product/project name can be customized at will.  In many implementations, the results are sent to the same organization which can create usability issues depending on how many different repositories/branches have been stored in the same organization.  A few examples of this:

    • Production and Non-Production results are combined

    • Production reports can be hard to generate

    • Report generation can be slow

  • Products & Projects are not deleted automatically and cleanup will need to be performed by a maintenance script

  • A “Development” organization must be created manually instead of an unseen SHADOW organization

    • Effective Licenses, Copyright, & Attribution adjustments should be performed on the Production/Release organization.

A “development” organization is not required, and this can be accomplished using project tags. However, this does require scripting and API knowledge which is a more complex approach than what is described below.

Repository Integration Example

Umbraco-CMS

Looking at the release tags and active branches, this application has the following attributions

• two production release streams of 9.x.x and 8.x.x

• a new v10 release stream that has yet to release

• feature branch streams of v8/feature/xxx, v9/feature/xxx, v10/feature/xxx

• bugfix branch of v9/bugfix/xxx and v8/bugfix/xxx

You can also understand the way they use gitflow by reading Umbraco-CMS/CONTRIBUTING.md at v10/contrib · umbraco/Umbraco-CMS

With this understanding, here are some examples of Organization/Product/Project mapping for this customer

Github.com Branch Settings

"baseBranches": ["v10/contrib", "v9/contrib", "v8/dev"]

Product name will change to the following for each integration

Pipeline Integration Example

In the example below, all of the production results appear in “ABC-Production” and the development results appear in the “ABC-Development” organization.  By doing this, running reports against “ABC-Production” will result in a perfect manifest of actual production results and development results are easy to find due to the product / project breakout. 

Application Name: Flight Simulator

Branching Strategy: Gitflow

Source Code Management Details

• Repository 1 Name: Flight Recorder

• Repository 2 Name: Event Processor

• Repository 3 Name: GPS

Mend UI Details
Organization Name: ABC-Production

Unified Agent Environment Variable Examples

Product Name = Team Name, Business Unit or Application Name
export WS_PRODUCTNAME=Flight Simulator

Product Version = Application Version that is in production
export WS_PRODUCTVERSION=V1
or to be more dynamic and pull the current git tag
export WS_PRODUCTVERSION=$(git describe --tags)

Project Name = Repo name_branch name
export WS_PROJECTNAME=$(basename -s .git $(git config --get remote.origin.url))_$(git branch --show-current)

Organization Name: ABC-Development

Unified Agent Environment Variable Examples

Product Name = Repo name
export WS_PRODUCTNAME=$(basename -s .git $(git config --get remote.origin.url))

Project Name = Repo name_branch name
export WS_PROJECTNAME=$(basename -s .git $(git config --get remote.origin.url))_$(git branch --show-current)

Development Organization Maintenance

Running https://github.com/mend-toolkit/sca-cleanup-tool nightly will ensure that your “ABC-Development” organization stays clean and relevant by removing unused projects which will provide a better Mend UI experience.

There are several configuration settings to help ensure that you are successful.  For most cases, the recommended practice is to remove anything that has not been updated in 21 days as shown in the following command

mend_sca_cleanup_tool -r 21 -m FilterProjectsByUpdateTime -u <USER_KEY> -k <ORG_TOKEN>

Unified Agent Scanning Example

Jenkins - https://github.com/whitesource-ft/ws-examples/blob/main/CI-CD/Jenkins/Jenkins_pipeline_maven_multi-org.groovy