(!) Available in the Pro and Enterprise plans
You may decide to document your production environment changes due to:
Best practice - proper documentation helps with debugging production issues / root cause analysis, knowledge sharing and onboarding new team members.
SOX compliance - publicly traded companies are required to meet certain financial processes, including documentation of all of their financial related changes, e.g., changes in Salesforce financial related elements or any changes in NetSuite or Zuora. This is needed to prove to the auditors that the company is following all of the requirements correctly.
Initial Setup
First, make sure to set up a scheduled fetch so that your Salto production environment is regularly updated with changes in the relevant business applications.
Secondly, make sure to connect a git provider with your Salto org by following the instructions here
Then, connect your Salto production environment to a branch in the git repository. To do so, go to the Audit tab at the top and click on the ‘Connect Git’ CTA.
🚧 Please make sure that you have write permissions to the connected git branch (aka not ‘push protected’)
Lastly, make sure to connect your Git provider with your ticketing provider, e.g., Jira or Zendesk. Doing this allows any documented change from Salto with a ticket-id mention to appear in the mentioned ticket in your ticketing system, along with a link to the changed code in Git. This is helpful in documenting your changes from request (the ticket itself) throughout the change in production.
How to document your changes
Salto provide two primary ways to document changes:
The person who makes the changes, documents them as they happen in each deployment. Read more about this flow here.
Alternatively, or in addition to #1 above (documenting any fetched changes which were done directly in the business application, and not via Salto), you can document changes after they happened. To do so, start from the Audit tab where you can see:
At the top, the pending changes that should be documented. Click on ‘Preview Push’ to document these changes.
Below, under the ‘Commit History’ headline you can see the previously documented changes. Each change includes the name of the user who documented the change and the commit (documentation) message. Below the vertical 3-dots menu you have a link to the code change in your Git provider.
Preview Push
This is where the actual documentation takes place. On the left, you can see each of your configuration files that contains a change. The +, - & M symbols indicate whether the change is an addition, e.g., a new field, a deletion, or a modification, e.g., a value change. Files with multiple different changes, e.g., additions and deletions will appear with an M symbol.
Clicking on a file will allow you to see the exact change by comparing the file version before the change and after it.
You can select one or more files or all of them via the ‘Select All’ CTA at the bottom.
In some business applications, you can also use the Changed By and Changed At filters to quickly find recent changes, or changes made by a specific user. This can help you find the latest changes made by you or other users.
On the right side you can document the nature of the change via the title and message boxes. Selecting at least one file and adding a title enables the ‘Push’ button. Clicking the button will commit your message, along with the code change to Git.
Make sure to mention your ticket number, e.g., in Jira that would be your project name and the ticket number: name-3754, so that your comment and link to the code change in Git will appear in the relevant ticket in your ticketing system.
You can mention multiple tickets within one Push event if your code change addressed multiple tickets. Similarly you can select multiple files with one ticket and Push event, if your ticket was addressed by changes in multiple files.
Salto supports Jira ‘Smart Commits’. This feature allows actions such as commenting on or closing a ticket in Jira, directly from Salto. Enabling this feature in Jira also allows you to automatically add a list of all of your documented file names by adding {{fileNames}} to your commit message.
Hiding Files and Folders
In some cases, you may want to only document changes to a specific set of files - for example, if you have sensitive configuration elements, and you only wish to document changes to them.
In this case, Salto supports hiding elements that you do not wish to document from the "Preview Push" screen.
To do this, click the "..." menu next to a folder or a file you wish to hide, and select Hide File.
Once hidden, the selected files and folders won't show up by default in the Preview Push file-tree. You can still see them by opening the "Hidden Files" menu and toggling the "Show Hidden Files" option.
Note that only environment owners and administrators can add or remove hidden files.