GitHub Integration

GitHub Account Setup

Step 1: Create GitHub Account and Log In

• Sign up or log in to GitHub.

Step 2: Create Organization and Repository

1. In GitHub, create an organization if necessary.

2. Set up a repository with similar parameters as Bitbucket:

   • Project Name

   • Repository Name

   • Default Branch: "main"

Step 3: Add StagingPro as admin collaborator in repository

Open

1. Link your GitHub repository to StagingPro.

2. Add StagingPro as an Admin collaborator to allow seamless integration.

Step 5: Verify Repository

Open

1. Log in to StagingPro and connect to Github.

2. Enter the repository URL in StagingPro under Settings > Connect Repository.

3. Verify the account, and you will receive a success message.

Step 6: Add Team Members

1. Click on Add Team member you will see below screen where you can see user verification form.

When adding a team member their GitHub id also needs to be entered in order to add the user to the StagingPro branch for your project.

Step 7: Remove User

• To remove a user, click "Remove" in StagingPro. This action removes the user from StagingPro but not from GitHub.

Step 8: Change Permissions

• Change user permissions by navigating to the user settings and modifying their access.

• By selecting “Change Permission,” you can give each team member access to individual staging environments. It is recommended that you restrict access to your production store to only those users who actually need it.

IMPORTANT:
Github Actions and workflow processes should be assigned to your development team who will review and fixes the notifications visible on the deployment logs. Once all log items are reviewed and fixed by your development team, the StagingPro code deployments will be successful.

Staging Pro Repository and Branches

Before installing StagingPro in your tenant, you need to create an organisation repository in GitHub and add StagingPro as an Admin collaborator. Then you can associate your organisation repository with your StagingPro tenant. StagingPro will automatically create branches based on your linked environment setup in StagingPro

When you add Git users in the ‘Connect GitHub’ tab, it creates team member branches for each environment branch (e.g. Production, Staging, UAT etc).

Code commits to the respective StagingPro branch, will show up in the History & Rollback > Code Deployment tab

Staging Pro Deployment workflow

The following illustration shows the suggested ideal process as part of the Git development workflow with Pull request, that can be implemented as part of your StagingPro setup.

And the following illustration shows the suggested ideal process for hot fixes as part of the Git development workflow with direct commit to the Production environment.

As a general rule of thumb, developers first commit codes to their local branch, before it reviewed and approved for merge with a shared branch (e.g. Production branch)

After StagingPro is linked with your Git repository, the active branches are programmatically generated and these names must NOT be changed.

StagingPro Git Branch workflow

As part of theme deployment workflow, consider the following StagingPro setup showing your mapped environments for Production, Staging and UAT.

Now consider GitHub users (developer and designer) added to StagingPro using the ‘Connect GitHub’ tab

The following ‘Git Branches’ illustration, highlights the flow that brings the following components together:

• StagingPro repository on your Git Organisation

• Webhook configured environments Production, Staging, UAT

• Storefront channels per environment

• GitHub users developer and designer.

• GitHub user branches

StagingPro Git Branch Code Deployment

This is accessible under the ‘History & Rollback’ tab and click on ‘Code Deployment’ sub-tab. This shows the list of git commits of your connected GitHub repository that is visible within your StagingPro environment

Status case: Awaiting Approval

A Git commit is visible on the grid, but requires your approval before the code is merged to the respective environment.

You get two options:

• Approve and Deploy - where you can deploy the code straightaway

• Generate Preview and Approve Later - where you can preview the codes on a generated preview site for visual reference

If you click to Generate Preview, you can select the version of Node.Js compatible with your Git commit preview and click to Launch. Please give it some time (up to 5 minutes) as it spins up a temporary preview url for visual validation.

Status case: If you approve the code

The code will be committed to the respective branch and you will see the status of ‘Merge Successful | Theme deployed’
You will also see a ‘Rollback’ option to rollback to a previous version if required.

Status case: If there are errors/conflicts

If a conflict is detected in config.json, click to view and resolve any errors/conflicts

Status case: If you reject the code

The status will show as ‘Rejected|Code Not approved’

A few GitHub FAQS

Q1. After giving Admin access to StagingPro Git repository, I see some autogenerated code branches e.g. Productione347c1, so should I keep the names as it is?
A1. Yes, that is correct. These environment branch names are autogenerated and required for code commit tracking. Please do not delete or rename these branches as it will affect the GitHub integration.

The branches are created i) per environment ii) per channel and iii) per team member

Q2. What is the purpose of developer branches?
A2. As best practice, developers are given their own branches so they can commit their codes to their own branch at the first instance, or for more frequent code commits at the developers convenience without affecting the environment branch.

Q3. Are there any benefits to using a developer branch over a more typical git feature branch (e.g. feature/TICKET-description-of-the-change)?
A3. Yes indeed! The developer can commit to their branch first. Once the task is complete, they can merge the code from their branch to the environment branch. If many developers are working on a common task, they can commit codes to each of their individual branches without affecting the other developer branches. And can merge their code easily.

Q4. What purpose does the Main/Master branch serve in a typical setup?
A4. Master branch is generally used as a buffer branch and is the default branch while creating a repo in GitHub. This master ‘buffer’ branch can be left as it is. Instead use the autogenerated active branches that is automatically (with a name such as Productione347c1) created during your GitHub integration and linking process.

Q5. Is there a way to export from Bigcommerce to Github through StagingPro? Or will I need to download the current theme through storefront and upload it to Github separately?
A5. As long as GitHub integration is connected and at a minimum, one team member user is added in the ‘Settings’ section, then yes - StagingPro automatically downloads the theme into the connected branch.

Q6. When I commit changes in Github, will those changes will appear as rollback options in StagingPro?
A6. Correct. After the GitHub integration is set, commit changes are tracked and rollback options are visible on the deployments grid.

Q7. Can you explain how version control works for StagingPro with multiple development teams as part of existing CI/CD pipelines?
A7. When you successfully configure the GitHub integration on your StagingPro tenant, your GIT commits will be visible on the ‘Code Deployment’ tab which displays incremental version numbers. The code branches are created i) per environment ii) per channel and iii) per repo team member. Refer the ‘StagingPro Git Branch workflow’ section of this document. Under Settings > Status Notifications you can enable the Deployment Notifications checkbox for team notifications through i) Email ii) Teams and iii) Slack for shared visibility and effective collaboration.

Video Guide