GitHub Repository Setup

What Is GitHub?

GitHub is a cloud hosting platform for Git repositories. It stores your source code online, tracks every change, and lets you collaborate with others.

For Astro Docus, GitHub is the first step before deployment. Most modern hosting platforms (Cloudflare, Vercel, Netlify) connect directly to GitHub and deploy automatically every time you push code.

Without GitHub:

• You would upload files manually every time you make a change
• You would have no version history
• You could not use automatic deployment

With GitHub:

• One push deploys your site
• Full version history
• Easy rollback if something breaks
• Free for public and private repositories

Step 1 — Create a GitHub Account

If you already have an account, skip to Step 2.

1.1 Sign Up

1. Open your browser and go to: https://github.com
2. Click the Sign up button in the top-right corner
3. Fill in the required information:
   • Email address — use one you check frequently
   • Password — at least 8 characters, include numbers and lowercase letters
   • Username — no spaces, use something like yourname-dev
4. Complete the human verification puzzle
5. Click Create account

1.2 Verify Your Email

GitHub sends a confirmation email to the address you provided. Open it and click the verification link .

Important: Check your spam folder if you do not see the email within a few minutes.

1.3 Log In

After verification, go to https://github.com/login and sign in with your credentials .

Step 2 — Install Git Locally

GitHub stores your code online, but you need Git on your computer to send code there.

2.1 Download Git

1. Go to: https://git-scm.com
2. Download the installer for your operating system
3. Run the installer with default settings (click Next through every screen)
4. On Windows, make sure “Git from the command line” is selected

2.2 Verify Installation

Open Command Prompt (Windows) or Terminal (Mac/Linux) and type:

git --version

You should see something like git version 2.45.1 .

Step 3 — Configure Git with Your Identity

Git needs to know who you are. This is a one-time setup .

Run these commands in your terminal (replace with your own details):

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

Use the same email you used to register on GitHub .

To verify the configuration:

git config --global --list

Step 4 — Create a New Repository on GitHub

A repository (repo) is like a cloud folder for your project .

4.1 Create the Repository

1. Log in to GitHub
2. Click the + button in the top-right corner, then select New repository
3. Fill in the form:

Field	What to enter
Repository name	astrodocus or my-docs-site
Description	Optional, e.g., “Documentation site built with Astro Docus”
Public / Private	Choose Public (easier to deploy) or Private (only you can see)
Add a README file	✅ Check this box

4. Click Create repository

4.2 Copy the Repository URL

After creation, you land on the repository page. Click the green Code button and copy the HTTPS URL. It looks like:

https://github.com/your-username/astrodocus.git

You will need this URL in Step 5 .

Step 5 — Push Your Astro Docus Project to GitHub

Now connect your local Astro Docus folder to the GitHub repository and upload it.

5.1 Open Terminal in Your Project Folder

1. Open VS Code
2. Click File → Open Folder and select your Astro Docus project folder
3. Open the built-in terminal with Ctrl + ` (backtick)

5.2 Initialize Git and Commit

Run these commands one by one:

git init
git add .
git commit -m "Initial commit - Astro Docus project"

What each command does:

• git init — creates a local Git repository in your folder
• git add . — stages all files for commit
• git commit -m "..." — saves a snapshot with a descriptive message

5.3 Connect to GitHub and Push

Run these commands (replace the URL with your repository URL from Step 4.2):

git remote add origin https://github.com/your-username/astrodocus.git
git branch -M main
git push -u origin main

What each command does:

• git remote add origin — links your local repo to the GitHub repo
• git branch -M main — renames the default branch to main
• git push -u origin main — uploads your files to GitHub

5.4 Authentication

When prompted for credentials:

• Username: your GitHub username
• Password: a Personal Access Token (not your account password)

Why a token? GitHub removed password authentication for Git operations. You must create a token instead.

How to create a Personal Access Token:

1. Go to GitHub → click your profile picture → Settings
2. Scroll down the left sidebar → Developer settings
3. Click Personal access tokens → Tokens (classic)
4. Click Generate new token (classic)
5. Give it a name (e.g., “Astro Docus deploy”)
6. Set expiration to 90 days or more
7. Check the repo scope (full repository access)
8. Click Generate token
9. Copy the token immediately — you will not see it again

Paste this token as your password when Git prompts you.

Step 6 — Verify the Push

1. Go to your repository page on GitHub: https://github.com/your-username/astrodocus
2. Refresh the page
3. You should see all your project files listed — astro.config.mjs, package.json, src/, public/, etc.

If you see your files, the push succeeded.

Daily Workflow After Setup

Once connected, every change follows the same pattern :

git add .
git commit -m "Description of what you changed"
git push

This is the cycle you will repeat:

1. Edit files locally in VS Code
2. Run git add . to stage changes
3. Run git commit -m "message" to save a snapshot
4. Run git push to send to GitHub

Troubleshooting

Problem	Solution
remote: Repository not found	Check the URL with git remote -v and re-add if wrong
Support for password authentication was removed	Use a Personal Access Token, not your password
failed to push some refs	Run git pull origin main --allow-unrelated-histories first
Git not recognized	Reinstall Git and ensure “Add to PATH” is checked
Authentication failed	Regenerate your Personal Access Token with repo scope

Quick Recap

1. Sign up at github.com
2. Verify your email
3. Install Git from git-scm.com
4. Configure: git config --global user.name/email
5. Create a new repository on GitHub (check "Add README")
6. In VS Code terminal:
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin YOUR_REPO_URL
   git branch -M main
   git push -u origin main
7. Authenticate with Personal Access Token
8. Verify files appear on GitHub

Your Astro Docus project is now on GitHub. This is the foundation for automatic deployment to any hosting platform.

👉 Next: docs/deploy-hosting/cloudflare.md — deploy to Cloudflare Pages with GitHub integration.