Part 1. GitHub account setup
Step 1. Create or sign in to GitHub
Sign up or log in to GitHub. A valid GitHub ID is mandatory. If you do not have one, sign up here.Step 2. Create an organisation and a repository
GitHub integration requires three pre-checks.The repository must be created under an Organisation account, not a Personal account
If you do not yet have an organisation account, follow the GitHub documentation on organisations. Then navigate to your repositories and click New.
Enter a suitable Repository Name (for example, Staging). It is recommended that the repository be Private. Click Create Repository.
The repository must include a README file at creation
The README option must be selected when creating the repo, otherwise no file exists in the repo and Vortex Staging cannot create branches against it. You will get an error during the linking step. Validate this before linking your GitHub repository to your Vortex Staging environment.Add vortexiq as an Admin collaborator
You now have a repository with no branches; collaborators are needed before linking can succeed.
- Click Settings.
- Click Collaborators and Teams.
- Click Add People.
- Add
vortexiqas a collaborator with the Admin role. - Click Add vortexiq to this repository.
Step 3. Link your GitHub repository to Vortex Staging
For VortexIQ to accept the invite, click on the<> Code icon in the menu tab and copy the page URL.
Log in to Vortex Staging and connect to GitHub:
- Enter the repository URL in Vortex Staging under Settings, Connect Repository.
- Click the Verify button. You will receive a success message if the linking is successful.
Then click Add Team Member to specify a team member email for adding them to the repo, and use the Change Permission button to update repository permissions.
Step 4. Add team members
- Click Add Team Member; you get a screen displaying the user verification form.
- Enter the team member’s GitHub ID; this adds them to the Vortex Staging branch for your project.
- Each environment you have created becomes visible. Specify the permissions you want and create per-environment branches if a new environment was added after adding the team member.
- Permissions follow the GitHub documentation on roles.
- Click Save to add the team member.
- Branches are automatically created based on your linked environment setup. Adding a Git user creates team-member branches for each environment branch (for example, Production, Staging, UAT).
Step 5. Remove a user
To remove a user, click Remove in Vortex Staging. This action removes the user from Vortex Staging but not from GitHub itself.Step 6. Change permissions
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. GitHub Actions and workflow processes should be assigned to your development team, who will review and fix the notifications visible on the deployment logs. Once all log items are reviewed and fixed, the Vortex Staging code deployments will be successful.Part 2. Recommended deployment workflow
This section explains the recommended Git-based deployment workflow when using Vortex Staging, including standard deployments, hotfixes, approvals, previews, and rollbacks. GitHub Actions and workflow processes should be assigned to your development team. Once all log items are reviewed and fixed, the code deployments will succeed.Staging repository and branches
Before installing Vortex Staging in your tenant, create an organisation repository in GitHub and addvortexiq as an Admin collaborator. Then associate your repository with your Vortex Staging tenant. Vortex Staging automatically creates branches based on your linked environment setup.
When you add Git users in the Connect GitHub tab, it creates team-member branches for each environment branch (for example, Production, Staging, UAT).
Code commits to the respective Vortex Staging branch will show up in the History and Rollback, Code Deployment tab.
Standard deployment (pull request based)
The following illustration represents the ideal Git development workflow using Pull Requests, implemented as part of your Vortex Staging setup.
Developers should first commit code to their local or personal branch. Code is then reviewed and approved before being merged into a shared branch (for example, Production).
Hotfix deployment (direct to production)
The following illustration represents the ideal hotfix workflow, where changes are committed directly to the Production environment.
Important Git branch rules
Once Vortex Staging is linked to your Git repository:- Active branches are programmatically generated.
- Branch names must NOT be renamed or deleted.
Staging Git branch workflow
As part of the theme deployment workflow, consider a Vortex Staging setup with the following mapped environments:- Production
- Staging
- UAT
The following illustration highlights how the components work together: the Vortex Staging repository in your GitHub Organisation, webhook-enabled environments (Production, Staging, UAT), storefront channels per environment, GitHub users (developer, designer), and user-specific Git branches.
Code deployment screen
Navigate to History and Rollback, Code Deployment. This section displays the list of Git commits from your connected GitHub repository that are available for deployment in Vortex Staging. The deployment status states (Awaiting Approval, Approved and Deployed, Errors or Conflicts, Rejected) are documented in Theme deployments.GitHub FAQs
Q1. I see auto-generated branches like Productione347c1. Should I keep them?
Yes. These branches are required for commit tracking and integration. Do not rename or delete these branches. Branches are created per environment, per channel, and per team member.
Q2. What is the purpose of developer branches?
Developer branches allow frequent commits without impacting environment branches, isolated development per team member, and cleaner merges once work is complete.Q3. Why use developer branches instead of feature branches?
Developer branches allow multiple developers to work independently, prevent conflicts between developers, and enable easy merging into environment branches when ready.Q4. What is the role of the Main / Master branch?
The Main / Master branch acts as a buffer / default branch. It can remain unused after setup. Vortex Staging uses auto-generated environment branches instead.Q5. Does Vortex Staging export themes from Shopify to GitHub?
Yes. Once GitHub integration is connected and at least one team member is added, Vortex Staging automatically downloads the theme into the connected branch.Q6. Do GitHub commits appear as rollback options?
Yes. All tracked commits appear as rollback options in the deployment grid.Q7. How does version control work with multiple teams and CI/CD?
Commits appear in Code Deployment with incremental versions. Branches are created per environment, per channel, and per team member. Under Settings, Status Notifications, enable deployment notifications via Email, Microsoft Teams, or Slack.Q8. Why does preview launch take time to generate the preview URL?
The time depends on the size of the theme files. The process may take up to 5 minutes as it involves provisioning a temporary server and installing the theme.Q9. Why does deployment take time after approval?
After approval, deployment may take 15-20 minutes depending on the size of the theme files. This time is required to create the theme bundle and upload it to Shopify.Related pages
- Theme deployments, the deployment queue UI in detail
- Notifications, get pinged when a deploy needs approval
- Onboarding, the broader Vortex Staging setup walkthrough
- Migration history, the related migration audit log
- Nerve Centre Shopify cards, KPIs to verify a successful theme deploy