Working with Branches

​

Overview

Stardeck projects are built around Git repositories hosted on GitHub. Every Stardeck project is connected to a GitHub repository, and all development happens through Git branches. This Git-first approach gives you powerful version control, collaboration features, and the ability to work with multiple versions of your project simultaneously. When you create a Stardeck project, you’re essentially creating a deployment pipeline that connects to specific branches in your GitHub repository. You can then choose which branches to publish and deploy live.

​

Why Branches Matter in Stardeck

• Isolated Development - Each branch represents a separate environment for development and testing
• Manual Publishing - You control which branches to publish and deploy live
• Collaboration - Team members can work on different features simultaneously
• Safe Experimentation - Test new features without affecting your main deployment
• Version Control - Full Git history and the ability to roll back changes

​

Key Concepts

​

GitHub Integration

All Stardeck projects are connected to GitHub repositories. Stardeck:

• Connects to your GitHub branches for development
• Provides tools to manage which branches to track
• Allows you to manually publish branches when ready
• Integrates with GitHub’s merge and pull request workflows

​

Default Branch

Every project has a default branch (usually main or master) that serves as:

• The primary deployment for your project
• The main production version of your application
• The target for most merge operations
• A protected branch that cannot be accidentally deleted

​

Branch Tracking

Not all GitHub branches are available in Stardeck by default. You control which branches Stardeck should:

• Track - Make available for development and publishing
• Manage - Include in your Stardeck dashboard and workflows
• Publish - When you’re ready to deploy them live

​

Getting Started with Branches

​

Viewing Your Branches

1. Navigate to your project in the Stardeck dashboard
2. Click the branch selector in the sidebar or top navigation
3. View all tracked branches with their current status and deployment URLs

Each branch shows:

• Branch name and latest commit information
• Publishing status (published, unpublished)
• Direct link to live deployment (if published)
• Settings and management options

​

Creating New Branches

You can create new branches directly from Stardeck:

1. Open the branch selector in your project
2. Click “New” → “Create new branch”
3. Enter a branch name following your team’s conventions
4. Choose a base branch (defaults to current branch)
5. Click “Create” - Stardeck will create the branch on GitHub and start tracking it

​

Tracking Existing GitHub Branches

If you have existing branches on GitHub that aren’t being tracked:

1. Open the branch selector
2. Click “New” → “Track existing branch”
3. Search and select the GitHub branch you want to track
4. Click the branch name to start tracking it in Stardeck

​

Branch Management

​

Branch Settings

Each branch has its own settings accessible through the gear icon: Branch Information:

• Branch name and latest commit SHA
• Whether it’s the default branch
• Connection status with GitHub

Actions:

• View on GitHub - Opens the branch on GitHub in a new tab
• Stop Tracking - Removes the branch from Stardeck (GitHub branch remains)

​

Switching Between Branches

1. Click the branch selector in your project
2. Select any tracked branch to switch to it
3. Work with that branch’s deployment and development environment

Each branch maintains its own:

• Development environment and settings
• Publishing status and deployment options
• Build history and logs (when published)

​

Branch Status Indicators

• 🟢 Published - Branch is published and accessible via live URL
• 🟡 Building - Branch is being built for publication
• 🔴 Failed - Publication failed (check logs for details)
• ⚫ Unpublished - Branch is tracked but not published

​

Publishing Branches

To make a branch accessible via a live URL, you need to publish it:

1. Switch to the branch you want to publish
2. Go to Project Settings → Deployment tab
3. Click “Publish” to deploy the branch live
4. Access your published branch at the generated URL

​

Merging Branches

Stardeck provides powerful tools for merging branches while maintaining your Git history:

​

Checking Merge Status

Before merging, Stardeck automatically checks:

• Merge conflicts - Whether branches can be merged cleanly
• Branch status - How many commits ahead/behind
• Commit preview - Exact changes that will be merged

​

Viewing Commits to be Merged

When a branch is ready to merge, you’ll see:

• Total commit count - Number of commits to be merged
• Commit details - Message, author, date, and SHA for each commit
• Change summary - What will be included in the merge

​

Performing Merges

1. Open branch settings (gear icon next to any branch)
2. Select your target branch (usually the default branch)
3. Review the merge status and commit list
4. Click “Rebase & Merge” when ready

​

Merge Conflict Resolution

If conflicts exist:

• Stardeck will clearly indicate which files have conflicts
• You’ll need to resolve conflicts on GitHub or locally
• Push the resolved changes before attempting to merge again

​

Advanced Features

​

GitHub Integration

View on GitHub:

• Click the “View on GitHub” button in branch settings
• Opens the specific branch on GitHub for code review
• Access GitHub’s full collaboration tools

Automatic Sync:

• Stardeck stays in sync with your GitHub repository
• New commits trigger automatic deployments
• Branch deletions on GitHub are reflected in Stardeck

​

Branch Protection

Default Branch Safety:

• Cannot accidentally stop tracking the default branch
• Protected from deletion through Stardeck interface
• Maintains your primary deployment stability

Confirmation Dialogs:

• All destructive actions require confirmation
• Clear warnings about what will happen
• Safe guardrails prevent accidental data loss

​

Stopping Branch Tracking

When you no longer need a branch in Stardeck:

1. Open branch settings for the branch you want to stop tracking
2. Click “Stop Tracking” (only available for non-default branches)
3. Confirm the action in the dialog

​

Best Practices

​

Branch Naming

• Use descriptive names: feature/user-authentication, fix/login-bug
• Follow your team’s conventions consistently
• Keep names short but meaningful

​

When to Create Branches

• New features - Each feature gets its own branch
• Bug fixes - Isolate fixes from ongoing development
• Experiments - Test ideas without affecting main code
• Collaboration - Multiple developers can work simultaneously

​

Merge Strategy

• Regular merging - Don’t let branches get too far behind
• Small commits - Easier to review and merge
• Test before merging - Use branch deployments to verify changes
• Clean history - Rebase merging keeps Git history readable

​

Team Collaboration

• Use GitHub pull requests for code review before merging
• Communicate about which branches are active
• Document branch purposes and current status
• Clean up old branches regularly

---

Ready to start working with branches? Create your first feature branch and experience the power of Git-based development with Stardeck.