Creating Your First Repository

A repository (often shortened to "repo") is the fundamental container on GitHub where all of your project's files, folders, and their complete revision history are stored. Every project you work on through GitHub lives inside a repository, and creating one is always the first step. Understanding exactly what each option does during this setup process will save you from common headaches later — especially when your goal is to publish a live website through GitHub Pages. This topic walks you through the entire repository creation process in depth, from finding the right button to copying the URL you will use to start working.

Navigating to the New Repository Page

GitHub provides two equally valid routes to the repository creation form, and knowing both means you are never left hunting around the interface. The quickest route is the '+' icon located in the top-right corner of any GitHub page, right next to your profile avatar. Clicking it reveals a small dropdown menu — select New repository from that list. The second route is through your personal profile: click your avatar or username to open your profile, select the Repositories tab just below your bio, and then click the green New button on the right-hand side of the page. Both paths deposit you on exactly the same repository creation form, so use whichever feels more natural. Familiarising yourself with both now means you will be faster next time.

Naming Your Repository

The repository name you choose is more than a label — it becomes part of the URL that anyone uses to find your project on GitHub and, critically for this course, part of the web address where your site will be published. Because of this, naming deserves careful thought before you click anything.

• Names must be unique within your own account. You can have a repository called portfolio and so can a million other GitHub users, but you personally cannot have two repositories both called portfolio.
• Allowed characters are letters, numbers, hyphens (-), and underscores (_). Spaces are not permitted. If you type a space, GitHub's form will highlight the error and typically suggest replacing the space with a hyphen — for example, my project would become my-project.
• For your primary GitHub Pages site — a special, automatically published website tied directly to your account — the repository must be named using a precise pattern: username.github.io, where username is replaced with your exact GitHub username, matching its capitalisation. For example, if your GitHub username is jsmith99, the repository must be named jsmith99.github.io. This specific name tells GitHub to treat the repository as your personal site and publish it automatically at https://jsmith99.github.io. No other repository name triggers this behaviour.

If you choose a different name (say, my-website), GitHub Pages can still publish it, but the URL will be longer: https://username.github.io/my-website. For this course, using the username.github.io naming convention is strongly recommended because it produces the cleanest URL and requires the least additional configuration.

Setting Repository Visibility

Directly below the name field, GitHub asks you to choose between Public and Private visibility. This setting controls who can see your repository's contents.

• A Public repository is visible to anyone on the internet, whether or not they have a GitHub account. Anyone can browse your files, read your commit history, and clone your code. This is the standard choice for open-source software, portfolio projects, and anything you intend to share.
• A Private repository is visible only to you and any collaborators you explicitly invite by username. The repository does not appear in search results and cannot be browsed by the public.

For this course project, you must select Public. GitHub Pages on free accounts requires the repository to be public in order to serve a website to the world. If you create a private repository and try to enable GitHub Pages, the site will either not publish at all or will not be accessible to anyone who visits the URL. Select Public now and you avoid that problem entirely.

Initializing the Repository

The initialization section of the form is where you decide whether your new repository starts with some files already in place or starts completely empty. An empty repository is technically valid, but it is harder to work with immediately because Git requires at least one commit before it can function properly. Initializing with one or more files creates that first commit for you automatically.

• Add a README file: Checking this box creates a file called README.md — a Markdown-formatted document that GitHub automatically renders as a formatted page on your repository's main screen. By convention, the README is where you describe what your project is, how to set it up, and any other information a visitor needs. More importantly for your immediate workflow, checking this box means the repository will have its first commit the moment it is created, making it ready to clone to your computer straight away. For this course, always initialize with a README.
• Add a .gitignore: A .gitignore file contains a list of file patterns that Git should deliberately ignore and never track. Common examples include operating system clutter files (like .DS_Store on macOS or Thumbs.db on Windows), editor configuration folders (like .vscode/), and dependency directories generated by package managers (like node_modules/ for Node.js projects). GitHub provides ready-made templates for dozens of project types — selecting the template that matches your technology stack fills the file with sensible defaults automatically. For a simple HTML/CSS website, a .gitignore is less critical, but it is still good practice to include one.
• Choose a license: A license is a legal document that tells others what they are and are not allowed to do with your code. Without a license, copyright law applies by default, meaning others technically have no right to use, copy, or modify your work even if it is publicly visible. Common choices include the MIT License (very permissive — others can do almost anything as long as they credit you) and the GNU GPL (requires derivative works to also be open source). For a course portfolio project, MIT is a common and reasonable choice. Adding a license is considered good professional practice for any public repository.

At minimum, check the Add a README file box before proceeding. This single action ensures your repository is immediately functional and cloneable the moment it is created.

Confirming Repository Creation

Before you click the green Create repository button, take a moment to review your choices at the bottom of the form. Confirm that the repository name is spelled correctly (especially important if you are using the username.github.io pattern — a single typo means GitHub Pages will not work), that visibility is set to Public, and that you have checked the README initialization option. These settings can be changed after creation, but correcting a misnamed repository later adds unnecessary steps.

Once you click Create repository, GitHub processes your request and immediately redirects you to your new repository's main page. You will see:

• The repository name displayed prominently at the top, along with your username in the format username/repository-name.
• A file listing showing any files you chose to initialize (your README.md, .gitignore, and/or license file).
• The rendered content of your README.md displayed below the file listing.
• A Code button (green, near the top right of the file listing area) that reveals your repository's URL.

Click that green Code button and you will see a panel with the repository's URL in HTTPS format, which looks like this:

https://github.com/username/username.github.io.git

Copy this URL — you will use it whenever you need to connect your local computer to this repository, whether by cloning it with Git on the command line or linking it inside a code editor. Keep this URL somewhere accessible as you move into the next steps of the course. Your repository is now live on GitHub and ready for files.