GitHub Repo Best Practices

Prerequisites

• Git version 2.34.0 or higher
• Git Bash (Windows users)

A. Authenticating with GitHub

Important: ✅ Use SSH when working locally. ❌ Do not use personal access tokens when working with repositories locally. Instead, use SSH keys.

When working with repositories on your local machine, use SSH to perform Git actions such as clone, push, and pull.

1. Open Git Bash

2. Check if the .ssh folder exists under the current account:

💡 The ~ symbol used in most of the commands below represents the home directory regardless of the OS, for example:

• On Linux: ~/ refers to /home/username/
• On Windows: ~/ refers to c:/users/username/

~/.ssh

• If it does not exist, create it before proceeding with the next steps:

mkdir -p ~/.ssh

3. Generate the SSH key (ideally with a strong passphrase):

ssh-keygen -t ed25519 -C "[email protected]"

4. Add the newly created SSH Public key to your GitHub account:

4.1 Copy the content of the newly generated SSH public key:

cat ~/.ssh/id_ed25519.pub

4.2 Go to the SSH and GPG keys section in GitHub:

GitHub Account → Settings → SSH and GPG keys

4.3 Create a new SSH key of type Signing Key

4.4 Create a new SSH key of type Authentication Key

• Once created, click on "Configure SSO" and click on "Authorize" for github-group-name.

5. Configure Git:

git config --global gpg.format ssh
git config --global user.name "<git-username>"
git config --global user.email "[email protected]"
git config --global user.signingkey ~/.ssh/id_ed25519.pub

💡 To have all commits signed by default, add the following to the git config settings:

git config --global commit.gpgsign true

6. Configure Allowed Signers File

6.1 Create the Allowed Signers File:

mkdir -p ~/.config/git
touch ~/.config/git/allowed_signers

6.2 Append your public key (id_ed25519.pub) to the allowed_signers file:

echo "$(git config user.email) $(cat ~/.ssh/id_ed25519.pub)" >> ~/.config/git/allowed_signers

6.3 (Optional) Verify the contents:

cat ~/.config/git/allowed_signers

Expected Output:

[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICz....

6.4 Configure Git to Use the Allowed Signers File:

git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers

6.5 Test Your Configuration:

git log --show-signature -1

7. Test SSH Connection:

ssh -T [email protected]

---

B. Create a New Branch

Important: Before creating a new branch, always sync the local repo with the remote one.

git checkout main
git pull

• Create the branch with a name corresponding to the Jira ticket number:

git checkout -b jira_ref_number

Example:

git checkout -b erm_123

---

C. Do a Commit

Categories:

• feat: → Adding a new feature.

• fix: → Fixing a bug.

• refactor: → Improving code without changing functionality (e.g., readability, optimization).

• chore: → Miscellaneous changes (docs, formatting, CI/CD, tests, cleanup, etc.).

• Each commit should be signed using the -S flag:

git commit -S

• For short commit messages:

git commit -S -m "<category>(<jira reference number>): <short summary>"

Example:

git commit -S -m "feat(ERM-123): Add a new dimensions table"

• For detailed commit messages (when omitting the -m flag git will automatically open the default Text editor where to specify both the commit subject line and message body):

git commit -S

Example commit message format:

feat(ERM-123): Add a new dimensions table

A new dimension table has been added for the stores data.
This table will keep only the necessary data columns loaded from the cleansed source store list table.

Pre-commit checks

✅ Pre-commit checks run automatically. ⚠️ If errors (e.g., redundant blank lines, trailing whitespaces, etc.) are found, they are auto-fixed. 🚨 If errors cannot be auto-fixed, they must be fixed manually before retrying the commit.

Push the commit to the remote repository:

git push origin jira_ref_number

Example:

git push origin erm_123

Commit Guidelines:

• Keep subject lines up to 50 characters (hard limit: 72).
• Use capitalized subject lines.
• Do not end subject lines with a period.

---

D. Pull Requests

1. Open a Pull Request (GitHub UI)

• Pull Request Title Format:

Pull Request - <category>(<jira reference number>): <short summary>

Example:

Pull Request - feat(ERM-123): Add a new dimensions table

2. Merge a Pull Request (GitHub UI or use Git CLI)

⚠️ Important: Pull requests can be merged only when they are approved by the corresponding reviewer(s).

• Merge Subject Line Format:

Merge pull request #PR_NUMBER from <jira ticket title>

Example:

Merge pull request #3 from new_dim_table

3. Merge a Pull Request (Git CLI or use GitHub UI)

Important: Before merging, sync the local repo with the remote one.

git checkout main
git pull

• Each merge should be signed:

git merge -S

• Fast-forward merge:

git merge jira_ref_number -S -m "Merge pull request #PRNUM from <jira reference number>" -m "<category>(<jira reference number>): <short summary>"

Example:

git merge erm_123 -S -m "Merge pull request #3 from <jira reference number>" -m "feat(ERM-123): Add a new dimensions table"

---

🔹 Following these best practices ensures better security, clarity, and efficiency when working with GitHub repositories! 🔹