Bitbucket Account Setup
Step 1: Sign up or log in to Bitbucket Account
Visit Bitbucket's official website, create an account, and log in.
Step 2: Create Workspace
Upon logging in, click “Create workspace.”
Provide the workspace details and proceed.
Step 3: Create Repository
Add Repository:
Enter Project Name
Enter Repository Name
Set Access Level
Important: Always set the default branch name as "main."
After successfully creating the repository, a URL similar to this will be generated:
https://bitbucket.org/{workspace}/{repository}/src/main/.
in stagingpro you need URL like this workspace/repository e.g.,“themedeploy-stagingpro/stagingpro-repo/”
Step 4: Add User to Bitbucket Workspace and Repository
Navigate to the repository and click on the settings icon.
Go to "User Management" and click on "Invite."
Here click on Invite button and the redirect to Invite people to Bitbucket screen.
Enter the bitbucket@stagingpro.com
Product Role: Click on the drop down field and click on the relevant checkbox
There will be 3 group permissions:
bitbucket-admins
bitbucket-user-access-admins
butbucket-users
Select the group permission "bitbucket-admins-themedeploy-stagingpro"
Add stagingpro as a user, assign it "Admin" permission at the repository level
Now again go back to previously selected repository then click on Invite it will redirected to repository permission and then again click on "Add user or group "
Click on Invite users button to send the invitation
For additional users:
Assign developer permissions.
Follow similar steps, but assign different permissions.
Step 5: Verify Repository
Log in to StagingPro and connect to Bitbucket.
Enter the repository URL in StagingPro under Settings > Connect Repository.
Click on Verify Bitbucket Account, Grant access and you will receive a success message.
Step 6: Add Team Members
Click on Add Team member, a popup window to enter Bitbucket username and Bitbucket name will be displayed
To get username and name, sign into Bitbucket account, click on the settings cog wheel on the top right-hand corner and then click on “Personal Bitbucket Settings”
https://bitbucket.org/account/settings/
In the following screenshot, you can get the Bitbucket name and Bitbucket username as follows:
Bitbucket Name: Theme Deploy
Bitbucket Username: themedeploy
Enter the Bitbucket username and Bitbucket name and click on save. Then the following popup window to select the environment type will be displayed. Click the checkbox on the desired environment for branch creation and click on confirm button.
Step 7: Change Permissions / environment type
Click on the Change permission button to remove existing environment or select any other environment.
Step 8: Remove User
To remove a user, click "Remove" in StagingPro. This action removes the user from StagingPro but not from Bitbucket.
Create OAUTH Token
1) Add OAuth Consumer
Click on Settings > workspace settings > OAuth Consumer > Add Consumer
2) After entering all the necessary fields on the OAuth Consumer form, click on save.
https://bitbucket.org/bigisagingpro/workspace/settings/api
Code Deployment Process
a) Workflow for direct commit
Clone the environment branch by using the command
git clone --branch $branchName https://userId:$oauthToken@bitbucket.org/ravistaging/stagingprobigi.git $branchName
After cloning branch go the folder Make some changes in the files
Open gitbash and write cd Productione160c1(“cloned folder);
git clone --branch branchname https://bigistagingprolatest:$authtoken@bitbucket.org/bigistagingpro/stagingprostaging.git branchname
After cloning branch do cd branchname
Make changes in the required file
git status to check the changes
git add --all : to add all the changes
git commit -m 'Commit Message'
git push origin branchname
Then go to code deployment screen there you can see the direct commit changes like this
By clicking on “Generate Preview and Approve Later” link user can launch Preview for direct commit
Click on “Approve and Deploy to initiate deployment
Workflow for Pull Request
Create Pull request in your bitbucket account under repository section
See the left menu and click on “Pull request”
Click on create pull request on the top right side then select the Environment branch for the destination branch dropdown.
you will see this screen where you can add your comment and then click on “approve” and “merge”
After clicking merge you will see this screen
You can add your comment but do not made modifications on top commit message like “Merged in Akanksha247e160c1472899 (pull request #12)” and simply click on “Merge” button Then you will start seeing entries like this under “Code Deployment”
Here you can see the generate Preview link click on “Generate Preview and Approve Later” link and select the correct note version from dropdown and then again click on “Launch Preview” button.
After generating Preview you will see screen like this
Click on “Preview Ready”
Click on Top link like this “https://fifty-olives-prove.loca.lt” to see the preview.
Click on Approve and Deploy then you will see screen like this
After some time refresh the page and click on "Deployment logs" and by going down see latest comment similar like this “Bundled saved to: 20240223-6.5.0.zip which means theme is downloaded properly and now the stencil server Cron will pick the theme and do the deployment.
Maximum Theme Notification:
In some case if user already have maximum no of theme which is 20 then user will see screen below screen then please select the theme user want to delete, click ok and then refresh the page to see the update.
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 BitBucket users (developer and designer) added to StagingPro using the ‘Connect BitBucket’ 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
BitBucket users developer and designer.
BitBucket 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 BitBucket 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 BitBucket 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 BitBucket 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 BitBucket. 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 BitBucket integration and linking process.
Q5. Is there a way to export from Bigcommerce to BitBucket through StagingPro? Or will I need to download the current theme through storefront and upload it to BitBucket separately?
A5. As long as BitBucket 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 BitBucket, will those changes will appear as rollback options in StagingPro?
A6. Correct. After the BitBucket 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 BitBucket 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.