GitHub Essentials

What GitHub is

GitHub is a web platform for hosting Git repositories and collaborating on them. It was founded in 2008 and has been owned by Microsoft since 2018. Git itself, described in What Is Version Control?, knows nothing about GitHub: it stores history and exchanges commits with any remote. GitHub adds everything around that history that a team needs:

• a central place to push to, with access control (Remotes and Collaboration);
• pull requests and code review (Pull Requests and Code Review);
• planning with issues and Projects, and conversation in Discussions;
• automation with GitHub Actions (What Is CI/CD?);
• security features such as secret scanning and Dependabot (Securing Repositories);
• cloud development environments and an AI assistant (Codespaces and Copilot, below).

GitLab, Bitbucket, Azure Repos and self-hosted options such as Gitea offer similar platforms. Because the repository underneath is plain Git, moving the code between them is easy; moving issues, pipelines and settings is the hard part.

Accounts, organizations and visibility

Every repository has one of three visibilities:

• Public: anyone on the internet can see and clone it. Only people you grant access can push.
• Private: only you, the people you invite, and organization members with access can see it.
• Internal: visible to all members of the enterprise, but not to the outside world. It exists only for organizations that belong to an enterprise account, and it is the basis for InnerSource (see below).

In organization repositories, access is granted per person or team with a role: Read, Triage (manage issues and pull requests without write access), Write, Maintain (manage the repository without sensitive or destructive settings) and Admin. Give each person the lowest role that lets them do their work.

The repository page

A repository's page on github.com is organized in tabs. Which tabs you see depends on the features enabled and on your role; Settings, for example, only appears for people with the Maintain or Admin role.

Two small buttons at the top are worth knowing: Watch chooses which notifications you receive from the repository, and Star bookmarks it (and shows appreciation). Fork creates your own copy, as explained in Remotes and Collaboration.

Issues

An issue is a numbered item in a repository's tracker for a bug, task, question or idea. Each issue has a title, a Markdown description and a conversation, and anyone with access can comment, react and be mentioned with @name. Issues, pull requests and discussions share one numbering sequence, so #12 refers to exactly one of them.

Writing Fixes #12 (or Closes #12, Resolves #12, and their other tenses) in a pull request description links the pull request to issue 12, and GitHub closes the issue automatically when the pull request is merged into the repository's default branch. The same keyword in a commit message works when that commit reaches the default branch.

GitHub Projects

GitHub Projects is GitHub's planning tool: a flexible view over issues and pull requests, which can come from many repositories. A project shows the same items in different layouts:

• Table: a spreadsheet-like list with sortable, filterable columns.
• Board: a Kanban board with a column per status, where you drag cards from "Todo" to "Done".
• Roadmap: a timeline based on date or iteration fields.

You can add custom fields (text, number, date, single select, and iterations for sprints), save several views, and use built-in workflows that, for example, set an item to "Done" when its issue is closed. Projects can belong to a user or an organization.

Markdown on GitHub

Markdown is a lightweight markup language: plain text with a few symbols (# for a heading, * for a list item) that is readable as it is and can be rendered as formatted HTML. GitHub uses its own variant, GitHub Flavored Markdown (GFM), everywhere: in .md files, issues, pull requests, comments, Discussions and wikis. GFM adds tables, task lists, strikethrough and automatic links to standard Markdown.

# Core switch replacement

The access switches in **building B** move to the new core on
*14 March*. See issue #12 and ask @mei-chen for the cable plan.

## Steps

1. Back up the running configurations
2. Move the uplinks
3. Verify spanning tree and VLANs

## Checklist

- [x] Change approved
- [ ] Maintenance window announced
- [ ] Rollback plan tested

| Switch | Uplink port | VLANs   |
|--------|-------------|---------|
| asw-b1 | Gi1/0/48    | 10, 20  |
| asw-b2 | Gi1/0/48    | 10, 30  |

```bash
ansible-playbook backup.yml --limit building_b
```

> [!WARNING]
> Do not reload the core switch during office hours.

• A fenced code block (three backticks) with a language name gets syntax highlighting.
• A task list in an issue shows checkboxes that people with access can tick in the browser, and progress such as "1 of 3 tasks" is shown in lists.
• #12, @mei-chen and commit hashes become links automatically.
• > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION] render as highlighted alert boxes.

README and community health files

A README is the file that introduces a project, usually README.md. GitHub renders it below the file list, so it is the first thing every visitor reads. A good README answers: what is this, how do I install or run it, how do I use it, who maintains it and where do I get help. GitHub looks for it in .github/, the repository root and docs/. A public repository with the same name as your account (mei-chen/mei-chen) has a special README that appears on your profile page.

GitHub calls a set of further files community health files. It links to them in the interface, for example when someone opens an issue or a pull request:

An organization can provide defaults for all its repositories (except the license) by placing these files in a public repository named .github; a file in an individual repository overrides the default. A LICENSE must always be added to each repository itself.

Discussions, Codespaces and Copilot

Discussions

GitHub Discussions is a forum for a repository or organization: questions and answers (with a "marked as answer" reply), announcements, ideas and open conversation. The rule of thumb is that an issue is work to be done, while a discussion is a conversation that may or may not lead to work. A discussion can be turned into an issue when it does, and an issue into a discussion when it turns out to be a question.

Codespaces and github.dev

GitHub Codespaces are development environments in the cloud: a container running on a virtual machine that GitHub hosts, with the repository cloned in it, which you open in Visual Studio Code (in the browser or on the desktop) or another supported editor. A .devcontainer/devcontainer.json file in the repository defines the image, tools and extensions, so every team member and every new hire gets the same working setup in minutes. Codespaces are billed by compute time and storage, with a monthly allowance included for personal accounts.

github.dev is lighter: press the . key on a repository page (or change github.com to github.dev in the address) and a browser-based editor opens. It is free and good for editing files and committing, but it has no terminal and cannot run code, because there is no machine behind it.

GitHub Copilot

GitHub Copilot is GitHub's AI coding assistant. It suggests code as you type in the editor, answers questions in a chat, makes multi-file changes in an agent mode in the editor, and can work on its own on GitHub: the Copilot cloud agent (earlier called the Copilot coding agent) can be assigned an issue, makes the change in its own environment and opens a pull request for a human to review. Copilot can use models from several AI providers.

Usage is measured in "GitHub AI Credits", with a monthly allowance included in each plan; older material talks about "premium requests". Plans and prices change often, so check GitHub's plans page before relying on these figures. Business and Enterprise add organization controls such as policies, content exclusion and audit logs.

Open source, InnerSource and the community

GitHub hosts a large share of the world's open-source software. Its contribution model is the one described on these pages: fork, branch, pull request, review. Projects often label approachable work as good first issue for newcomers.

InnerSource applies the same open-source practices inside an organization: code is visible to everyone in the company (for example as internal repositories), any team may propose changes to another team's code through a pull request, and the owning team reviews and merges. It reduces duplicate tools and waiting time across teams, for instance when the network team's automation library gets an improvement from the server team.

The gh command-line tool

Git commands work with any remote; the gh command-line tool talks to GitHub itself, so you can handle issues, pull requests and workflow runs without leaving the terminal. These commands need the network and an account, so they are not run here:

gh auth login                              # sign in once (browser or token)
gh repo create example-org/net-tools --private --clone
gh repo clone example-org/net-tools
gh issue list --label bug
gh issue create --title "R2 NTP drift" --body "Clock is 4 s off since Monday"
gh pr create --fill                        # pull request from the current branch
gh pr checkout 42                          # test a colleague's pull request locally
gh pr merge 42 --squash --delete-branch
gh run list                                # recent GitHub Actions runs