Synchronize branches with Guidewire VCS

Warning:

You're fully responsible for setting up and maintaining the configuration for the bring-your-own code repository method. For details, see Bring-your-own code repository.

With a set of Git commands, you can set up synchronization of code between the Guidewire VCS and your remote repository. The synchronization doesn't require cloning the code.

Important:

To synchronize branches between the Guidewire VCS and your remote repository, you must keep the same standards and requirements as when using only Guidewire VCS directly. In particular, you can't push changes in the Guidewire Layer as they will be rejected when pushing to the Guidewire VCS, even if you successfully pushed the changes to your repository.

For details on changes in the Guidewire Layer, see Troubleshooting.

Prerequisites

To set up code synchronization between your remote repository and the Guidewire VCS, ensure that:

• You are working on an initialized Git repository.

  If you want to create CI automation that works only as a sync between two repositories, and you don't want to clone the code, use the git init command to set up a Git repository as a step.

• You have Git Large File Storage (LFS) installed and initialized.

  You can check this with the git lfs install command.

• You can authenticate to both repositories with Git.

  For details on how to authenticate to the Guidewire VCS in Git using a command line, see Authentication to a Git repository.

Set up two remote repositories

To set up two remote repositories, one that is your repository, and the other that is Guidewire VCS, run the following commands:

git remote add source <url_to_your_repository>
git remote add gwmanaged <url_to_guidewire_vcs_repository>

Where:

• <url_to_your_repository> is a Git URL to your remote repository.
• <url_to_guidewire_vcs_repository> is a Git URL in the HTTPS format to the Guidewire VCS repository.

If your Git repository setup already contains remote repository URL to one of the repositories, you can omit a command related to it.

Tip:

This guide uses the following example names for remote repositories: - source as an example name for your remote repository. - gwmanaged as an example name for a remote repository in the Guidewire VCS.

You can replace them with different names.

Copy a branch from the Guidewire VCS to your remote repository

To copy a branch from the Guidewire VCS to your remote repository:

1. Ensure that the two remote repositories are set.

   For details, see Set up two remote repositories.

2. Update the information about both remote repositories:

   git remote update

3. Fetch the information about Git LFS objects from the Guidewire VCS. It can be done in one of the following ways:

   • Fetch the information for a specific remote branch:

     git lfs fetch gwmanaged refs/remotes/gwmanaged/<branch_name> --all
     Where:
     • <branch_name> is a branch in the Guidewire VCS that you want to synchronize with your repository.

   • Fetch the information for all the branches in the remote repository:

     Linux

     git for-each-ref --format="%(refname)" refs/remotes/gwmanaged | while read ref; do git lfs fetch gwmanaged $ref --all; done
     PowerShell on Windows

     git for-each-ref --format="%(refname)" refs/remotes/gwmanaged | ForEach-Object { git lfs fetch gwmanaged $_ --all }

   Note:
   

   Flag --all in git lfs fetch command ensures that files from all the commits visible for a passed branch will be fetched. If you require any change in the list of commits for which files are fetched, check git lfs fetch command documentation.

4. (Optional) Verify if all the LFS files from the branch that you want to push are available.

   Large files are kept in the Guidewire VCS repositories using Git LFS. You must fetch these files from the remote repository to know which files should be moved between the two remote repositories.

   To check if all the LFS files are available for the branch that you want to push from the Guidewire VCS to your remote repository, run the following command:

   git lfs fsck refs/remotes/gwmanaged/<branch_name>

   Where:

   • <branch_name> is a branch in the Guidewire VCS that you want to synchronize with your repository. In case of any files missing, the command will list them.

   Important:
   

   To execute git lfs fsck command directly on the remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.

5. Push code from the Guidewire VCS to your remote repository.

   git push source 'refs/remotes/gwmanaged/<branch_in_gw_repository>:refs/heads/<branch_in_your_repository>'

   Where:

   • <branch_in_gw_repository> is a branch in the Guidewire VCS that you want to synchronize with your repository.
   • <branch_in_your_repository> is a branch name in your remote repository to which you want to push code.

   Branch in your remote repository doesn't have to exist before pushing to it.

6. Push all the tags related to the branch pushed from Guidewire VCS to your remote repository.

   Linux

   git tag --merged refs/remotes/gwmanaged/<branch_in_gw_repository> | while read tag; do git push source "refs/tags/$tag"; done

   PowerShell on Windows

   git tag --merged refs/remotes/gwmanaged/<branch_in_gw_repository> | ForEach-Object { git push source "refs/tags/$_" }

   Where:

   • <branch_in_gw_repository> is a branch in the Guidewire VCS that was pushed in the previous step.

Copy a branch from your repository to the Guidewire VCS

To copy branch from your remote repository to the Guidewire VCS:

1. Ensure that the two remote repositories are set.

   For details, see Set up two remote repositories.

2. Update the information about both remote repositories:

   git remote update

3. Fetch the information about Git LFS objects from your remote repository. It can be done in one of the following ways:

   • Fetch the information for a specific remote branch:

     git lfs fetch source refs/remotes/source/<branch_name> --all
     Where:
     • <branch_name> is a branch in your remote repository which you want to synchronize to the Guidewire VCS.

   • Fetch the information for all the branches in a remote:

     Linux

     git for-each-ref --format="%(refname)" refs/remotes/source | while read ref; do git lfs fetch source $ref --all; done
     PowerShell on Windows

     git for-each-ref --format="%(refname)" refs/remotes/source | ForEach-Object { git lfs fetch source $_ --all }

   Note:
   

   Flag --all in git lfs fetch command ensures that files from all the commits visible for a passed branch will be fetched. If you require any change in the list of commits for which files are fetched, check git lfs fetch command documentation.

4. (Optional) Verify if all the LFS files from the branch that you want to push are available.

   Large files are kept in the Guidewire VCS repositories using Git LFS. You must fetch these files from the remote repository to know which files should be moved between the two remote repositories.

   To check if all the LFS files are available for the branch that you want to push from your repository to the Guidewire VCS, run the following command:

   git lfs fsck refs/remotes/source/<branch_name>

   Where:

   • <branch_name> is a branch in your remote repository that you want to synchronize with the Guidewire VCS. In case of any files missing, the command will list them.

   Important:
   

   To execute git lfs fsck command directly on the remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.

5. Push code from your remote repository to the Guidewire VCS.

   git push gwmanaged 'refs/remotes/source/<branch_in_your_repository>:refs/heads/<branch_in_gw_repository>' --follow-tags

   Where:

   • <branch_in_your_repository> is a branch name in your remote repository which you want to synchronize with the Guidewire VCS.
   • <branch_in_gw_repository> is a branch in the Guidewire VCS to which you want to push code.

   Branch in your remote repository doesn't have to exist before pushing to it.

6. Push all the tags related to the branch pushed from your remote repository to Guidewire VCS.

   Linux

   git tag --merged refs/remotes/source/<branch_in_your_repository> | while read tag; do git push gwmanaged "refs/tags/$tag"; done

   PowerShell on Windows

   git tag --merged refs/remotes/source/<branch_in_your_repository> | ForEach-Object { git push gwmanaged "refs/tags/$_" }

   Where:

   • <branch_in_your_repository> is a branch in your remote repository that was pushed in the previous step.

Push the code from your local setup to a specified remote repository

You can work from your local repository with both the Guidewire VCS or your remote repository without the synchronization process. With this method, you can push the code on which you are working locally to both Guidewire VCS and your remote repository.

If you want to push to both remote repositories, make sure that you have both of the remote repository URLs set in your local Git repositories. For details, see Setup of two remote repositories.

Check out a branch from a remote repository to your local branch

To check out a new local branch from a remote repository, run the following command:

git checkout -b <local_branch_name> <remote_name>/<remote_branch_name>

Where:

• <local_branch_name> is the name of a local branch to which you want to checkout the code from the remote repository.
• <remote_name> is the name of a remote repository from which you want to check out the code to your local branch, for example source or gwmanaged.
• <remote_branch_name> is the name of a remote branch on which the code is available in the remote repository.

Push the code from your local setup to a specified remote repository

To push the code from your local branch to the specified remote repository, run the following command:

git push <remote_name> <local_branch_name>:<remote_branch_name>

Where:

• <remote_name> is the name of a remote repository to which you want to push the code from your local branch, for example source or gwmanaged.
• <local_branch_name> is the name of a local branch from which you want to push the code to the remote repository.
• <remote_branch_name> is the name of a remote branch from which the code will be pushed to the remote repository.

If you want to push tags related to the branch that you pushed, run the following command:

Linux

  git tag --merged <local_branch_name> | while read tag; do git push <remote_name> "refs/tags/$tag"; done

PowerShell on Windows

git tag --merged <local_branch_name> | ForEach-Object { git push <remote_name> "refs/tags/$_" }

Where:

• <local_branch_name> is the name of a local branch that you pushed.
• <remote_name> is the name of a remote repository to which you want to push the tags, for example source or gwmanaged.

Branch in your remote repository doesn't have to exist before pushing to it.

Compare your local branch with a remote repository

Before pushing code, you can compare the lists of commits between your local branch and the remote branch:

git log --left-right <local_branch_name>...<remote_name>/<remote_branch_name>

Where:

• <remote_name> is the name of a remote repository on which the compared remote branch exists, for example source or gwmanaged.
• <local_branch_name> is the name of a local branch which you want to compare with a remote branch.
• <remote_branch_name> is the name of a remote branch which you want to compare with your local branch.

Example output:

< commit abc1234567890abcdef
Author: Example User <example@example.com>
Date:   Mon Apr 1 12:34:56 2024 +0000

    Commit only in local branch

> commit def9876543210fedcba
Author: Example User 2 <example2@example.com>
Date:   Tue Apr 2 09:00:00 2024 +0000

    Commit only in remote branch

Where:

• < indicates commits unique to the local branch.
• > indicates commits unique to the remote branch.

Note:

To check if there is any commit difference between the branch in your remote repository and in the Guidewire VCS, you can execute the following command:

git log --left-right gwmanaged/<branch_in_gw_repository>...source/<branch_in_your_repository>

Where:

• <branch_in_gw_repository> is a branch in Guidewire VCS which you want to synchronize to your repository.
• <branch_in_your_repository> is a branch name in your remote repository to which you want to push code.

Troubleshooting

These are the most common issues with synchronization between the two remote repositories:

• Push to the Guidewire VCS fails because of the Guidewire Layer modification.

  Git push operation fails because one of the new commits that you tried to push modifies files inside the Guidewire Layer.

• Changes are rejected because of the differences in history.

  Git push operation fails because the pushed branch and the target branch differ in history.

• Changes are rejected because of the lack of permissions or incorrect authentication.

  Git push operation fails either because authentication setup is incorrect, or the user that is used for authentication has incorrect branch restrictions.

  In case of authentication to the Guidewire VCS, see Troubleshooting in Authentication to a Git repository.

• LFS tracked files don't exist or are malformed after a push to the remote repository.

  Only the references to the files that are tracked by Git LFS were pushed, not the contents of those files.

• Branch was pushed to the remote repository, but tags connected to commits within that branch weren't pushed.

  This issue can happen if you don't use, for example, --follow-tags with the push command. To resolve this issue, re-add the missing tags manually in the target repository.

Guidewire Layer modifications

If you make changes to the Guidewire Layer, pushing those changes to the Guidewire VCS will be rejected with the information about violation.

For details on Guidewire Layer and the recommended approach, see Guidewire Layer and Customer Layer in the InsuranceSuite documentation.

Warning:

If you rebase an existing commit that contains changes to the Guidewire Layer, for example, a commit with the new InsuranceSuite release provided by Guidewire, the commit hash might change.

During pushing to the Guidewire VCS, such a commit will be treated as a new change and violation of the Guidewire Layer modification.

Different Git history of commits in the target branch

When pushing branches, either from a local branch or during synchronization between two remote repositories, operation might be rejected with the Updates were rejected because the tip of your current branch is behind its remote counterpart error or similar. The error means that there is a conflict in commits between a branch you are trying to push and a target branch.

To resolve this error:

• When pushing from a local branch.

  1. Compare commits between your local branch and a target remote branch. For details, see Comparing your local branch with specific remote repository.
  2. Resolve conflicts locally and then push the changes.

• When synchronizing two remote branches between two remote repositories.

  1. Checkout branches from both remote repositories to separate local branches.
  2. Compare commits between created branches. For details, see Comparing your local branch with specific remote repository.
  3. Resolve conflicts or merge changes from both local branches to one of them.
  4. Push the changes with resolved conflicts to both remote repositories under the original branch name.

Warning:

Resolving conflicts might result in a different history for at least one of the remote repositories. You might need to do push with the --force option.

Before pushing, ensure that all the required changes are in the local branch from which you will be pushing, as pushing with the --force option will rewrite the history of the target branch.

Malformed LFS files

Note:

• If you encounter an issue with malformed LFS files, check if you have Git LFS installed and set up in the local repository from which the code was pushed.
• If you want to ensure that all the LFS files are ready to be pushed from the local branch, use the git lfs fsck <branch_name> command which should check the state of LFS files on a branch.

When you don't fetch or pull the files tracked by Git LFS and push only references to those files, these files are malformed.

If the malformation happens during the synchronization from one remote repository to the other, you can try to find the missing files and push them to the remote repository:

1. Ensure that you have the up-to-date data from both remote repositories:

   git remote update

2. Fetch information about LFS files for the pushed remote branch containing malformed files:

   git lfs fetch <source_remote> refs/remotes/<target_remote>/<branch_name>

   Where:

   • <source_remote> is the name of the remote repository from which the branch with the malformed LFS files was synchronized.
   • <target_remote> is the name of the remote repository to which the branch with the malformed LFS files was pushed.
   • <branch_name> is the name of the remote branch in the target remote repository.

3. Check if the LFS files were properly downloaded and are available:

   git lfs fsck refs/remotes/<target_remote>/<branch_name>

   Where:

   • <target_remote> is the name of the remote repository to which the branch with the malformed LFS files was pushed.
   • <branch_name> is the name of the remote branch in the target remote repository.

   Important:
   

   To execute git lfs fsck command directly on the remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.

4. Get and save the commit hash for the target remote branch:

   git rev-parse refs/remotes/<target_remote>/<branch_name>

   Where:

   • <target_remote> is the name of the remote repository to which the branch with the malformed LFS files was pushed.
   • <branch_name> is the name of the remote branch in the target remote repository.

   Note:
   

   This step is required, because the git lfs push command doesn't understand remote references (refs/remotes/...). It expects a local branch or a commit hash.

5. Push only LFS files to the target remote repository for the remote branch:

   git lfs push <target_remote> <commit_hash>

   Where:

   • <target_remote> is the name of the remote repository to which the branch with the malformed LFS files was pushed.
   • <commit_hash> is a commit hash retrieved from the previous step, to which the remote branch points.