HelsinkiHint - Source Control

"How do we backup our app and manage file versions?"  

This is usually one of the first questions I get when I start working with a new software vendor who's building an app for the ServiceNow store. Before the Helsinki release, developers needed to resort to exporting a copy of an application update set for offline storage, or leverage team development to copy the code to another instance. These solutions provide a source code backup, but is not what typical software developers think of when they think of source control. The Helsinki release introduces source control within the instance.

Will it meet the needs of developers? Let's take a look.



First, a few things to note before you get started. Since this blog series is mostly targeting developers, I'm going to assume you already understand the basic values and concepts of source control and versioning.

  • The source control feature supports Git repositories (repo)
  • Any Git repo (github, bitbucket, private servers, ...) is supported, provided the instance has access to it
  • ServiceNow instances provide the function of a local repo
  • Each ServiceNow app will have its own repo
  • Repos must be created before you can link an app
  • Source control management happens from the Studio interface

Before you get too excited, here are some limitations you should be aware of.

  • ServiceNow instance is the sole owner of all code. Code changes cannot be made in the remote repository other than pushed from a linked instance. That means there's no editing of source files from external sources.
  • All application files that would be included in an app update set or pushed to the store can be pushed to the remote repo.
  • Application files are stored in the same XML format that's used in update sets. Script sources are still buried in the XML file and not easily extracted for external automated testing.

Now that we have that out of the way, let's take a look into the power of source control for you app.


Getting started

As I mentioned, each ServiceNow app will have its own repo. Once you create the remote repo, just add the url and credentials in your app from Studio, and you can start pushing updates. If you want to bring the app source code into another instance for development, you can also import from Studio source control menu. When importing an existing app, you'll have full control of the app since file protection policies aren't applied here. It's essentially the same as importing an app's update set.



Once you start adding or changing files in your app, the changes can be committed to the remote repo. You'll see a list of new and modified files, but committing is an all-or-nothing concept here. You cannot select a subset of your changes.  


If you have a lot of changes at once (not really recommended), you can filter the list to review what you are committing. Just be aware that you are still committing the full list, not the filtered list.

As with any repo, you'll be able to view the committed remote files from your normal git client. Just be sure to limit your access to read-only from external clients.

Technically, you'll have the ability to push changes from any git client to this repo, but don't even think about it. The local repo in ServiceNow stores and validates it's own hashed checksum of the repo state. It definitely will not like you if it finds out you've been working behind its back.


Pulling from remote

If you only have a single development instance you might not see value in pulling from the remote but we'll cover more cases when we get into branching. For those of you with multiple development instances, you might need to apply remote changes more often. As with most development environments, you'll have a conflict if you try to apply remote changes if you have uncommitted local changes. Again, think all-or-nothing. If you do have local changes, you'll be able to stash them if you aren't ready to commit.



Stashing is supported as a way to save your changes but remove them from the instance. The stash is saved in the instance's local repo.

The challenge with stashing is that you can't view the files in a stash from Studio. If needed, you can view the list of stashes and files from the sys_repo_stash table. The stash table is simply an extension of the retrieved update set table and its components are standard update set records.



If conflicts are encountered when applying remote or stashed changes you'll be prompted to resolve them first. Your choices are to accept or discard the stashed changes, or manually review and apply the differences for each file.



Branching and why you need it

Ok, now for something cool. Branching isn't really anything to get excited about for developers already using git. However, having the ability to switch branches of app update records can be quite valuable to any ServiceNow developer. If you've ever had to add development instances just so you could swap between patching a current app release and working on the next release, you'll love branches. Branches are snapshots of a repo at a given commit level. Each instance using the remote repo can use a different branch. The power is when you use a single instance to switch between app v1 code and v2 code on the same instance, without any conflict in code. You can think of this concept as uninstalling one update set or app state and installing another, and switch back anytime.

The current branch used for the instance can be viewed from the upper-right corner of the Studio interface.


The biggest thing to be aware of when working with branches, is that there are no checks for any dependencies. If the branch was created from another instance and depends on plugins or tables you will most likely run into problems when applying the branch in an instance without the required components. 



This is the initial release of source control in the ServiceNow platform. While it may not meet all of your needs today, start leveraging for the reasons that will add value to your development lifecycle. As with most version 1 features, I expect functionality to expand over the next release or two. Be sure to share your feedback directly with the platform teams if you're attending Knowledge16 this week.

You can also share your thoughts here as I'm frequently working with the ServiceNow product teams on future design concepts.