Pick your repository: GitHub or Bitbucket
| Provider | Recommended for | Connect path |
|---|---|---|
| GitHub via GitHub App | Most teams. One-click OAuth, organisation-level install, automatic token rotation, granular permissions. | Settings, Connect Repository, Connect to GitHub App |
| Bitbucket | Teams already standardised on Atlassian. | Settings, Connect Repository, Bitbucket. Invite bitbucket@stagingpro.com to the workspace. |
GitHub Apps setup
The install supports two flows depending on whether the StagingPro user has GitHub App install rights on the target organisation.
Pre-checks before connecting
Three things to validate before you click Connect:- The repository must be under a GitHub Organisation, not a personal account. Create an Organisation at https://github.com/settings/organizations if you do not have one yet, then create the repo inside it.
- The repository must have a README committed. A file must exist in the repo before linking, otherwise StagingPro cannot create branches and the link will fail.
- A private repository is recommended for security.
Type 1, the user has install rights
- Sign in to StagingPro and click Connect to GitHub App.
- Click Authorise.
- Select your GitHub Organisation.
- Select Only select repositories, pick the relevant repo, click Install.
- After redirect back to StagingPro, the Settings, Connect Repository tab now shows the connected repo.
Type 2, the user does not have install rights
The requester (no install rights) submits a request, the approver (install rights) reviews and approves.- The requester clicks Connect to GitHub App, Authorise, picks the Organisation, picks the repo, clicks Request.
- StagingPro shows a “Request submitted” notification on Settings, Connect Repository.
- The approver signs in to GitHub, clicks Review request, picks Only select repositories for the relevant repo, clicks Approve & Install.
- The requester then sees the GitHub repo connected on the StagingPro Settings tab.
Adding GitHub team members
After the repo is connected, add the developers and designers who will commit code:- Click Add Team Member on the Settings, Connect Repository tab.
- Enter the team member’s GitHub email and Git User ID.
- Pick the environments they should have access to and the permission level (based on GitHub roles).
- Click Save.
Branch model, the autogenerated structure
StagingPro auto-generates branches with this structure:- Per environment, e.g.
Production,Staging,UAT,Integration1. - Per channel, branches suffixed with channel hash, e.g.
Productione347c1. - Per team member, individual developer branches forked from the environment branch.
- Do not rename or delete autogenerated branches. They are required for commit tracking; renaming breaks the integration.
- The Master / Main branch acts as a buffer / default branch in GitHub. StagingPro uses the autogenerated active branches, not Main.
Bitbucket setup
If you use Bitbucket instead:Step 1, Bitbucket workspace
Create a Bitbucket workspace (or use an existing one). Inside it, create a project and a repository. Set the default branch name to main. The full URL format is:themedeploy-stagingpro/stagingpro-repo/.
Step 2, invite the StagingPro Bitbucket user
In Bitbucket, navigate to repository Settings, User Management, Invite. Invitebitbucket@stagingpro.com with all three product roles (User, Product admin, User access admin) and the group permission bitbucket-admins-{workspace-name}. Click Invite users.
Step 3, verify in StagingPro
Open StagingPro, Settings, Connect Repository. Enter the workspace/repository URL. Click Verify Bitbucket Account. On grant, a success message appears.Step 4, add team members in StagingPro
Click Add Team Member, enter the Bitbucket username and Bitbucket name (visible at https://bitbucket.org/account/settings/ in your personal Bitbucket settings). Save, then pick which environments to provision branches for. The team member must already have access to the Bitbucket repository workspace, otherwise the branch creation will not surface their commits.Deployment workflow, the recommended GitHub flow
StagingPro supports both standard PR-based deployment and direct-commit hotfix flow.Standard PR-based deployment
- Developer commits to their personal developer branch.
- Code review happens in GitHub or Bitbucket.
- PR merged into the target environment branch (Staging first, then UAT, then Production).
- StagingPro picks up the merged commit and surfaces it on History and Rollback, Code Deployment with status Awaiting Approval.
Hotfix deployment
For urgent fixes, commit directly to the Production environment branch. The commit appears on Code Deployment immediately for approval and deploy.Deployment statuses on Code Deployment
| Status | Meaning | Available actions |
|---|---|---|
| Awaiting Approval | Commit appears on grid, needs review | Approve and Deploy, Generate Preview and Approve Later |
| Approved & Deployed | Merge successful, theme deployed to environment | Rollback |
| Errors / Conflicts | Conflict detected (e.g. in config.json) | Resolve conflicts or Reject |
| Rejected | Code not approved | No further action |
Rollback
The Action column on a deployed entry includes a Rollback button. Clicking it redeploys the previous theme version to the same environment. Please refer this article for detailed information on deployment workflowImportant practices
- Connect at least one team member to the Connect Repository tab. StagingPro only auto-downloads the theme into the connected branch when at least one user is added.
- Restrict Production-environment access to only the users who actually need it. Use the Change Permission flow to give developers Staging and UAT only.
- GitHub Actions and workflow notifications must be reviewed and fixed by your development team. StagingPro deployments only succeed when all workflow log items are clean.
To view our Onboarding steps, please access the following article → StagingPro Onboarding