> ## Documentation Index > Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt > Use this file to discover all available pages before exploring further. # GitHub and Bitbucket Integration in StagingPro for BigCommerce StagingPro uses Git as the deploy pipeline for BigCommerce theme code. You connect either a GitHub repository (recommended via the GitHub App) or a Bitbucket workspace, then push commits through a pull-request workflow with preview URLs, approval, and one-click rollback. This page covers both integration paths and the deployment workflow that runs on top. ## 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 replaced the older Classic Token and Fine-Grained PAT setups. Use GitHub Apps unless your security policy specifically requires manual PAT-based access. ## GitHub Apps setup GitHub App connect screen 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: 1. **The repository must be under a GitHub Organisation, not a personal account.** Create an Organisation at [https://github.com/settings/organizations](https://github.com/settings/organizations) if you do not have one yet, then create the repo inside it. 2. **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. 3. **A private repository is recommended** for security. Create new repo as private ### Type 1, the user has install rights 1. Sign in to StagingPro and click **Connect to GitHub App**. 2. Click **Authorise**. Authorise GitHub App, type 1 3. Select your GitHub Organisation. 4. Select **Only select repositories**, pick the relevant repo, click **Install**. Select repository for install 5. After redirect back to StagingPro, the **Settings, Connect Repository** tab now shows the connected repo. Allow 3 to 5 minutes for StagingPro to auto-create the base environment branches based on the number of channels configured per store. ### Type 2, the user does not have install rights The requester (no install rights) submits a request, the approver (install rights) reviews and approves. 1. The requester clicks **Connect to GitHub App**, **Authorise**, picks the Organisation, picks the repo, clicks **Request**. 2. StagingPro shows a "Request submitted" notification on Settings, Connect Repository. 3. The approver signs in to GitHub, clicks **Review request**, picks **Only select repositories** for the relevant repo, clicks **Approve & Install**. 4. The requester then sees the GitHub repo connected on the StagingPro Settings tab. If the approver rejects, GitHub still leaves an entry in the Apps list which must be uninstalled before logging a helpdesk ticket to reset the connection. ## Adding GitHub team members After the repo is connected, add the developers and designers who will commit code: 1. Click **Add Team Member** on the Settings, Connect Repository tab. 2. Enter the team member's GitHub email and Git User ID. Add Team Member popup 3. Pick the environments they should have access to and the permission level (based on [GitHub roles](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles)). 4. Click **Save**. StagingPro will create a per-environment, per-channel, per-team-member branch for the new user. Allow 5 to 10 minutes for branches to be ready and the theme file to be pulled into them. To remove a user, click **Remove**. This removes them from StagingPro but not from the underlying GitHub repository. To change permissions, click **Change Permission**, adjust, 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. Important rules: * **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. Developer branches let multiple developers commit to their own branch first, then merge into the environment branch. This isolates work between developers and avoids cross-developer conflicts. ## 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: ``` https://bitbucket.org/{workspace}/{repository}/src/main/ ``` StagingPro needs the workspace/repository portion, e.g. `themedeploy-stagingpro/stagingpro-repo/`. ### Step 2, invite the StagingPro Bitbucket user In Bitbucket, navigate to repository Settings, User Management, Invite. Invite `bitbucket@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/](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 1. Developer commits to their personal developer branch. 2. Code review happens in GitHub or Bitbucket. 3. PR merged into the target environment branch (Staging first, then UAT, then Production). 4. 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 | Generate Preview spins up a temporary preview server and installs the theme. Pick the compatible Node.js version (14 to 24 supported), click **Launch**, and the preview URL becomes available within about 5 minutes depending on theme size. After approval, the actual deploy to BigCommerce takes 15 to 20 minutes depending on theme size. StagingPro builds the theme bundle, uploads it to BigCommerce, and BigCommerce installs it to the target channel. ### 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 workflow](/vortex-apps/staging-pro/stagingpro-github-deployment-workflow) ## Important 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.