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 external repository. The synchronization doesn't require cloning the code.

Important:

To synchronize branches between the Guidewire VCS and your external 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 external 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 the two remote repositories

See an example video with the procedure on setting up the two repositories:

Tip:

This guide uses the following example names for the remote repositories:

source - an example name for your external repository.
gwmanaged - an example name for a Guidewire-managed repository in Bitbucket.

You can replace them with different names.

To set up two repositories: one that is your external repository and the other that is the Guidewire-managed repository in Bitbucket, 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 external repository.
<url_to_guidewire_vcs_repository> is a Git URL in the HTTPS format to the Guidewire-managed repository.

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

Copy a branch from Guidewire-managed to your external repository

See an example video with the procedure on copying a branch from the Guidewire-managed repository to your external repository:

To copy a branch from the Guidewire-managed repository to your external repository:

Ensure that the two repositories are set. For details, see Set up the two repositories.
Update the information about both the repositories:
```
git remote update
```
Fetch the information about Git LFS objects from the Guidewire-managed repository. 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-managed repository that you want to synchronize with your external repository.
- Fetch the information for all the branches in the Guidewire-managed 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 the git lfs fetch command ensures that files from all the commits visible for the passed branch will be fetched.
  If you need to make any changes to the list of commits for which the files are fetched, check the git lfs fetch command documentation.
(Optional) Verify if all the LFS files from the branch that you want to push to are available.

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

To check if all the LFS files are available for the branch that you want to push from the Guidewire-managed repository to your external repository, run the following command:
```
git lfs fsck refs/remotes/gwmanaged/<branch_name> 
```
Where:
- <branch_name> is a branch in the Guidewire-managed repository that you want to synchronize with a branch in your external repository. In case of any files missing, the command will list them.
Important:
To execute the git lfs fsck command directly on a remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.
Push the code from a branch in the Guidewire-managed repository to a branch in your external 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-managed repository that you want to synchronize with your external repository.
- <branch_in_your_repository> is a branch name in your external repository to which you want to push the code.
Note:
The branch in your external repository doesn't have to exist before pushing to it.

Push all the tags related to the branch pushed from the Guidewire-managed repository to your external 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-managed repository that was pushed in the previous step.

Copy a branch from external to Guidewire-managed repository

See an example video with the procedure on copying a branch from your external repository to the Guidewire-managed repository:

To copy branch from your external repository to the Guidewire-managed repository:

Ensure that the two repositories are set. For details, see Set up the two repositories.
Update the information about both the repositories:
```
git remote update
```
Fetch the information about Git LFS objects from your external repository. It can be done in one of the following ways:
- Fetch the information for a specific branch in your external repository:
```
git lfs fetch source refs/remotes/source/<branch_name> --all
```
  Where:
  - <branch_name> is a branch in your external repository which you want to synchronize with a branch in the Guidewire-managed repository.
- Fetch the information for all the branches in your external repository:
  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 the git lfs fetch command ensures that files from all the commits visible for the passed branch will be fetched.
If you need to make any changes to the list of commits for which the files are fetched, check the git lfs fetch command documentation.
(Optional) Verify if all the LFS files from the branch that you want to push from are available.

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

To check if all the LFS files are available for the branch in your external repository that you want to push from to the Guidewire-managed repository, run the following command:
```
git lfs fsck refs/remotes/source/<branch_name>
```
Where:
- <branch_name> is a branch in your external repository that you want to synchronize with the Guidewire-managed repository. In case of any files missing, the command will list them.
Important:
To execute the git lfs fsck command directly on a remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.
Push the code from your external repository to the Guidewire-managed repository.
```
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 external repository which you want to synchronize with the Guidewire-managed repository.
- <branch_in_gw_repository> is a branch in the Guidewire-managed repository to which you want to push code.
Note:
The branch in your external repository doesn't have to exist before pushing to it.

Push all the tags related to the branch pushed from your external repository to the Guidewire-managed repository.

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 external repository that was pushed in the previous step.

Push the code from your local setup to one of the two repositories

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

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

Check out a local branch from one of the two repositories

To check out a new local branch from one of the two repositories, 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 one of the repositories.
<remote_name> is the name of the repository, either Guidewire-managed or your external repository, from which you want to check out the code to your new local branch.
For example source or gwmanaged.
<remote_branch_name> is the name of a remote branch on which the code is available in one of the repositories.

Push the code from your local setup to one of the two repositories

To push the code from your local branch to one of the two repositories, run the following command:

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

Where:

<remote_name> is the name of a repository, either Guidewire-managed or your external 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 repository.
<remote_branch_name> is the name of a remote branch in either the Gudiewire-managed or your external repository to which the code will be pushed.

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 one of the repositories, either Guidewire-managed or your external repository, to which you want to push the tags, for example source or gwmanaged.

Note:

The branch in your external repository doesn't have to exist before pushing to it.

Compare your local branch with a remote branch

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

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

Where:

<remote_name> is the name of a repository, either Guidewire-managed or your external repository, in 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 the remote branch.
<remote_branch_name> is the name of a remote branch with which you want to compare 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 a branch in your external repository and a branch in the Guidewire-managed repository, you can run 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 the Guidewire-managed repository which you want to synchronize with your external repository.
<branch_in_your_repository> is a branch name in your external repository to which you want to push the code.

Troubleshooting

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

Push to the Guidewire-managed repository fails because of the Guidewire Layer modification.

The 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.

The git push operation fails because the pushed branch and the remote branch differ in history.
Changes are rejected because of the lack of permissions or incorrect authentication.

The 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 repository.

Only references to the files that are tracked by Git LFS were pushed, not the contents of those files.
Branch was pushed to one of the repositories, but tags connected to commits within that branch weren't pushed.

This issue can happen if you don't use --follow-tags with the git push command. To resolve this issue, 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-managed repository 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-managed repository, such a commit will be treated as a new change and violation of the Guidewire Layer modification.

Resolve Git history conflicts in target branch

When pushing branches, either from a local branch or during synchronization between the two 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. This error means that there is a conflict in commits between a branch that you are trying to push from and the remote branch.

To resolve this error:

When pushing from a local branch.
1. Compare commits between your local branch and the target remote branch. For details, see Compare your local branch with the remote branch.
2. Resolve conflicts locally and then push the changes.
When synchronizing the 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 Compare your local branch with the remote branch.
3. Resolve conflicts or merge changes from both the branches to one of them.
4. Push the changes with resolved conflicts to both repositories under the original branch name.

Warning:

Resolving conflicts might result in a different history for at least one of the 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 remote branch.

Malformed LFS files

Note:

If you encounter an issue with the 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 the 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 repository to the other, you can try to find the missing files and push them to the affected repository:

Ensure that you have the up-to-date data from both the repositories:
```
git remote update
```
Fetch information about LFS files for the remote branch containing malformed files:
```
git lfs fetch <source_remote> refs/remotes/<target_remote>/<branch_name>
```
Where:
- <source_remote> is the name of the repository from which the branch with the malformed LFS files was synchronized.
- <target_remote> is the name of the affected repository to which the branch with the malformed LFS files was pushed.
- <branch_name> is the name of a remote branch in the affected repository.
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 affected repository to which the branch with the malformed LFS files was pushed.
- <branch_name> is the name of a remote branch in the affected repository.
Important:
To execute the git lfs fsck command directly on a remote reference (refs/remote/...), you must use Git LFS at least at version 3.0.
Get and save the commit hash for the remote branch:
```
git rev-parse refs/remotes/<target_remote>/<branch_name>
```
Where:
- <target_remote> is the name of the affected repository to which the branch with the malformed LFS files was pushed.
- <branch_name> is the name of a remote branch in the affected 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.
Push only LFS files to the affected repository for the remote branch:
```
git lfs push <target_remote> <commit_hash>
```
Where:
- <target_remote> is the name of the affected 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.

Prerequisites​

Set up the two remote repositories​

Copy a branch from Guidewire-managed to your external repository​

Copy a branch from external to Guidewire-managed repository​

Push the code from your local setup to one of the two repositories​

Check out a local branch from one of the two repositories​

Push the code from your local setup to one of the two repositories​

Compare your local branch with a remote branch​

Troubleshooting​

Guidewire Layer modifications​

Resolve Git history conflicts in target branch​

Malformed LFS files​

Prerequisites

Set up the two remote repositories

Copy a branch from Guidewire-managed to your external repository

Copy a branch from external to Guidewire-managed repository

Push the code from your local setup to one of the two repositories

Check out a local branch from one of the two repositories

Push the code from your local setup to one of the two repositories

Compare your local branch with a remote branch

Troubleshooting

Guidewire Layer modifications

Resolve Git history conflicts in target branch

Malformed LFS files