GitHub Setup Guide

What Is GitHub?

GitHub is a website where people store, version, and share files — application code, but equally the prompts, skills, agents, and markdown you build with AI. If Git tracks your changes locally (like a save history on your computer), GitHub is where that history lives in the cloud — backed up, shareable, and accessible from anywhere.

As you build with AI, you’ll create prompts, skills, agents, and project files that become the foundation of your workflows. GitHub is where those files live in the cloud — backed up, versioned, and accessible from any machine. Think of it as your portfolio and safety net in one place. Your files are stored in repositories (project folders that Git tracks), and you work with them by cloning — making a local copy on your computer.

How to Use This Guide

Everyone creates an account. After that the guide forks, and you follow only the path that matches how you’ll work:

You need	Read
An AI agent, automation, or hosted tool to reach GitHub for you	Give an agent or tool access
To work with the files yourself, on your own machine	Work with files on your own machine

Plenty of people need both. Nobody needs to read the whole page top to bottom — Choose how you’ll authenticate explains the difference if you’re not sure which is you.

Create your repository before you generate a token — a token has to be scoped to a repository that already exists. The Repository Creation and Cloning Guide covers that, and its first section needs nothing installed.

New to the vocabulary — repository, commit, push, branch, merge? The Git Concepts Reference explains all of it without asking you to install anything.

Prerequisites

For everyone:

An email address for your GitHub account
Your phone with an authenticator app, for two-factor authentication

Creating an account and generating a token happen entirely in your browser — nothing to install.

Additionally, if you’ll run Git commands yourself:

Git installed (see Git Installation Guide)
An editor such as Cursor or VS Code — useful, but not required for anything in this guide (see Editor Setup Guide)

Create Your GitHub Account

Go to github.com
Click Sign up
Follow the prompts to create your account
Verify your email address
Enable two-factor authentication (2FA):
- Go to Settings → Password and authentication
- Under Two-factor authentication, click Enable two-factor authentication
- Choose an authenticator app (recommended — e.g., 1Password, Authy, Google Authenticator) or a security key
- Scan the QR code with your authenticator app and enter the generated code to confirm
- Save the recovery codes GitHub shows you somewhere safe (a password manager, not a text file) — you’ll need one if you lose access to your authenticator
- Tip: once 2FA is set up, you can also install the GitHub mobile app, sign in, and add it as a second method under Settings → Password and authentication — future sign-ins become a single tap on your phone instead of typing a code

Already have an account with 2FA enabled? Skip ahead to whichever path you need.

Choose How You’ll Authenticate

Your GitHub password gets you into the website. It does not get anything else in — not the tools on your computer, and not an AI agent working on your behalf. Those need their own way to prove they’re allowed.

There are two, and which one you need depends on who is doing the asking:

You, at your own computer. You sign in once, and the tools on that machine remember you. This is a CLI login — CLI means “command line interface”, the text-based way of working with a tool instead of clicking around a website. GitHub’s is called the GitHub CLI.
Something acting on your behalf. An AI agent, an automation, or a hosted tool needs a personal access token — a long string of characters you generate once and paste into that tool. It’s a credential you hand over, like giving someone a key.

The difference that matters: a CLI login is tied to your machine, so anything that isn’t on your machine can’t use it. A token travels — which is what makes it work for a hosted agent, and also what makes it worth protecting.

	Personal access token	GitHub CLI login
What it is	A credential you generate and paste into a tool	You sign in through your browser once; your computer remembers
Use it when	Something other than you needs access — an AI agent, an automation, a scheduled job	You are working on your own machine
How much access	Only the repositories and permissions you tick, and it expires on a date you choose	Broad access to your account, and it doesn’t expire on its own
What to watch	It’s a secret. If it leaks, it works until you revoke it or it expires	Anyone who can use your computer can use your GitHub access

If you generate a token, make it a fine-grained one. GitHub offers two kinds. The older “classic” tokens reach every repository you can reach and grant broad permission scopes. Fine-grained tokens only ever grant the specific repositories and permissions you tick — even at their widest setting.

Give an Agent or Tool Access

Complete this path when something other than you needs to reach GitHub — an AI agent, an automation, or a hosted tool. Nothing here requires installing anything.

Creating a Fine-Grained Personal Access Token

Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens
Click Generate new token
Give it a descriptive name (e.g., claude-code-my-repo)
Choose the Resource owner — your personal account, or an organisation if the repository belongs to one. If your own username is the only option, choose it — that’s the normal case on a personal account. Organisation-owned tokens usually need an admin to approve them before they work, which can take days; start early if that applies to you.
Set an expiration that outlasts whatever you’re building with it — if you’re on a course, set it past the last session; otherwise 30 or 90 days is a good default. On a personal account GitHub also offers No expiration — skip it; an expiry date is your safety net if the token ever leaks. Pick deliberately either way: a token that lapses mid-project silently breaks every integration using it. (Tokens for organisation-owned repositories are usually capped at 366 days by the organisation’s policy.)
Set Repository access — Only select repositories, and choose just the repo(s) needed. Create the repository first if it doesn’t exist yet (see the Repository Creation and Cloning Guide); you can’t select one that isn’t there.

All repositories also exists, and covers current and future repositories — occasionally useful on a personal account holding nothing you care about, when you want a token that keeps working as you add repos. Two reasons to prefer selecting: many tools that consume a token require a specific repository anyway (Notion’s Claude agent connector, for one, states this on its connect screen), and on any account holding real work the wider scope is a genuine risk. Never point a token at an organisation’s full repository list to save a step.
Under Permissions, grant only what’s needed. The tool you’re connecting will list the permissions it requires — treat that list as authoritative. Two you’ll meet often: Contents (read and write files) and Pull requests (open a pull request instead of writing straight to the main branch), each set to Read and write. GitHub adds Metadata: Read automatically.
Click Generate token
Copy the token now — GitHub shows it exactly once and cannot show it to you again

Storing Your Token Safely

Save the token in a password manager (1Password, Bitwarden, etc.) — not in a plain text file, a document, or a note on your computer. If a hosted agent or tool needs the token, paste it directly into that tool’s credential/secret field rather than writing it to disk in your repository.

Work With Files on Your Own Machine

Complete this path when you will be running Git commands locally — in a terminal, an AI code editor, or a coding agent on your machine.

Install GitHub CLI

The GitHub CLI (gh) is the simplest way to authenticate Git on your own machine, and it is what AI code editors and coding agents use to reach GitHub on your behalf. Install it before cloning a repository. Skip this section entirely if you won’t be working with files locally.

macOS

Install with the .pkg installer — no terminal needed. (If you installed Git via Xcode Command Line Tools — the path the Git guide recommends — this is your route.)

Go to the GitHub CLI releases page
Scroll down to Assets and click Show all assets if you don’t see many files listed
Download the file whose name ends in macOS_universal.pkg — it works on every Mac
Double-click the downloaded file and follow the installer prompts

Already use Homebrew? Then this is quicker:

brew install gh

Windows

winget install --id GitHub.cli

winget is not recognized? Some Windows 10 machines (and some corporate laptops) don’t have it. Go to cli.github.com, click Download MSI, and run the downloaded installer instead — no terminal needed.

Authenticate

gh auth login

Before it opens your browser, gh asks four questions in the terminal. Use the arrow keys to choose and press Enter:

Question	Choose
Where do you use GitHub?	GitHub.com
What is your preferred protocol for Git operations on this host?	HTTPS
Authenticate Git with your GitHub credentials?	Yes
How would you like to authenticate GitHub CLI?	Login with a web browser

The exact wording shifts slightly between gh versions, but the questions come in this order and these are the answers to give.

It then shows a one-time code and opens your browser. Paste the code, approve the access, and return to the terminal — it confirms when it’s done.

Verify

gh --version
gh auth status

gh auth status should show you are logged in to github.com as your username.

Official docs: GitHub CLI manual

Troubleshooting

gh is not recognized / command not found after installing?

Close and reopen your terminal, then run gh --version again — a terminal only picks up newly installed programs when it starts

gh auth login fails or hangs?

Make sure you have a browser available to complete the flow
Try gh auth login --web to force the browser-based flow
Check gh auth status afterward to confirm

Token doesn’t work?

Confirm the token hasn’t expired
Confirm the repository you’re targeting is one of the repositories the token was scoped to
Confirm the token has the permission the operation needs (e.g., Contents: Read and write to push commits)

Ask AI for help

If you’re stuck, paste this into ChatGPT, Claude, or Gemini:

I’m setting up GitHub authentication (2FA / gh auth login / a fine-grained personal access token) and getting this error: [paste the error message]. What should I try?

Next Steps

Create a repository and clone it — the next step now that your account and authentication are set up