Create and organise your GitHub repository
A repository is the folder on GitHub that holds your project and its full history. Set one up correctly once, and every host and automation tool can build on it.
Create your repository
You need a free GitHub account. Free accounts can have unlimited public and private repositories.
Sign up and start a new repo
- Create an account at github.com/signup and verify your email.
- Press the + button at the top right, then New repository.
Fill in the form
| Field | What to enter |
|---|---|
| Repository name | Short, lowercase, with hyphens, for example my-portfolio |
| Description | One line about the project |
| Public or Private | Public is visible to everyone. Private is visible only to you and people you invite. |
| Add a README file | Tick it, so the repo starts with a front page |
| Add .gitignore | Pick a template such as Node, or none for plain HTML |
| Choose a license | MIT is a common open choice. Skip it for private work. |
Press Create repository
You land on the Code tab. The other tabs matter later: Issues for tasks, Pull requests for reviewing changes, Actions for automation and Settings for everything else.
Add your files
Use the browser for a quick start, or Git on your computer for regular work.
Option A: upload in the browser
- On the Code tab press Add file, then Upload files.
- Drag your files and folders into the page.
- Write a short message such as Add website files and press Commit changes.
Option B: use Git on your computer
Install Git from git-scm.com, then set your name and email once:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"Copy the repo to your computer, using the address from the green Code button:
git clone https://github.com/USERNAME/my-portfolio.git
cd my-portfolioAfter editing files, save and upload your changes:
git add .
git commit -m "Update homepage"
git pushSign in when Git asks
GitHub no longer accepts your account password for Git over HTTPS. Sign in through the browser window that Git Credential Manager opens, run gh auth login if you use GitHub CLI, or paste a personal access token as the password. Create a token under Settings, Developer settings, Personal access tokens.
Organise the folders
A clean layout makes the repo easy to read and lets hosts find your files without extra settings.
Use a simple layout
my-portfolio/
├── index.html
├── about.html
├── css/
│ └── style.css
├── js/
│ └── main.js
├── images/
├── favicon.svg
├── og-image.png
├── README.md
├── .gitignore
├── LICENSE
└── .github/
└── workflows/
└── deploy.yml| Path | Purpose |
|---|---|
index.html | Homepage. Keep it in the root so hosts serve it first. |
css/ js/ images/ | Styles, scripts and pictures, one folder each |
README.md | Front page of the repo, shown on GitHub automatically |
.gitignore | Files Git must never upload |
.github/workflows/ | GitHub Actions automation files |
Name files in lowercase with hyphens and no spaces, for example contact-us.html.
Add a README
# My Portfolio
Short description of what this project is.
## Live site
https://yourdomain.com
## Run locally
Open index.html in a browser, or run `npm install` and `npm run dev`.
## Built with
HTML, CSS and JavaScript.
## License
MITSave it as README.md in the root of the repo.
Add a .gitignore
node_modules/
dist/
.env
.env.local
.DS_Store
*.logSave it as .gitignore. Anything matching these lines stays on your computer, so secrets and bulky folders never reach GitHub.
Branches and everyday commands
Keep main working. Do new work on a branch, then merge it through a pull request.
Make a change safely
- Create a branch:
git switch -c fix-navbar. - Edit files, then
git add .andgit commit -m "Fix navbar". - Run
git push -u origin fix-navbar. - On GitHub press Compare & pull request, then Merge pull request when it looks right.
- Press Delete branch to tidy up.
Commands you will use most
| Command | What it does |
|---|---|
git status | Shows changed and untracked files |
git diff | Shows exactly what you changed |
git add . | Stages every change for the next commit |
git commit -m "message" | Saves a snapshot with a message |
git push | Uploads commits to GitHub |
git pull | Downloads and merges the latest changes |
git switch -c name | Creates and switches to a new branch |
git log --oneline | Lists recent commits in short form |
git restore file | Throws away uncommitted changes to a file |
Repository settings worth setting
Open the Settings tab, or the gear next to About on the Code tab.
| Where | What to do |
|---|---|
| About (Code tab) | Add a description, your website link and topics so people can find the project |
| Settings, Pages | Publish a static site from a branch or from GitHub Actions |
| Settings, Secrets and variables | Store API keys for Actions without putting them in code |
| Settings, Collaborators | Invite people to work on the repo |
| Settings, Branches | Optional rule to protect main so changes go through pull requests |
| Releases (right sidebar) | Attach zips or installers, up to 2 GiB per file |
| Settings, Danger Zone | Change visibility, rename, transfer, archive or delete |
Common mistakes and fixes
Most repo problems fall into one of these.
| Problem | Fix |
|---|---|
| An API key or .env file was uploaded | Revoke and replace the key first. Deleting the file in a new commit does not remove it from history, so clean the history too, for example with git filter-repo. |
| File is too large | GitHub blocks files over 100 MiB and warns above 50 MiB. Use Git LFS, or attach the file to a Release instead. |
| node_modules was committed | Add it to .gitignore, then run git rm -r --cached node_modules and commit. |
| Push rejected: updates were rejected | Someone changed the branch. Run git pull, fix any conflict, then push again. |
| Wrong files in the repo root | Move the project into the root so index.html sits at the top level, then commit. |
| Repo is getting huge | GitHub recommends keeping repositories under 1 GB. Keep videos and big datasets outside Git. |
Common questions
Should my repo be public or private?
Public suits portfolios and open projects, and it is the safe default for free static hosting. Use private for client work or anything with unpublished content, and never store secrets in either.
Can I host a site from a private repo?
Cloudflare, Vercel and Render can all deploy private repos once you grant access. GitHub Pages from a private repo needs a paid GitHub plan.
What is a commit?
A saved snapshot of your files with a message. You can return to any earlier commit if something breaks.
How do I delete a repository?
Open Settings, scroll to Danger Zone, choose Delete this repository and type its name to confirm. Download a copy first if you may need it.