Skip to content
Tutorials Center
My learning

Topics

Lesson 57 of 78 ยท GitHub and Platforms

GitHub Basics

Learn what GitHub adds to Git: repositories, remotes over HTTPS and SSH, README and community files, issues, pull requests, Actions and Pages, with local demos you can run.

Git is a program on your computer. GitHub is a website and a service that hosts Git repositories and adds a lot around them: accounts and permissions, a web interface for browsing code, issues, pull requests, automation, packages and more. They are different things made by different organizations (GitHub is owned by Microsoft), and people often mix them up. You can use Git without GitHub, and alternatives such as GitLab and Bitbucket offer similar features (GitLab, Bitbucket and Self-Hosting).

This lesson is a tour for beginners: what a GitHub repository is, how your local repository connects to it, which files GitHub treats specially, and what the main features do. The sandbox has no internet, so screens and web steps are described, and every Git command is demonstrated against a local bare repository that plays the role of GitHub.

What GitHub adds to Git

When you push a repository to GitHub you get, without installing anything:

  • A shared central copy that everybody pushes to and fetches from, with access control (who may read, who may write).
  • A web view of files, history, blame and diffs, with rendered Markdown.
  • Issues to track bugs, tasks and ideas.
  • Pull requests to propose, discuss, review and merge changes (Pull Requests and Code Review).
  • Forks, personal copies of someone else's repository, for open source contribution (Forks, Upstreams and Contributing).
  • Actions, automation that runs your tests and deployments (GitHub Actions: CI for Your Repository).
  • Pages, free static website hosting from a repository.
  • Releases, Packages, Projects (boards), Discussions, a wiki, security scanning, and cloud development environments (Codespaces).

None of these are part of Git itself. Everything that lives only on GitHub (issues, pull request comments, stars) is not inside your clone. If you ever leave the platform, your commits go with you, but your issues and reviews do not unless you export them.

Accounts, repositories and visibility

You start by creating an account at github.com and turning on two-factor authentication (an authenticator app or a hardware key). Everything lives under an owner: your user name or an organization that you create for a team or a company. A repository's address always has the form owner/name, for example ada/shop.

Creating a repository asks for a few choices:

  • Visibility. Public repositories can be seen (and cloned) by everyone; private ones only by people you invite.
  • Starter files. You can add a README.md, a .gitignore template and a license. If you already have a local project, create the repository empty (no starter files), otherwise your first push is rejected because the remote already has a commit that you do not have.
  • Default branch. Usually main.

Then GitHub shows you the URL to use. There are two kinds (Signing, Credentials and Security explains how each authenticates):

TEXT
HTTPS   https://github.com/ada/shop.git      (token or credential manager)
SSH     [email protected]:ada/shop.git          (SSH key)

Connecting your local repository

The usual first steps for an existing project are: add the remote, push the branch, and set the upstream so that later git push and git pull need no arguments. The next demo does exactly that, with one trick: Git can rewrite URLs on the fly with url.<base>.insteadOf. We use it to make the address https://github.com/ada/shop.git point at a folder inside the sandbox, so you can run the real commands without a network.

Bash Add a remote, push and set the upstream

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git remote add origin <url> only records the address in .git/config; nothing happens on the network until you fetch or push. The conventional name origin means "the place I cloned from or push to". set-url switches between SSH and HTTPS at any time. Our insteadOf line is a sandbox trick; on your own computer you would not add it. git push -u origin main uploaded the branch (* [new branch] main -> main) and printed branch 'main' set up to track 'origin/main', so the branch listing shows [origin/main] next to main. The server now has the branch refs/heads/main (and HEAD, which points to it). Remotes are the subject of Remotes: clone, remote, fetch and push, pull and Tracking Branches.

If you start on GitHub instead, copy the clone URL and run git clone https://github.com/ada/shop.git; a clone sets up origin and the upstream for you.

Files GitHub treats specially

GitHub recognizes a few file names and shows them in a special way. They are ordinary files in your repository, so they are versioned like everything else.

File What GitHub does with it
README.md Rendered on the repository's front page (Markdown). Say what the project is, how to install and use it, how to contribute.
LICENSE Detected and shown in the sidebar. Without one, nobody else may legally reuse your code.
CONTRIBUTING.md Linked when people open an issue or pull request.
CODE_OF_CONDUCT.md, SECURITY.md Linked from the community page; SECURITY.md explains how to report vulnerabilities.
.github/ISSUE_TEMPLATE/* Templates offered when someone creates an issue.
.github/PULL_REQUEST_TEMPLATE.md Pre-fills the description of every new pull request.
.github/CODEOWNERS Automatically requests reviews from owners of changed paths.
.github/workflows/*.yml GitHub Actions workflows.
.gitignore Same as locally (.gitignore and Untracked Files).

The .github folder is also the right place for community files that apply to all repositories of an owner: create a repository called .github and put defaults in it.

Bash Community files in a .github folder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

All seven files went into one commit. The two lines in CODEOWNERS mean "Ada owns everything, and the docs-team also owns docs/"; later patterns win. The issue template starts with a front matter block (name, about, labels) that GitHub reads to build the "New issue" chooser.

Issues

An issue is a discussion thread about one problem or task: a title, a description, comments, labels (bug, enhancement), an assignee, a milestone and a number such as #12. Numbers are shared between issues and pull requests in a repository. Good issues say what you expected, what happened and how to reproduce it. Issues, Projects and Project Management goes further.

Commits and pull requests can talk to issues through the text of their messages. Writing #12 creates a link. Writing a closing keyword before it (fixes, closes, resolves, in any case, plus forms like fixed and closed) closes that issue automatically when the change reaches the repository's default branch. You can test the pattern locally:

Bash Issue references in commit messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Three commits mention an issue, but the last one only says see #20, which links without closing. The second pipeline keeps only keyword-prefixed references and prints 12, 15 and 16. GitHub itself applies this rule when the pull request is merged into the default branch, not when you push a feature branch.

Pull requests

A pull request (PR) says: "please merge my branch into yours". You push a branch, open a PR on the web page, and GitHub shows the diff, the commits, the conversation and the results of automated checks. Reviewers comment on lines, request changes or approve, and a maintainer merges using one of three buttons: merge commit, squash and merge or rebase and merge (Merging Branches, Rebasing). The whole workflow, including review etiquette and keeping a branch up to date, is covered in Pull Requests and Code Review. A pull request is a GitHub feature; Git itself only sees branches and merges.

Writing a README in Markdown

README.md is written in Markdown, a plain-text format that GitHub renders as formatted text. These are the building blocks you will use every day (GitHub adds a few extras, called GitHub Flavored Markdown):

MARKDOWN
# Project title            (one # is a title, ## and ### are sub-headings)

Plain paragraph with **bold**, *italic*, ***both*** and ~~strikethrough~~.

> A blockquote, handy for notes and warnings.

---                        (a horizontal rule)

- Unordered list item
- Another item
  - Nested item

1. Numbered step
2. Another step

- [x] Task list item, done
- [ ] Task list item, open

Inline `code` and a [link](https://example.com).

```bash
npm install          # a fenced block; the language name enables syntax highlighting
```

| Column A | Column B |
| -------- | -------- |
| cell     | cell     |

Inline math such as $E = mc^2$ is rendered on GitHub.

A good README answers, in this order: what the project is, how to install it, how to use it (a short example), how to contribute (link to CONTRIBUTING.md) and which license applies. Put installation and usage in fenced code blocks so readers can copy them, and add a screenshot or badge only if it helps. A README can also live in docs/ or .github/; GitHub shows the first one it finds.

Actions and Pages

GitHub Actions runs scripts in response to events such as a push or a pull request. A workflow is a YAML file in .github/workflows/. Its typical job: install dependencies, run tests and linters, and report a green check or red cross on the commit. The next lesson teaches the syntax in detail (GitHub Actions: CI for Your Repository).

GitHub Pages publishes static files as a website at https://owner.github.io/repo/ (or your own domain). You choose a branch and folder (main and /docs, or the output of an Actions workflow) in the repository settings. It is a popular place for documentation, portfolios and blogs built with tools such as Jekyll, Hugo or Vite.

The GitHub CLI

The gh command (separate from Git) lets you use many GitHub features from the terminal. It is not available in the sandbox, so the examples are read-only. Install it with your package manager: winget install GitHub.cli on Windows, brew install gh on macOS, or sudo apt install gh / sudo dnf install gh on Linux. Then sign in once with gh auth login: it asks for the host, the protocol (HTTPS or SSH) and how to authenticate (a browser flow or a token), and gh auth status shows who you are.

CONSOLE
$ gh auth login                       # sign in once (browser or token)
$ gh repo create ada/shop --private --source=. --push
$ gh repo clone ada/shop              # clone without typing the full URL
$ gh issue create --title "Cart total is wrong" --label bug
$ gh issue list --assignee @me        # issues assigned to you
$ gh pr create --fill                 # open a pull request from the current branch
$ gh pr checkout 42                   # fetch and switch to someone's PR branch
$ gh pr review 42 --approve           # review from the terminal
$ gh pr merge 42 --squash --delete-branch
$ gh pr status                        # your PRs and the checks on them
$ gh run list                         # recent Actions runs
$ gh run watch                        # follow a running Actions workflow
$ gh workflow run ci.yml              # trigger a workflow that has workflow_dispatch
$ gh gist create notes.txt --public   # share a snippet as a gist
$ gh release create v1.2.0 --generate-notes ./dist/app.zip
$ gh api repos/ada/shop/issues        # call any REST endpoint with your login

Most commands guess the repository from the origin remote of the current folder, and add --web to open the same page in the browser. Habits worth having: use --json with --jq to script output, create aliases with gh alias set, and prefer gh auth login over pasting tokens into config files.

Reading a GitHub address in a script

Scripts often need the owner and repository name from git remote get-url origin. The URL comes in several shapes, so parse carefully:

Bash Parse owner and repo from any remote URL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The four hosted forms all give owner=ada repo=shop; the local path is reported as unsupported instead of producing nonsense. Bash parameter expansion (${var#pattern}, ${var%pattern}) does the work without any external tool.

Good habits on GitHub

  • Keep main protected: require pull requests and passing checks (Signing, Credentials and Security).
  • Write a useful README first; it is the most-read file of any project.
  • Make small, focused pull requests with a clear description and a linked issue.
  • Never commit secrets, even to a private repository: private repositories get cloned, forked and made public more often than you think.
  • Do not treat GitHub as a backup of your only copy of important work; it is a collaboration platform, and every clone is a full backup of the history.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which statement about Git and GitHub is correct?

    Git is open source software that runs anywhere. GitHub hosts Git repositories and adds issues, pull requests, Actions and more.
  2. 2. What does git push -u origin main do beyond uploading the branch?

    -u (--set-upstream) records the tracking relationship in .git/config, as shown by git branch -vv.
  3. 3. Why should you usually create an empty repository on GitHub when you already have a local project?

    A starter commit on the server makes the histories diverge. You can still fix it by pulling first, but starting empty avoids the detour.
  4. 4. Which commit message line closes issue 7 when the change reaches the default branch?

    A closing keyword (fix, fixes, fixed, close, closes, closed, resolve, resolves, resolved) followed by #number closes the issue. 'see #7' only links.
  5. 5. Where does a GitHub Actions workflow live?

    Workflows are versioned files in the repository, so they are reviewed and changed like code.

Summary

  • Git is the tool; GitHub is a hosting service that adds accounts, permissions, issues, pull requests, Actions, Pages and more. Those extras live on GitHub, not in your clone.
  • A repository is addressed as owner/name and can be cloned over HTTPS or SSH; git remote add, set-url and push -u connect a local repository to it.
  • Create an empty repository when you push an existing project, so histories do not diverge.
  • Special files: README.md, LICENSE, CONTRIBUTING.md, SECURITY.md, issue and PR templates, CODEOWNERS and .github/workflows/*.yml.
  • Issues have numbers; #12 links, and fixes #12 closes the issue when merged into the default branch. Pull requests propose merging a branch and carry review and checks.
  • The gh CLI brings repositories, issues and PRs to the terminal.

Next: GitHub Actions: CI for Your Repository