A curated list of GitHub Do’s and Don’ts

Here are some pointers that can help you define GitHub usage guidelines.

GitHub Do’s

It is recommended to create a new GitHub repository for each new project.

To ensure proper code management, a CODEOWNERS file should be included in the repository to indicate the list of individuals/GitHub teams responsible for approving the code changes. Additionally, a README.md file should be added to provide information about the repository and its code.

A .gitignore file should also be included to prevent unwanted files from being committed.

Regularly committing and pushing changes to the remote branch will prevent loss of work and ensure that the branch name is reserved.

A consistent branching strategy should be used, with new bugs or features branching off the master branch.

Before creating a pull request, it is essential to review thoroughly, lint your code and perform tests to ensure it is error-free and does not contain any unnecessary code.

Make use of PR templates to endure the contributor submits all the necessary information for PR review.

When creating pull requests, it is important to include detailed commit messages and mention any relevant Ticket IDs or information about testing or proof of concepts. This will help reviewers understand the changes and the reliability of the code.

It is always necessary to create a pull request when merging changes from one branch to another, and the master branch should be protected to prevent direct editing. Pull request standards should be followed to merge code even in repositories without protection.

During the PR review process, when changes to the code are requested, do not delete the branch, instead, ensure the new changes are made in the same branch and aligned with the original pull request so that the history is visible to future reviewers.

Having multiple people review a pull request is recommended, although it is not required.

For large projects, using git-submodule can be beneficial. Keep your branches up to date with development branches and consult with peers to ensure consistency in your project.

Be cautious when merging code on repositories integrated with automation, as it can automatically alter related resources. Ensure you understand the potential impacts of your code commits.

After each release, it is best practice to merge changes from the release branch to the master.

Regularly maintain your repositories by deleting branches that are no longer needed after merging a feature or bug fix.

Consider using Git Hooks for automation where appropriate.

Access to repositories is controlled using GitHub teams, regularly check that only the intended teams and users have access.

After creating a GitHub user ID, enabling multi-factor authentication (MFA) from the settings is crucial.

GitHub Don’ts

Do not share your GitHub credentials with new team members. They should only have access to the codebase after they have secured their credentials through the established process.

The organization should implement the policy of protecting the master branch in GitHub. Even if you encounter an unprotected repository, do not commit directly to the master/main branch. Instead, please take action to have it protected as soon as possible.

Do not delay progress by regularly not pushing changes made on local branches to remote branches.

Avoid working on outdated master branches. Always use the most recent version by taking a fresh pull.

Never include sensitive information, such as application secrets or proprietary data, in public repositories. Implement secret scanning in PR checks via GitHub actions. e.g. Trufflehog

Avoid committing large files in the repository, as GitHub has a default upload limit of 100MB. Consult with peers/higher to determine the best strategy for a specific project. Git LFS is another option to consider.

Avoid creating one pull request that addresses multiple issues or environments.

Before resetting a branch, make sure to commit or stash your changes to avoid losing them.

Be cautious when using force push, as it may override remote files and should only be used by those who are experienced with it.

Do not alter or delete the public history.

Avoid manually copying code from GitHub private repositories. Instead, use the Fork functionality to duplicate the code safely.

Avoid using public GitHub actions on repositories without going through defined procedures and approvals.