GitHub

Version control and code collaboration platform for software development.

Overview

GitHub is our primary platform for version control, code collaboration, and software development. It hosts our repositories, manages code reviews, tracks issues, and automates workflows through GitHub Actions.

What GitHub Provides

• Git repository hosting
• Code review and pull requests
• Issue tracking and project management
• CI/CD with GitHub Actions
• Documentation with GitHub Pages
• Team collaboration and permissions
• Code search and browsing

Getting Started

Account Access

1. Check your email for the GitHub organization invitation
2. Click Join [Organization Name]
3. Sign in or create a GitHub account
4. Accept the organization invitation

If you haven't received an invitation, contact TechOps to request access.

Sign In

1. Go to github.com
2. Click Sign in
3. Enter your credentials or use Okta SSO
4. Complete 2FA if enabled

First-Time Setup

1. Complete your profile:

   • Add a profile photo
   • Set your name and bio
   • Add your email addresses
   • Set your public visibility preferences

2. Configure SSH keys:

   • Generate SSH key: ssh-keygen -t ed25519 -C "your.email@company.com"
   • Add to GitHub: Settings → SSH and GPG keys → New SSH key
   • Test connection: ssh -T git@github.com

3. Configure Git locally:

   git config --global user.name "Your Name"
   git config --global user.email "your.email@company.com"
   git config --global init.defaultBranch main

4. Enable Two-Factor Authentication:

   • Go to Settings → Password and authentication
   • Click Enable two-factor authentication
   • Choose authenticator app or SMS
   • Save recovery codes securely

Basic Usage

Repositories

Clone a Repository:

# Using HTTPS
git clone https://github.com/organization/repo.git

# Using SSH (recommended)
git clone git@github.com:organization/repo.git

Create a New Repository:

1. Click + icon → New repository
2. Enter repository name
3. Choose public or private
4. Add README, .gitignore, and license if desired
5. Click Create repository

Fork a Repository:

1. Navigate to the repository
2. Click Fork button (top right)
3. Choose your account or organization
4. Clone your fork locally

Branches

Create a Branch:

# Create and switch to new branch
git checkout -b feature/new-feature

# Push to GitHub
git push -u origin feature/new-feature

Switch Branches:

git checkout main
git checkout feature/new-feature

List Branches:

# Local branches
git branch

# All branches (local and remote)
git branch -a

Commits

Make a Commit:

# Stage changes
git add .
# or stage specific files
git add file1.txt file2.txt

# Commit with message
git commit -m "Add new feature"

# Push to GitHub
git push

Good Commit Messages:

• Start with a verb: "Add", "Fix", "Update", "Remove"
• Be concise but descriptive
• Reference issue numbers: "Fix #123: Resolve login bug"

Pull Requests

Create a Pull Request:

1. Push your branch to GitHub
2. Navigate to the repository
3. Click Pull requests → New pull request
4. Choose base branch (usually main) and compare branch (your feature branch)
5. Fill in title and description
6. Add reviewers and labels
7. Click Create pull request

Review a Pull Request:

1. Go to Pull requests tab
2. Click on the PR to review
3. Review the Files changed tab
4. Add comments on specific lines
5. Submit review (Approve, Request changes, or Comment)

Merge a Pull Request:

1. Ensure all checks pass
2. Get required approvals
3. Click Merge pull request
4. Choose merge type:
   • Create a merge commit - Keeps all commits
   • Squash and merge - Combines into one commit
   • Rebase and merge - Adds commits linearly
5. Confirm merge
6. Delete branch if done

Issues

Create an Issue:

1. Go to Issues tab
2. Click New issue
3. Add a descriptive title
4. Provide detailed description
5. Add labels, assignees, and milestones
6. Click Submit new issue

Reference Issues:

• In commits: Fix #42: Resolve login error
• In PRs: Closes #42 (will auto-close when merged)
• In comments: Related to #42

Features

GitHub Actions

Automate workflows with CI/CD:

1. Create .github/workflows/ci.yml in your repository
2. Define triggers (push, pull request, schedule)
3. Set up jobs and steps
4. Use actions from the marketplace
5. View workflow runs in the Actions tab

Example Workflow:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

Code Review

Review Best Practices:

• Review promptly (within 24 hours)
• Be constructive and respectful
• Focus on code, not the person
• Ask questions if unclear
• Suggest improvements
• Approve when ready

Projects

Organize work with GitHub Projects:

1. Go to Projects tab
2. Create a new project
3. Choose view (Board, Table, Roadmap)
4. Add issues and pull requests
5. Organize with columns/fields
6. Track progress

GitHub Pages

Host documentation or websites:

1. Go to Settings → Pages
2. Choose source (branch or GitHub Actions)
3. Select folder (root or /docs)
4. Save and wait for deployment
5. Access at https://username.github.io/repository

Common Issues

Permission Denied (SSH)

Problem: Permission denied (publickey) when pushing/pulling.

Solution:

1. Check SSH key is added to GitHub: ssh -T git@github.com
2. Verify SSH agent is running: eval "$(ssh-agent -s)"
3. Add key to agent: ssh-add ~/.ssh/id_ed25519
4. Ensure key is added in GitHub settings
5. Try HTTPS if SSH continues to fail

Authentication Failed (HTTPS)

Problem: Authentication fails when pushing via HTTPS.

Solution:

1. GitHub removed password authentication
2. Use a Personal Access Token (PAT) instead:
   • Settings → Developer settings → Personal access tokens
   • Generate new token (classic)
   • Select appropriate scopes
   • Use token as password when prompted
3. Or switch to SSH authentication

Merge Conflicts

Problem: Can't merge due to conflicts.

Solution:

1. Pull the latest changes: git pull origin main
2. Git will mark conflicts in files
3. Open conflicted files and resolve manually
4. Remove conflict markers (<<<<<<<, =======, >>>>>>>)
5. Stage resolved files: git add .
6. Complete merge: git commit
7. Push changes: git push

Accidentally Committed to Wrong Branch

Problem: Made commits on main instead of feature branch.

Solution:

# Create new branch with current changes
git checkout -b feature/correct-branch

# Switch back to main
git checkout main

# Reset main to remote state
git reset --hard origin/main

# Switch to feature branch and push
git checkout feature/correct-branch
git push -u origin feature/correct-branch

Large File Error

Problem: "file exceeds GitHub's file size limit" error.

Solution:

1. Remove large file from commit history:

   git rm --cached large-file.zip
   git commit --amend -C HEAD

2. Add to .gitignore
3. Use Git LFS for large files:

   git lfs install
   git lfs track "*.zip"
   git add .gitattributes

4. Contact TechOps if you need LFS enabled

Best Practices

Repository Management

1. Use meaningful names - Clear, descriptive repository names
2. Write good READMEs - Explain purpose, setup, and usage
3. Add a .gitignore - Exclude unnecessary files
4. Include a LICENSE - Specify usage terms
5. Protect main branch - Require reviews before merging
6. Keep branches short-lived - Merge or delete regularly

Commit Practices

1. Commit often - Small, logical commits
2. Write good messages - Descriptive and consistent
3. Don't commit secrets - Use environment variables
4. Test before committing - Ensure code works
5. Review your changes - Use git diff before committing

Security

1. Enable 2FA - Required for organization access
2. Use SSH keys - More secure than passwords
3. Rotate access tokens - Regularly update PATs
4. Review third-party access - Check authorized applications
5. Never commit secrets - No API keys, passwords, or tokens
6. Use branch protection - Prevent force pushes to main
7. Enable Dependabot - Automatic security updates

Collaboration

1. Use descriptive PR titles - Clear and concise
2. Fill out PR templates - Provide context
3. Request specific reviewers - Get relevant expertise
4. Respond to feedback - Address all comments
5. Keep PRs focused - One feature or fix per PR
6. Link related issues - Maintain traceability

How-To Guides

Set Up SSH Keys

1. Generate SSH key:

   ssh-keygen -t ed25519 -C "your.email@company.com"
   # Press Enter to accept default location
   # Enter a passphrase (recommended)

2. Add key to SSH agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519

3. Copy public key:

   # macOS
   pbcopy < ~/.ssh/id_ed25519.pub
   
   # Linux
   cat ~/.ssh/id_ed25519.pub

4. Add to GitHub:

   • Go to Settings → SSH and GPG keys
   • Click New SSH key
   • Paste key and save

5. Test connection:

   ssh -T git@github.com

Create a Pull Request

1. Create and switch to feature branch:

   git checkout -b feature/add-login

2. Make changes and commit:

   git add .
   git commit -m "Add login functionality"

3. Push to GitHub:

   git push -u origin feature/add-login

4. Create PR on GitHub:

   • Click the notification link or go to repository
   • Click Compare & pull request
   • Fill in details
   • Add reviewers
   • Create pull request

5. Address review feedback:

   # Make requested changes
   git add .
   git commit -m "Address review feedback"
   git push

6. Merge when approved:

   • Click Merge pull request
   • Confirm merge
   • Delete branch

Resolve Merge Conflicts

1. Update your branch:

   git checkout main
   git pull origin main
   git checkout feature/your-branch
   git merge main

2. Identify conflicts:

   git status
   # Shows conflicted files

3. Open conflicted files and resolve:

   <<<<<<< HEAD
   Your changes
   =======
   Changes from main
   >>>>>>> main

   Remove markers and keep desired code

4. Complete merge:

   git add resolved-file.txt
   git commit -m "Resolve merge conflicts"
   git push

Revert a Commit

Undo last commit (not pushed):

git reset --soft HEAD~1  # Keep changes staged
# or
git reset --hard HEAD~1  # Discard changes

Revert a pushed commit:

# Creates new commit that undoes changes
git revert <commit-hash>
git push

Revert a merge:

git revert -m 1 <merge-commit-hash>
git push

Quick Reference

Common Git Commands

Command	Description
git clone <url>	Clone a repository
git status	Check repository status
git add <file>	Stage changes
git commit -m "msg"	Commit changes
git push	Push to remote
git pull	Pull from remote
git checkout <branch>	Switch branches
git checkout -b <branch>	Create and switch to branch
git merge <branch>	Merge branch
git log	View commit history
git diff	Show changes
git stash	Temporarily save changes
git stash pop	Restore stashed changes

Keyboard Shortcuts (GitHub Web)

Action	Shortcut
Search repository	/
Go to Code	g then c
Go to Issues	g then i
Go to Pull requests	g then p
Go to Actions	g then a
Create issue	c
Submit comment	Ctrl/Cmd + Enter

GitHub CLI Commands

Install: cli.github.com

Command	Description
gh auth login	Authenticate with GitHub
gh repo clone <repo>	Clone repository
gh pr create	Create pull request
gh pr list	List pull requests
gh pr checkout <number>	Checkout PR locally
gh issue create	Create an issue
gh issue list	List issues

Official Resources

• Documentation: docs.github.com
• GitHub Skills: skills.github.com
• Git Documentation: git-scm.com/doc
• Status Page: githubstatus.com
• Community: github.community
• GitHub CLI: cli.github.com
• GitHub Desktop: desktop.github.com

Support

TechOps Team:

• Slack: #techops-support
• For organization settings, permissions, or access issues

GitHub Support:

• Visit support.github.com
• Check githubstatus.com for service issues
• Browse docs.github.com for guides

Learning Resources:

• GitHub Skills - Interactive tutorials
• Pro Git Book - Free comprehensive guide
• Git Cheat Sheet

---

For detailed documentation and tutorials, visit docs.github.com