GitHub Best Practices – Professional Workflows Used in Software Companies
In a professional software company, GitHub is more than a place to store source code. It is part of the engineering process used by developers, technical leads, architects, QA engineers, DevOps teams and security teams.
Imagine a team developing a banking application. Multiple developers work on customer onboarding, loan processing, payment integration and reporting. If everyone directly modifies the production branch, code conflicts, unstable deployments and accidental defects can become serious problems.
Professional teams avoid this by following consistent Git and GitHub practices. They use feature branches, pull requests, code reviews, automated checks, protected branches and controlled releases.
- How software companies organise GitHub repositories.
- Branching and commit message conventions.
- Professional pull request and code review practices.
- Branch protection and CI/CD quality checks.
- Security, release management and production workflows.
- How to implement a complete team workflow.
1. Why Do Professional GitHub Practices Matter?
Without agreed engineering practices, each developer may follow a different approach. One developer commits directly to the main branch, another creates long-running branches, and someone else merges code without testing.
This creates avoidable risks:
- Unreviewed code reaches production.
- Developers overwrite or conflict with each other's changes.
- Bug fixes become difficult to trace.
- Credentials or sensitive configuration may be committed accidentally.
- Releases become unpredictable.
- Teams struggle to understand why a change was introduced.
Professional GitHub practices create a repeatable process where every change is traceable, reviewed, tested and approved before it reaches an important branch.
2. Organise Repositories Properly
A repository should communicate what the project does, how to run it, how to contribute and where to find important technical information.
Recommended repository structure
loan-management-api/
│
├── src/
│ ├── Api/
│ ├── Application/
│ ├── Domain/
│ └── Infrastructure/
│
├── tests/
│ ├── UnitTests/
│ └── IntegrationTests/
│
├── docs/
├── .github/
│ ├── workflows/
│ ├── ISSUE_TEMPLATE/
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── CODEOWNERS
│
├── .gitignore
├── .editorconfig
├── README.md
├── CONTRIBUTING.md
└── LICENSE
This is an illustrative structure for a .NET API. The actual folder structure should reflect the architecture and needs of the project.
Important repository files
| File | Purpose |
|---|---|
README.md |
Project overview, setup and usage instructions. |
.gitignore |
Excludes generated files, local settings and other unwanted files. |
.editorconfig |
Maintains consistent formatting conventions. |
CONTRIBUTING.md |
Explains how contributors should work with the project. |
CODEOWNERS |
Defines code ownership and suggested reviewers. |
.github/workflows/ |
Contains GitHub Actions workflow definitions. |
LICENSE |
Defines how the project may legally be used and distributed. |
3. Follow a Consistent Branching Strategy
Branches allow developers to work independently without disturbing the stable codebase. A team should agree on a branching strategy and use it consistently.
A practical feature-branch workflow
Many teams use a simple model with a protected main branch and short-lived feature, bug-fix or hotfix branches.
A feature branch isolates work until the pull request is reviewed and merged.
Common branch naming conventions
feature/add-customer-search
feature/loan-eligibility-check
bugfix/fix-payment-timeout
hotfix/fix-production-login
release/2.4.0
chore/update-dependencies
Include a ticket or work-item identifier when the organisation uses one:
feature/LOAN-245-add-customer-search
bugfix/LOAN-319-fix-interest-calculation
Create and publish a feature branch
# Get the latest main branch
git switch main
git pull origin main
# Create a feature branch
git switch -c feature/LOAN-245-add-customer-search
# Verify the current branch
git branch --show-current
feature/LOAN-245-add-customer-search
4. Write Meaningful Commit Messages
A commit message should explain what changed and, where useful, why the change was necessary. Messages such as final changes, update code or fix issue provide very little information.
Recommended commit message format
<type>(<scope>): <short description>
[optional body]
[optional footer]
Examples:
feat(customer): add customer search endpoint
fix(payment): handle gateway timeout response
test(loan): add eligibility calculation tests
docs(api): update authentication instructions
refactor(repository): simplify customer query logic
| Type | Meaning |
|---|---|
feat |
Introduces a new feature. |
fix |
Fixes a defect. |
refactor |
Changes internal structure without changing intended behaviour. |
test |
Adds or updates tests. |
docs |
Updates documentation. |
chore |
Performs maintenance tasks. |
perf |
Improves performance. |
Commit changes in a focused manner
# Inspect changed files
git status
# Review the actual changes
git diff
# Stage only the intended file
git add src/Customer/CustomerService.cs
# Commit with a meaningful message
git commit -m "feat(customer): add customer search endpoint"
Prefer small, logical commits over one very large commit containing unrelated changes. This makes reviews, debugging and reverting changes easier.
5. Use Pull Requests for Every Important Change
A pull request (PR) is the formal mechanism for proposing changes from one branch into another. It gives team members a place to review code, discuss design decisions, inspect automated checks and approve the change.
What should a good pull request contain?
- Clear title: Describe the purpose of the change.
- Context: Explain the problem or requirement.
- Implementation: Summarise what was changed.
- Testing: Mention tests executed and relevant results.
- Impact: Identify API, database, configuration or deployment changes.
- Evidence: Include screenshots or sample requests when useful.
- Related work item: Link the relevant issue or ticket.
Example pull request description
## Summary
Added customer search functionality.
## Changes
- Added customer search API endpoint.
- Implemented filtering by name and customer ID.
- Added input validation.
- Added unit tests.
## Testing
- Customer service unit tests passed.
- API integration tests passed.
- Invalid search parameters tested.
## Impact
No database schema changes.
## Related issue
Closes #245
Recommended PR review checklist
- Does the implementation satisfy the requirement?
- Is the code readable and maintainable?
- Are edge cases and error conditions handled?
- Are unit and integration tests sufficient?
- Are security and access-control rules respected?
- Are database and API changes backward-compatible where required?
- Are logs, configuration and documentation appropriate?
6. Perform Effective Code Reviews
Code review is not just about finding syntax errors. It is an engineering quality practice that helps teams identify defects, improve maintainability and share technical knowledge.
Responsibilities of the author
- Submit a focused and understandable change.
- Provide sufficient context in the PR description.
- Run relevant tests before requesting review.
- Respond professionally to review feedback.
- Resolve conversations or explain why a suggestion is not applicable.
Responsibilities of the reviewer
- Understand the requirement before reviewing implementation details.
- Check correctness, readability, security and test coverage.
- Identify possible regressions and edge cases.
- Explain feedback with a clear reason.
- Distinguish blocking defects from optional improvements.
Example review feedback
Less useful: "This code is wrong. Change it."
More useful: "This query may return duplicate customers when multiple accounts match the search criteria. Could we verify whether the result should be distinct before returning the response?"
Use GitHub review states appropriately:
- Comment: Provides feedback without approving or requesting changes.
- Approve: Indicates that the reviewer approves the proposed changes.
- Request changes: Indicates that important changes are required before approval.
Approval requirements should be defined by the repository's branch protection or ruleset configuration. An approval alone should not be treated as proof that every production requirement has been satisfied.
7. Protect Important Branches
Branches such as main should not be open to uncontrolled changes. GitHub repository rules can require reviews and automated checks before changes are merged.
Recommended protection requirements
- Require pull requests before merging.
- Require approval from designated reviewers.
- Require relevant status checks to pass.
- Require conversation resolution where appropriate.
- Restrict direct pushes to authorised users or automation.
- Require signed commits when the organisation's policy demands them.
- Use rulesets or branch protection settings consistently across repositories.
The protected branch acts as a quality gate. The exact requirements depend on the team's repository policy.
main automatically protects it. Configure and verify the repository's actual rules.8. Automate Quality Checks with GitHub Actions
Manual testing alone is not enough for a busy engineering team. Continuous Integration (CI) helps run repeatable checks whenever developers push changes or open pull requests.
For a .NET application, a CI workflow may restore dependencies, build the solution and execute unit tests.
Example GitHub Actions workflow
Create the following file in the repository:
.github/workflows/dotnet-ci.yml
name: .NET CI
on:
pull_request:
branches:
- main
push:
branches:
- main
permissions:
contents: read
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: '8.0.x'
- name: Restore dependencies
run: dotnet restore
- name: Build solution
run: dotnet build --no-restore --configuration Release
- name: Run tests
run: dotnet test --no-build --configuration Release
This example assumes the repository contains a compatible .NET 8 solution and test projects. Adapt the runtime version and commands to the actual application.
What happens when a pull request is opened?
- GitHub detects the pull request event.
- The workflow starts on a GitHub-hosted runner.
- The source code is checked out.
- Dependencies are restored.
- The application is compiled.
- Automated tests are executed.
- The workflow reports success or failure.
Configure the relevant workflow checks as required status checks in the repository's branch protection or ruleset settings. A workflow existing in the repository does not automatically make it a mandatory merge requirement.
9. Follow Secure Repository Practices
Source code repositories often contain sensitive application information. A single accidental commit can expose credentials, tokens or private configuration.
Never commit secrets
Avoid committing:
- Database passwords and connection strings containing credentials.
- Cloud access keys and private keys.
- API tokens and authentication secrets.
- Production environment files containing sensitive values.
- Certificates and signing keys.
Use environment variables and secret stores
For GitHub Actions, store deployment credentials in GitHub Actions secrets or an approved external secret-management solution. Reference secrets from the workflow instead of writing them directly into YAML files.
steps:
- name: Deploy application
run: ./deploy.sh
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
For production deployments, consider environment-level protection rules, restricted deployment permissions, short-lived credentials through OIDC where supported, and approval requirements for sensitive environments.
Apply least-privilege permissions
- Give team members only the repository permissions they need.
- Use organisation teams to manage access consistently.
- Review external collaborators periodically.
- Limit workflow token permissions to the required scope.
- Enable appropriate secret scanning and push protection features when available.
- Review dependency vulnerabilities and security alerts.
10. Use CODEOWNERS and Repository Templates
In larger teams, not every developer should be expected to review every part of the application. CODEOWNERS helps identify the teams or individuals responsible for specific areas of a repository.
Example CODEOWNERS file
# Default owners
* @company/platform-team
# API implementation
/src/Api/ @company/api-team
# Database and persistence
/src/Infrastructure/ @company/data-team
# CI/CD configuration
/.github/workflows/ @company/devops-team
GitHub can use this file to suggest or request reviews from the configured owners, depending on repository settings and permissions. The file alone does not guarantee that approval is mandatory; configure the appropriate review rules separately.
Use templates for consistency
Issue and pull request templates help developers provide the information reviewers need. Repository templates can also standardise setup files, labels and contribution guidance across related projects.
11. Manage Releases and Versioning Carefully
Professional teams need to know exactly which version of the application is being deployed. Git tags and GitHub Releases help identify stable points in repository history.
Use semantic versioning where appropriate
A common version format is:
MAJOR.MINOR.PATCH
2.4.1
- MAJOR: Introduces incompatible changes.
- MINOR: Adds functionality in a backward-compatible manner.
- PATCH: Provides backward-compatible fixes.
Create a release tag
# Create an annotated tag
git tag -a v2.4.0 -m "Release version 2.4.0"
# Push the tag
git push origin v2.4.0
# View tags
git tag
After pushing the tag, create a GitHub Release using the tag. Include release notes describing new features, bug fixes, breaking changes and upgrade instructions.
12. Keep the Development Workflow Clean
Small daily habits prevent many avoidable Git problems.
Useful commands before pushing changes
# Check current branch
git branch --show-current
# Check working tree
git status
# Review unstaged changes
git diff
# Review staged changes
git diff --staged
# Fetch latest remote information
git fetch origin
# Update current branch from remote main
git pull --rebase origin main
# Push current branch
git push -u origin HEAD
Use git pull --rebase only when it matches the team's agreed history policy. Avoid rebasing commits that have already been shared with others unless the team explicitly coordinates that operation.
Additional habits worth following
- Keep branches short-lived and synchronise regularly.
- Review staged changes before committing.
- Do not commit generated build output unless the project requires it.
- Keep dependencies updated through a controlled process.
- Write tests for important business rules and regression scenarios.
- Delete merged feature branches when they are no longer needed.
- Document breaking changes and operational requirements.
13. Real-World Example: A Banking Application Team
Consider a team working on a loan management platform. A business requirement asks for a new loan eligibility API.
The product owner creates issue or ticket LOAN-245 describing the required API behaviour and acceptance criteria.
The developer creates feature/LOAN-245-loan-eligibility from the latest main branch.
The developer implements the API, adds validation and writes unit tests for eligibility rules and boundary conditions.
Changes are committed with meaningful messages and pushed to the remote feature branch.
The developer opens a PR against main, explains the implementation and links the work item.
Code owners review the changes. GitHub Actions runs the build and tests. The author addresses review comments and updates the branch.
After the configured approval and checks are satisfied, the change is merged. The release process builds and deploys the approved version through the organisation's deployment pipeline.
This workflow gives the team traceability from business requirement to source-code change, review, validation and release.
14. Common GitHub Mistakes to Avoid
| Common mistake | Better practice |
|---|---|
| Committing directly to main | Use pull requests and protected branches. |
| Using unclear commit messages | Follow an agreed commit convention. |
| Creating very large PRs | Keep changes focused and reviewable. |
| Skipping automated tests | Run CI checks before merging. |
| Committing credentials | Use secret stores and rotate exposed credentials. |
| Keeping branches open for months | Integrate changes frequently. |
| Approving without reviewing | Review functionality, tests and risks. |
| Deploying without release records | Use versioned releases and deployment tracking. |
| Giving everyone admin access | Apply least-privilege permissions. |
15. Hands-On Practice
Try implementing a professional workflow using a sample repository.
Exercise 1 – Branching and commits
- Create a repository named
employee-management-api. - Create a feature branch named
feature/add-employee-search. - Add a simple employee search endpoint or sample implementation.
- Commit the change using a meaningful commit message.
Exercise 2 – Pull request and review
- Push the feature branch to GitHub.
- Open a pull request against
main. - Add a meaningful description and testing details.
- Ask another contributor to review the changes.
- Address feedback and merge the PR.
Exercise 3 – Automate quality checks
- Create a GitHub Actions workflow.
- Configure it to run on pull requests targeting
main. - Run build and test commands.
- Configure the workflow as a required status check.
- Verify that a failed check prevents merging when the branch rules are configured accordingly.
16. Interview Questions and Answers
1. Why should developers use feature branches?
Feature branches isolate development work from the stable branch. They allow multiple developers to work independently and submit changes through pull requests without directly modifying the main codebase.
2. What is the purpose of a pull request?
A pull request proposes changes from one branch into another. It provides a place for code review, discussion, automated checks and approval before merging.
3. How do branch protection rules improve code quality?
They enforce repository policies such as requiring pull requests, approvals and successful status checks. This reduces uncontrolled changes to important branches.
4. What is the difference between Continuous Integration and Continuous Deployment?
Continuous Integration focuses on frequently integrating code and automatically validating changes through builds and tests. Continuous Deployment automatically releases qualifying changes to a target environment. Some organisations instead use Continuous Delivery, where the software is kept deployable but production release requires an approval or manual decision.
5. What should a developer do if an API key is accidentally committed?
Immediately revoke or rotate the exposed key, investigate possible use, notify the appropriate security team and follow the incident response process. Removing the value from the latest commit does not remove it from repository history or guarantee that it was not accessed.
17. Conclusion
Professional GitHub usage is about building a reliable engineering process, not simply learning Git commands. Repository organisation, short-lived branches, meaningful commits, pull requests, code reviews, branch protection, automated testing and secure release management work together to improve software quality.
When teams follow these practices consistently, changes become easier to understand, review, test, release and maintain. These are the habits expected in well-managed software engineering teams.
Keep changes focused, review every important contribution, automate quality checks, protect critical branches, secure credentials and make every release traceable.
Upgradix by Shrash Studio
Learn Technology. Build Your Future.
Quality Technology Education. Completely Free.