Git
Git integration for PowerShell Universal.
Last updated
Git integration for PowerShell Universal.
Last updated
Copyright 2024 Ironman Software
PowerShell Universal is capable of synchronizing the configuration scripts with a remote git repository. You can use the Configuration settings to setup git sync.
PSU Git sync does not handle merge conflicts automatically and you should ensure that you prepare for the first sync before configuring it.
By default, PowerShell Universal will sync with the master branch. If you wish to use a different branch, specify the GitBranch setting within your appsettings.json.
You will need to configure authentication to your remote git repository. We recommend a personal access token.
The default location for the local repository is C:\ProgramData\UniversalAutomation\Repository
You must ensure that your local folder is not a pre-existing git repository. Your repository directory should be simply a folder with your PowerShell Universal files. If a .git folder exists, and you do not wish to use this repository, you should delete it and PowerShell Universal will create a new repository.
If you are populating a new git repository, you need to ensure that the remote does not have any files in it. It should be a completely bare repository. For example, when creating a repository on GitHub, do not select a license or readme.md file to be created.
Once the repository has been created, you can retrieve the git remote URL and provide that to the PowerShell Universal appsettings.json file.
Once you have the branch, git remote URL and credentials, you can provide them to your appsettings.json file and the git remote will be populated with your local files.
The default location for the local repository is C:\ProgramData\UniversalAutomation\Repository
You can configure PowerShell Universal to pull from a git remote. In this configuration, you must ensure that your local repository folder is completely empty. Any files within the folder will cause the git sync to fail and prevent it from recovering.
Configure the appsettings.json file to include the branch, credentials and git remote URL that you are cloning. Once the fields have been set, you can start the PowerShell Universal service. The first thing the service will do is clone the repository and configure it locally.
The files that are included with a git sync are any files within the local repository. This includes PS1 configuration files, pages XML files and any other files you may add manually.
The following are not included:
appsettings.json
database.db
web.config
PowerShell Universal Application Binaries
The git status page lists the synchronized repository, branch and the list of commits that have occurred.
By default, git synchronization will work both ways. If you make changes within the PSU admin console, those changes will be committed and sync'd to the configured remote.
Any changes that are made in the remote will be pulled locally.
If you setup git sync with a preexisting git remote, the changes will be pulled and synchronized locally. You cannot have any changes locally.
If you setup git sync with a bare repository, the local changes will be sync'd and the repository will be initialized.
You can adjust the git synchronization behavior by changing the GitSyncBehavior setting in appsettings.json. When set to OneWay, the admin console and management API will become read-only. The PowerShell Universal system will pull from the remote but will never push or commit locally.
PowerShell Universal 2.6 or later.
Push-only git sync mode will not pull changes from the remote. Any changes made locally will be pushed up to the remote. The console will not be read-only. This configuration is useful for scenarios where you have one machine that is used to for the source-of-truth configuration for a pool of servers that are read-only.
Requires PowerShell Universal 2.10 or later.
Defines the git initialization behavior. If this parameter is not set, PowerShell Universal will attempt to select the proper method based on the state of the local file system.
Clones the remote to the local repository folder. The local folder must be empty.
Initializes the local repository and pushes it to the remote. The remote must be bare.
We recommend that you use a personal access token (PAT) over a user name and password. You can configure a personal access token by setting the password property in the appsettings.json or other configuration methods.
In GitHub, you can retrieve a personal access token by clicking your avatar in the top right, selecting Settings, Developer Settings and then Personal Access Tokens.
When generating your access token, ensure that you select the Repo permissions.
Note, that if you are using BitBucket, you will need to specify the user name in addition to the PAT in appsettings.json.
You can also configure a git remote to authenticate with a user name and password. Set the user name and password either with the appsettings.json file or another configuration method.
It is possible to manually git sync a repository. PowerShell Universal uses very basic commands when dealing with git. Any changes made to PowerShell Universal through the admin console or API invoke a git commit and the author is set to the identity of the user making the change. During a git sync operation, we first perform a git pull to ensure that we have the latest version of files on the remote. Next, we perform a git push to push up local commits that have happened since the last sync.
You could achieve this functionality with a scheduled job.
That said, one feature of the git sync is that it analyzes the commit to ensure that only files that were changed during the sync are reloaded. This will stop dashboards from auto-deploying when they haven't changed or APIs services from restarting when environments haven't been updated. So there is a performance gain here.
The other issue is that due to the way that PowerShell Universal watches files (with a FileSystemWatcher) and the way that git updates files, the configurations will not reload automatically after a pull. You will have to ensure that you force the configurations to be reevaluated.
