Real-World GitHub Project – Build a Complete Team Development Workflow
Imagine a team of five developers building an e-commerce application. One developer works on product search, another handles payments, and another fixes order-processing issues. All of them need to change the same codebase without overwriting each other's work.
This is where a proper GitHub team workflow becomes important. In this project, we will build a practical workflow that takes a change from a developer's machine through a feature branch, pull request, automated checks, code review, and finally into the main branch.
- A shared GitHub repository for an e-commerce application.
- A branch strategy for parallel development.
- A pull request and code-review process.
- Automated CI checks using GitHub Actions.
- Protected main branch and a controlled release process.
1. Understand the Team Scenario
Our sample project is called ShopSphere. It contains product, order, payment, and customer modules. The team has the following responsibilities:
| Role | Responsibility | Example work |
|---|---|---|
| Team Lead | Architecture and approvals | Review design and critical changes |
| Developer A | Product module | Add product search |
| Developer B | Order module | Improve order validation |
| Developer C | Payment module | Handle payment failures |
| QA Engineer | Quality verification | Validate test scenarios |
Without a workflow, developers may directly push unfinished code to the main branch. A faulty change can affect everyone, and it becomes difficult to identify who changed what.
main. They create branches and submit pull requests for review.2. Plan the Repository Structure
Create a repository named shopsphere on GitHub. For this demonstration, assume the repository URL is your own repository URL.
A simple project structure could look like this:
shopsphere/
├── src/
│ ├── Products/
│ ├── Orders/
│ └── Payments/
├── tests/
│ ├── Products.Tests/
│ └── Orders.Tests/
├── docs/
├── .github/
│ ├── workflows/
│ │ └── ci.yml
│ └── pull_request_template.md
├── .gitignore
└── README.md
The src folder contains application code, tests contains automated tests, and .github stores GitHub-specific workflow configuration.
3. Choose a Branching Strategy
For a small or medium-sized team that releases regularly, a simple main-and-feature-branch strategy is often sufficient.
| Branch | Purpose | Example |
|---|---|---|
main |
Stable, releasable code | Production-ready changes |
feature/* |
New functionality | feature/product-search |
bugfix/* |
Non-urgent defect fixes | bugfix/order-validation |
hotfix/* |
Urgent production fixes | hotfix/payment-timeout |
Each developer creates a separate branch from the latest main. This allows multiple tasks to progress independently.
ShopSphere team development workflow
The workflow follows a controlled sequence. A change reaches the stable branch only after automated checks and the required human review.
4. Create the First Feature Branch
Developer A is assigned the product-search feature. First, clone the repository and create a new branch.
Example 1: Clone and create a feature branch
# Clone the repository
git clone https://github.com/YOUR-USERNAME/shopsphere.git
# Move into the project
cd shopsphere
# Get the latest main branch
git switch main
git pull origin main
# Create and switch to a feature branch
git switch -c feature/product-search
git switch -c creates a branch and switches to it. The developer can now make changes without modifying the local main branch.
Check the current branch
git branch --show-current
feature/product-search
5. Commit and Push the Changes
After implementing the feature and running the relevant tests locally, the developer stages and commits the changes.
Example 2: Save the feature work
# Review changed files
git status
# Stage the intended files
git add src/Products tests/Products.Tests
# Create a meaningful commit
git commit -m "feat(products): add product search"
# Push the branch to GitHub
git push -u origin feature/product-search
A commit is a saved snapshot in Git history. The commit message should explain the purpose of the change, not simply say "updated code".
fix(orders): validate duplicate order items. A consistent format such as type(scope): description makes the history easier to understand.6. Open a Pull Request
Once the branch is pushed, open the GitHub repository in your browser. GitHub will usually show an option to compare the recently pushed branch and create a pull request.
- Select Compare & pull request.
- Set the base branch to
main. - Set the compare branch to
feature/product-search. - Add a meaningful title and description.
- Assign reviewers and link the related issue if one exists.
- Create the pull request.
A pull request (PR) is a proposal to merge changes from one branch into another. It gives the team a place to inspect code, discuss changes, and verify automated checks before merging.
Example: Pull request description template
## Summary
Added product search functionality.
## Changes
- Added product search logic.
- Added validation for empty search terms.
- Added unit tests for search scenarios.
## Testing
- Product search unit tests passed.
- Empty search input verified.
## Checklist
- [x] Code follows project conventions
- [x] Tests added or updated
- [x] No secrets committed
- [ ] Reviewer approval received
7. Automate Checks with GitHub Actions
Manual testing alone is not enough for a team repository. A developer may accidentally introduce a compilation error or break an existing test. Continuous Integration (CI) automatically runs configured checks when code is pushed or a pull request is opened.
For this example, assume ShopSphere contains a .NET solution named ShopSphere.sln. Create this file:
.github/workflows/ci.yml
name: ShopSphere CI
on:
push:
branches:
- main
pull_request:
branches:
- main
permissions:
contents: read
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Install .NET SDK
uses: actions/setup-dotnet@v4
with:
dotnet-version: '8.0.x'
- name: Restore dependencies
run: dotnet restore ShopSphere.sln
- name: Build solution
run: dotnet build ShopSphere.sln --configuration Release --no-restore
- name: Run tests
run: dotnet test ShopSphere.sln --configuration Release --no-build
This workflow runs when a commit is pushed to main or when a pull request targets main. It checks out the code, installs the .NET SDK, restores dependencies, builds the solution, and runs tests.
8. Review the Code as a Team
Automated checks help catch technical problems, but they do not replace code review. A reviewer should understand the change and check whether it is safe, maintainable, and consistent with the application design.
What should reviewers verify?
- Correctness: Does the implementation solve the actual requirement?
- Readability: Can another developer understand the code?
- Testing: Are important success and failure scenarios covered?
- Security: Are secrets, credentials, and sensitive data protected?
- Compatibility: Could the change break an existing API or dependent module?
- Performance: Does it introduce unnecessary database calls or expensive operations?
If changes are requested, Developer A updates the same feature branch, commits the corrections, and pushes again. The existing pull request receives the new commits automatically.
Example: Push review corrections
git add src/Products
git commit -m "test(products): cover empty search input"
git push
9. Protect the Main Branch
Branch protection rules help prevent unreviewed or failing code from being merged into the stable branch.
In the GitHub repository, open Settings → Rules → Rulesets and create a branch ruleset targeting main. Depending on the repository configuration and GitHub plan, available controls can vary.
For this workflow, configure the following protections where available:
- Require a pull request before merging.
- Require at least one approval from a reviewer.
- Require the CI status check to pass.
- Require approval of the latest reviewable push, if appropriate.
- Block force pushes to the protected branch.
- Restrict deletion of the protected branch.
10. Merge and Release the Feature
After the required checks pass and the pull request receives approval, an authorised team member can merge it into main.
Choose a merge strategy that matches the team's history policy:
- Squash and merge: Combines the pull request's commits into one commit on the base branch.
- Merge commit: Preserves the branch history and creates a merge commit.
- Rebase and merge: Replays commits onto the base branch without creating a merge commit.
For this example, the team uses squash merging to keep the main branch history concise. After merging, the team verifies the resulting build and follows its deployment process.
Example: Update the local main branch
git switch main
git pull origin main
For a versioned release, the team can create a Git tag after the release has been approved and deployed according to its release procedure.
git tag -a v1.2.0 -m "ShopSphere release 1.2.0"
git push origin v1.2.0
A tag identifies a specific point in Git history. Create release tags only according to the team's release policy and ensure the tagged commit is the intended release commit.
11. Handle an Urgent Production Fix
Suppose the payment module starts failing after a production release. The team needs to fix the issue without mixing it with unfinished feature work.
# Start from the current stable branch
git switch main
git pull origin main
# Create a focused hotfix branch
git switch -c hotfix/payment-timeout
# Implement and test the fix, then commit
git add src/Payments
git commit -m "fix(payments): handle gateway timeout"
# Push and open a pull request
git push -u origin hotfix/payment-timeout
The hotfix still follows the team's required review and CI checks. After approval, merge it into main, deploy through the approved release process, and verify the production issue is resolved.
12. Understand the Complete Pull Request Lifecycle
| Stage | Owner | Expected result |
|---|---|---|
| Task creation | Team Lead / Product Owner | Clear requirement and acceptance criteria |
| Branch creation | Developer | Isolated working branch |
| Implementation | Developer | Code and relevant tests |
| Pull request | Developer | Reviewable change proposal |
| CI checks | GitHub Actions | Build and test status |
| Code review | Reviewer | Approval or requested changes |
| Merge | Authorised maintainer | Change integrated into main |
| Release | Release owner / CI-CD | Approved version deployed |
| Verification | Development / QA / Operations | Application health confirmed |
13. Common Team Workflow Mistakes
- Direct pushes to main: Use pull requests and branch protection to control changes.
- Large pull requests: Split unrelated work into smaller, reviewable changes.
- Unclear commit messages: Describe the intent and scope of each commit.
- No automated tests: Add relevant tests and make required CI checks part of the merge process.
- Ignoring review comments: Resolve discussions and explain any intentionally retained design decisions.
- Committing secrets: Never commit API keys, passwords, tokens, or private certificates. Use an approved secrets-management solution.
- Stale feature branches: Regularly bring changes from the base branch into long-running feature branches and resolve conflicts carefully.
- Uncontrolled releases: Define release ownership, versioning, deployment approvals, and rollback procedures.
14. Hands-On Team Exercise
Create a repository and practise the complete process with two contributors.
- Create a repository named
shopsphere. - Invite a second contributor with the appropriate repository access.
- Create
feature/product-searchand add a sample feature. - Ask the second contributor to review the pull request.
- Add a GitHub Actions workflow that builds and tests your sample project.
- Configure branch protection for
main. - Merge the approved pull request and create a release tag.
Expected result: Both contributors can work independently, review changes, and integrate code into the protected main branch through a repeatable process.
15. Interview Questions
A feature branch isolates a developer's work from the stable branch. It allows development and testing to happen independently before the change is proposed for integration.
Git is a distributed version control system used to track source-code changes. GitHub Actions is an automation platform that can run workflows such as builds, tests, and deployments based on repository events.
Branch protection can require reviews and successful status checks before merging. It reduces the risk of accidentally integrating unreviewed or failing changes.
Squash merge is useful when the team wants one consolidated commit per pull request. A merge commit is useful when preserving the individual branch commits and merge history is important. The choice depends on the team's history and traceability policy.
Use protected branches, mandatory peer review, required CI checks, automated security scanning, controlled secrets, environment-specific deployment approvals, release traceability, monitoring, and a tested rollback strategy. Apply stricter controls to high-risk changes and keep the workflow auditable.
16. Conclusion
A successful GitHub workflow is more than pushing code to a remote repository. It defines how a team plans work, isolates changes, reviews implementations, validates quality, protects stable code, and releases software.
By following this ShopSphere example, you have seen how branches, commits, pull requests, GitHub Actions, code reviews, branch protection, and releases work together. These practices create a repeatable development process that can scale as the team and application grow.
Next step: Apply this workflow to a small project with two contributors. Once the process is comfortable, extend it with security scanning, deployment environments, release automation, and monitoring.