Expand your SuiteScript skills in the Sustainable SuiteScript community for NetSuite developers.

Source Control Repository Layouts for NetSuite Development

Created: February 16, 2021

When I started my first SuiteScript job nearly a decade ago, seven developers shared a single branch of a single SVN repository. All of our code - for over 30 different NetSuite accounts at the time - lived in a giant monolith.

For the smaller clients who required a single developer once in a while, this was mostly fine as it at least gave us an off-site backup, and there was never overlap. For any larger client, or clients with concurrent projects, it was completely impossible to keep from overwriting or conflicting with each other's changes. I avoid reflecting on how many hours of life were lost staring bleary-eyed at the Tortoise SVN conflict resolution window.

There were myriad problems with our approach to source control then. In the intervening decade - as a developer, a manager, and now an advisor - I've observed and advised many SuiteScript teams on implementing or revamping their source control strategy. Recently, as part of a DevOps Diagnostic for a client, I put together a brief comparison of the various repository structures I've seen for SuiteScript development since the advent of SDF, and I thought I'd share that comparison with you, too.

Below are four different repository and SDF project layouts that I commonly see SuiteScript teams use; for each layout, I've given my own quick summary of the workflow as well as the pros and cons as I see them. For the folder structure images, imagine each is from the perspective of a developer who has all of their development work, NetSuite and beyond, stored in a folder named my-dev-work.

I've left out the workflow for actually writing the code as that is driven by your branching scheme more than your repository layout. If you're interested, I've previously spelled out my branching scheme, and I have a free email course intended to help you define one for your team.

Single Repository for All Clients

Don't do this.

Pros

None.

Cons

All.

Single Repository, Single SDF Project

Each Client has a single Repository, and each Repository contains a single SDF Project for the entire Account.

File Structure

Pros

  • All NetSuite customization work for a Client Account lives in exactly one place.

Cons

  • Must manually manipulate deploy.xml for every deployment; this is error-prone, hard to track, and confusing to merge.
  • Have to remember to never commit changes on deploy.xml or ignore the file entirely.
  • Tags require an extra layer of identification/naming for the feature (e.g. " projectB-v1.2.1" instead of "v1.2.1" in a project-specific repository).
  • Rollbacks are more complicated as all features are intertwined in a single project and repository, unless you have a disciplined release process which enforces one feature release at a time.
  • Deploying from main deploys the entire account, increasing the risk and impact of any error or mistake during deployment.

Single Repository, Multiple SDF Projects

Each Client has a single Repository, and each Repository contains multiple SDF Projects - generally one SDF Project per Feature.

File Structure

Pros

  • All NetSuite customization work for a Client Account lives in exactly one place.
  • No manual manipulation of deploy.xml because SDF projects are separated.
  • Risk and impact of overwriting configuration changes are greatly reduced because only a small portion of the account is ever involved in a deployment.

Cons

  • Rollbacks are more complicated as all features are intertwined in a single repo, unless you have a disciplined release process which enforces one feature release at a time.
  • Team must decide how to handle Objects/files which are shared across multiple SDF Projects. I typically use a separate Repository titled "NetSuite Core" containing a single SDF Project.
  • Tagging requires an extra layer of identification/naming for the feature ( e.g. "shiphawk-v1.2.1" instead of "v1.2.1" in a project-specific repo), and that only works if your releases only contain changes to one particular feature. If not, you have to get even more creative for consistent tagging.

Separate Repository and SDF Project for each Client Project

Each Feature gets its own Repository, and each Repository contains a single SDF Project. It becomes useful to group Repositories by Client from within the hosting platform and on local filesystems.

This is my personal preference.

File Structure

Pros

  • No manual manipulation of deploy.xml because SDF Projects are separated.
  • Rollbacks are easy; it's always the previous commit on main.
  • Tagging is easy; it's always an increment to a version number.
  • Risk and impact of overwriting configuration changes are greatly reduced because only a small portion of the account is ever involved in a deployment.

Cons

  • There is no single consolidated place for all NetSuite customizations for a particular Account.
  • Team must decide how to handle Objects/files which are shared across multiple SDF Projects. I typically use a separate Repository titled "NetSuite Core" containing a single SDF Project.

Account Comparison Automation

Due to the shared nature of the NetSuite environments (i.e. developers do not have their own individual development environments), there is always a risk of encountering Environmental Drift between what is committed to your repository and what is active in the NetSuite account. My manual process for comparing the contents of an SDF project to a NetSuite environment is outlined in this Environmental Drift article.

To automate this process, you might consider a Continuous Integration (CI) system like GitHub's Actions or GitLab's Pipelines or rolling your own. Here are some relevant articles on the topic of CI:

This CI process would:

  1. git switch to or git checkout the corresponding environment branch,
  2. git pull,
  3. perform an SDF project:update,
  4. perform a git diff between the environment branch and main

If any differences were detected between the branches, then there are likely unanticipated changes that need to be resolved, the "build" should fail, and developers should be alerted by the system.

This should help identify and prevent overwriting any configuration changes that have been made directly via the NetSuite UI or otherwise outside of the normal source control process. It will still be up to developers to manually compare using a similar process before they perform any deployments.

Do you use one of these repository layouts, or something else?

HTH

-EG