Syncing a Gitlab release branch with GitHub - RedHatInsights/red-hat-ansible-automation-platform-documentation GitHub Wiki

Automatic sync

A Jenkins job syncs the AAP Gitlab repo with this GitHub repo. The sync job runs every hour.

The instructions below describe a manual sync that you can execute when the Jenkins server is down.

Manually syncing a Gitlab release branch with Github

This article describes how to copy a release branch from the AAP docs GitHub repo to the AAP docs Gitlab repo.

Andrew Dahms has provided a script for a function called sync to automate this process.

If it is your first time syncing Gitlab to GitHub, follow the steps to set up the sync script in the Setting up and working with the sync script section.

Workflow

The Gitlab repo is the source for the AAP customer portal docs. Therefore, before you sync a release branch to Gitlab, checkout a local copy of the GitHub release branch and make sure that the docs build correctly. Once you have synced the Gitlab release branch with GitHub, checkout a local copy of the Gitlab release branch and make sure that the docs build correctly.

In this workflow, you will need to use the git log command. For convenience, set up an alias. Refer to the git log alias wiki article.

Connect to the VPN.
View the most recent commits for the release branch on both Gitlab (gitlab remote) and GitHub (upstream remote), either on a browser or by typing the following commands:
```
$ git fetch upstream && git log --oneline -n 2 upstream/<release_branch>
$ git fetch gitlab && git log --oneline -n 5 gitlab/<release_branch>
```
If you have set up the gl alias, these commands can be shortened as follows:
```
$ git fetch upstream && gl 2 upstream/<release_branch>
$ git fetch gitlab && gl 5 gitlab/<release_branch>
```
You will need the commit SHAs for the most recent commits in GitHub and Gitlab in the next step.

List the files that have been changed in the new commits in GitHub that haven’t been ported to Gitlab:

$ git diff --name-only <most_recent_GitHub_commit_SHA>..<most_recent_Gitlab_commit_SHA>

For example:

$ git diff --name-only 0a93b45..be3d6e
downstream/assemblies/platform/assembly-install-aap-operator.adoc
downstream/assemblies/platform/assembly-installing-controller-operator.adoc
downstream/assemblies/platform/assembly-installing-hub-operator.adoc
downstream/modules/platform/proc-install-aap-operator.adoc
downstream/modules/platform/proc-operator-external-db-controller.adoc
downstream/modules/platform/proc-operator-external-db-hub.adoc
downstream/titles/aap-operator-installation/master.adoc

Verify that the titles affected by the changed files build successfully.
1. Checkout a copy of the release branch from GitHub (upstream/<release_branch>).
  git checkout -b check-github-build upstream/<release_branch>
2. Build the titles affected by the changed files and check that the output looks OK.
Navigate to your sandbox directory and run the sync script to copy the new commits from GitHub to Gitlab.
```
$ sync <release_branch_name>
```
The following example syncs the 2.1 release branch:
```
$ sync 2.1
```
To verify that the sync script executed successfully, view the most recent commits on the Gitlab UI. Alternatively, run the following command:
```
git fetch gitlab && git log --oneline -n 5 gitlab/<release_branch>
```
If the sync script copied the commits to Gitlab, fetch the release branch from Gitlab and build the affected titles again.
```
git checkout -b check-gitlab-build gitlab/<release_branch>
```

If the builds ran successfully, you can delete the branches that you checked out:

$ git checkout main
$ git branch -D check-github-build
$ git branch -D check-gitlab-build

If the sync script failed and the commits have not been copied to Gitlab, post a message in the aap-product-docs Slack channel.

Setting up and working with the `sync` script

Andrew’s sync script (requires VPN): Synchronizing the Red Hat Ansible Automation Platform repository.
The script is a function that you must add to your ~/.bashrc or ~/.zshrc file.
The script was written for a RHEL environment. To run it on a Mac, you must modify the if statement syntax.

Using the `sync` script

Before you begin

The sync script clones a copy of the AAP Gitlab repo, and deletes it after merging changes into the Gitlab repo.
Do not run the sync script from within your local repo, or from the parent directory of your repo.
It is useful to create a "sandbox" directory on your machine and run the sync script from there.

Prerequisites for interacting with the AAP Gitlab and GitHub repositories

In the GitHub repo, you have configured a git remote called gitlab that points to the GitLab repo. This git remote is required so that you can fetch and build the synced branch from Gitlab after you have run the script; it is not a requirement for executing the sync script.

To check whether you have set up a Gitlab remote, run the git remote -v command from your local GitHub repo to list your remotes. The following example shows the part of the output that you see if you have configured the gitlab remote.
```
$ git remote -v
gitlab [email protected]:red-hat-cloud-services-software-documentation/red-hat-ansible-automation-platform-documentation.git (fetch)
gitlab [email protected]:red-hat-cloud-services-software-documentation/red-hat-ansible-automation-platform-documentation.git (push)
```
Step 6 of Setting up your copy of the repository describes how to set up a git remote that points to the Gitlab repo.
You are connected to the Red Hat VPN. This is a requirement for accessing the Gitlab repo.
You have set up ssh authentication for Gitlab and GitHub.
You have maintainer privileges on the Gitlab repository. Your privileges are listed in the max role column in Documentation - CCS Internal Group members page on Gitlab.

Setting up the `sync` script

Linux users

Follow the procedure on the sync script page to copy the script to your ~/.bashrc file.

Mac users

Use the modified script that works on a Mac, but follow the procedure on the sync script page to add the modified script to your ~/.zshrc file.

Running the `sync` script

Run the following command
```
sync <release_branch_name>
```
The following example syncs the 2.1 release branch:
```
sync 2.1
```

Modified sync script that works on a Mac

###################################################################
# Migrate content from GitHub to GitLab - modified for use on a mac
###################################################################

function sync () {

# Navigate to a sandbox directory so you won't interfere with your existing cloned repo
# Modify this line to navigate to your own sandbox directory
cd ~/Documents/sandbox

    if [ -z "$1" ]
    then
        echo "No branch specified; exiting..."
        return 1
    fi

# Changed the git clone command to clone only the branch that you want to port over to gitlab
# As you're cloning the Gitlab repo, the origin remote refers to the Gitlab repo.
    git clone -b $1 --single-branch [email protected]:red-hat-cloud-services-software-documentation/red-hat-ansible-automation-platform-documentation.git

    cd red-hat-ansible-automation-platform-documentation

# Changed the git remote command to only view the GitHub branch that you want to port over to gitlab
# Create an upstream remote that points to the GitHub repository
         git remote add -t $1 upstream [email protected]:RedHatInsights/red-hat-ansible-automation-platform-documentation.git

# Checkout gitlab/<release_branch>
    git checkout $1

# Fetch github/<release_branch>
    git fetch upstream $1

# Identify the latest commits in upstream (GitHub) and origin/downstream (Gitlab)
    LATEST_DS=`git log --oneline -n 1 | cut -f1 -d ' '`
    echo "Most recent downstream (Gitlab) commit: $LATEST_DS"
    LATEST_US=`git log --oneline -n 1 upstream/${1} | cut -f1 -d ' '`
    echo "Most recent upstream   (GitHub) commit: $LATEST_US"

# This if statement syntax didn't work on a mac: if [ ${LATEST_DS} == ${LATEST_US} ]
# Modification for mac:
    if [[ $LATEST_DS == $LATEST_US ]]
    then
        echo "Already up to date; exiting..."
        return 0
    fi

    TIMESTAMP=`date +"%m-%d-%Y %H:%M:%S"`
# Print the timestamp on the screen
    echo "$TIMESTAMP"

# Merge the github branch (upstream) into gitlab (origin). Gitlab is currently checked out.
    git merge upstream/$1 -m "Upstream updates from ${TIMESTAMP}."

# Push to gitlab (origin)
    git push origin $1

# Delete the cloned repo
    cd ..
    rm -rf red-hat-ansible-automation-platform-documentation
}
##########################################