> ## 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 Integration in StagingPro for BigCommerce

StagingPro uses Git as the deploy pipeline for BigCommerce theme code. You connect a GitHub repository (recommended via the GitHub App), 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

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.

### Type 1, the user has install rights

1. Sign in to StagingPro and click **Connect to GitHub App**.
2. Click **Authorise**.
3. Select your GitHub Organisation.
4. Select **Only select repositories**, pick the relevant repo, click **Install**.
5. After redirect back to StagingPro, the **Settings, Connect Repository** tab now shows the connected repo.
6. 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.
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 auto-generated 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.

***

## 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.
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.