If you have developed vRealize Orchestrator content, you might have had the need to have that vRealize Orchestrator content shared across different instances. In previous vRealize Orchestrator versions you might have done this by creating Packages, exporting them to your local machine and importing them to another desired vRealize Orchestrator instance.
While that is still a valid way to do things, since the release of version 8, vRealize Orchestrator allows users to integrate with their own Git repositories. In this blogpost we will cover why that might be a good choice to do things and how one could configure, setup and perform basic actions with vRealize Orchestrator and Git.
What is Git?
First and foremost let us start by covering what exactly Git is. The official Git webpage describes it as the following:
“Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.”
Lets start by breaking down each of those terms one by one in reverse order:
- “…designed to handle everything from small to very large projects with speed and efficiency.” – The sky is the limit in terms of how big your project can be.
- “…version control system…” – Version control systems are tools that store and manage information about files in a versional manner, meaning that every change to a specific file can be traced to a specific version of that file.
- “…distributed…” – A particular Git project can be mirrored anywhere (as long as Git is installed).
- “…free and open source…” – Information about how Git works and its usage is completely free for everyone.
Git can be used to manage any kind of files, with code being the most popular way it is used. When Git is used as the version control system of choice to manage files, those files are said to be now part of Git repositories. A Git repository can be any directory which has been initialized as one. Achieving distribution using Git is primarily done by having a Git repository hosted somewhere (common choices include, but are not limited to GitHub, GitLab, Bitbucket, Azure DevOps and more) and cloned to users’ local machines. After that, any changes made in that mirror directory, either to its existing files, or to new ones, are tracked by Git. When a user is happy with their changes, they can choose to push them to the remote side, where other users, who have also cloned and mirrored the repository, can choose to pull them to their local machine.
Basic usage of the Git integration feature in vRealize Orchestrator
Now that we have a basic idea of what Git is and how it can be used, we will dive into how we could integrate a Git repository that we will create in order to transfer vRealize Orchestrator content across different instances.
In order to begin, first we will need to have a Git repository created. Choosing where our Git repository is hosted does not matter, since vRealize Orchestrator allows for integration with any Git provider’s repositories. For the purpose of this tutorial I will be using GitLab.
To create a Git repository in GitLab I would need to create a new GitLab project.
I will now be using this GitLab project to integrate a vRealize Orchestrator instance embedded in vRealize Automation and an external vRealize Orchestrator instance with that same Git repository. The process to do that is pretty simple and straightforward.
First you would need to be logged in the vRealize Orchestrator client as a user with the Orchestrator Administrator role in vRealize Automation. After you are logged in, in the navigation pane on the left, under the Administration section, you will find the Git Repositories tab. Navigating to it will lead you to the Git Repositories page which contains information about your currently added repositories and give you the option to add new ones. To add a new repository click the Add Repository button.
Clicking on the Add Repository button in the Git Repositories page will transfer you to the “New Git Repository” page. Here you will need to provide all the necessary details about your Git repository in order to integrate it with vRealize Orchestrator.
In order to get started you will need to grab your Git repository’s URL for cloning. If you are using GitLab, you can find that in your GitLab project’s page, under the Clone button. It will provide you with both SSH and HTTPS URLs for cloning.
Should you provide the SSH URL in vRealize Orchestrator, you will receive an option to choose a value for Key length, and a Public key with the desired key length. If you choose to integrate a Git repository in vRealize Orchestrator, you will need to add the provided Public key from vRealize Orchestrator as a Deploy Key to your GitLab project. This way SSH will be used for authentication between vRealize Orchestrator and the Git repository with the specified public/private key pair.
The other way to integrate a Git repository is by providing the HTTPS URL for cloning. This is the way that I will be doing things for the sake of this tutorial but you may choose whatever option fits your use case.
When we choose to integrate a Git repository that will be authenticating over HTTPS, we are provided with two blank fields that we will need to populate – Username and Token. The credentials that are requested to be filled in are the ones of a user which has permissions to read from and write information to the Git repository. In our case, we would need to have an access token generated for our Project from GitLab.
After we have provided the necessary details, we can validate that a connection can be established between vRealize Orchestrator and the Git repository by clicking on the Validate button. Upon success we will receive a message stating that a connection has been successfully made.
At this point we are ready to have our Git repository ready to be fully integrated with vRealize Orchestrator. All that is left to do is to toggle on the Make active repository option on and click the Save button.
We can now also choose what our Remote Branch will be. After making our choice from the list of the existing repository branches, we can Save our changes and we are ready to roll.
We now have a local copy of our Git repository in vRealize Orchestrator. We can now start pulling from and pushing changes to it. All of this can be done from the Git History tab under the Administration section in the navigation pane.
On this page we will see most of the needed information and tools to perform operations against our repository.
On the top we see information about the name of the Git repository that is currently active, the active remote branch that we will be working with, and a status message about our repository.
Below that are the Push and Pull buttons which we will both cover later on in this post.
Underneath the Push and Pull buttons is a two-way split view which contains all of the information about ours and the repository’s files. On the left part of it we have a timeline of the repository’s commit history. Commits are the changes that are being made over time to a particular repository. The way that they are shown is always by having the latest ones at the top of the timeline. We can select any commit from the timeline by clicking on it. To the right of the commit history timeline is a grid which displays the Modified content of the currently selected commit in the timeline. We can expand each file entry from the grid in order to see what are the changes made to it in regards to the active Git repository that we are using.
Initially, we would see a the status message at the top read “The remote branch is not pulled.”. This means that the changes that are available in the Git repository are not fully incorporated in vRealize Orchestrator. To make them part of our vRealize Orchestrator content library we would need to perform a pull operation which is achieved by clicking the Pull button.
After pulling what was available in the Git repository, our local changes are put on top of whatever has been pulled from the repository.
Local changes refer to the currently developed content in vRealize Orchestrator that is not part of the Git repository. In this case, I have created a simple Workflow element named “My Workflow” with one Input and an Action named “myAction”. We have the option to push either a subset of them, or all of them and to discard them.
I will be pushing all of my local changes because I want them to become part of the Git repository that I am using, so whenever another vRealize Orchestrator instance is integrated with the same Git repository, after they perform a pull operation, they would now have that content as part of their content library.
To push our local changes we would need to create a commit that would be pushed which starts by first clicking the Push button. We will then be navigated to the “Push Changes to Remote Branch” page where in order to proceed we would need to provide a bit of details for our commit:
- Commit title – Here we should provide a brief summary of what we are trying to achieve by pushing our changes.
- Commit message – Any additional details around our changes which would help future users of the same Git repository understand what and why exactly are the changes being made.
- Changed Item grid – The list of changed vRealize Orchestrator content that we want to include in our commit that is going to be pushed to the repository. Here is where we select either all of our local changes, or a subset of them.
When we are happy with the details of our commit we can proceed by clicking the Push button. After that we will be redirected back to the Git History page.
Once our push operation has succeeded, we will see our commit now part of the repository’s history in the timeline on the left and the status message update to “no local changes, 0 commits behind”, meaning that we are fully in sync with the repository. At this point our vRealize Orchestrator content changes are part of the Git repository that we have been using.
Earlier I mentioned that I would be using this repository to integrate both the embedded in vRealize Automation vRealize Orchestrator instance and an external vRealize Orchestrator instance with this repository. I will now switch to the external vRealize Orchestrator instance where I have gone through the process of adding the same repository that I have been using, by performing the same steps as already described. When I go to the Git History tab on the external vRealize Orchestrator instance, I would see pretty much the same thing as before – only differences being the local changes and the timeline containing one more commit than when we first opened the Git History tab on the embedded vRealize Orchestrator instance.
In order to grab the changes that are part of the repository, we would need again to perform a pull operation, following the same steps as before, by clicking the Pull button. After the pull operation succeeds we should see that the status message is now “several local changes, 0 commits behind”. We now also have the changes, that we previously committed from the embedded vRealize Orchestrator instance, be a part of the content library of the external vRealize Orchestrator instance, again with our local changes on the external vRealize Orchestrator instance put on top of the repository’s changes.
Wrap-up
By now you should be familiar with what Git as a tool is and how it can be used in vRealize Orchestrator. Git is a very powerful tool that can be used in a number of different ways and the way that you use it depends entirely on the specifics of your use case. In this post we covered how one could integrate a Git repository, that they have created, with their vRealize Orchestrator instance and pull changes from and push changes to it.
If you would like to learn more about anything Git related, you can take a look at the official Git webpage. A great read on Git basics and deep dives into some of the Git internals that I strongly recommend is the Pro Git book which you can download and read for free.
Credits
Git Logo by Jason Long.
