Week 1: Project Management
GitLab
Installing Homebrew, Git, and Python
To begin, I needed to install homebrew and git on my MacOS. To do this, I typed the following command into my MacOS command terminal.
Then, following the instructions on the git website, I typed the following into the command terminal to install git.
I also downloaded the latest version of python from the official website, but later found that this was not entirely necessary since VSCode has a built-in python extension.
Setting Up My SSH Key
With git and python installed, the next step was to generate my ssh key. This process was completed with much help and guidance from Dylan Heneck's Fab Academy documentation.
To start, I accessed the dev terminal by typing the follwing into the MacOS terminal.
I then ran the keygen command.
It prompted me to enter a file to store my key in. I simply chose the given option, which was /Users/yianhu/.ssh/id_ed25519.
With the ssh key generated, I then ran the follwing command to view the public ssh key, and copied and pasted the output in my GitLab profile under User Settings > SSH Keys.
After that, I opened the .ssh folder in Visual Studio Code and created a file within it called config. In this file, I typed the following:
Doing so ensures that my connection to the remote GitLab repository is unique and identifiable.
To confirm my connection to the GitLab repository, I ran the following command.
This the gave me the follwing output.
PTY allocation request failed on channel 0
Welcome to GitLab, @28hui!
Connection to gitlab.fabcloud.org closed.
Cloning the GitLab Repository
After verying my connection, the next step was to clone my GitLab repository. To do this, I first navigated to GitLab and clicked on the blue button towards the right side called 'Code'. This opened a drop-down that gave me several cloning and downloading options. I copied the path under 'Clone with SSH'.
Once copied, I navigated back to the Terminal and ran the following command to clone my repo.
During this step, I encountered an error. More specifically, after attempting to clone my repo, I received this output:
“Cloning into 'yian-hu'...
git@gitlab.fabcloud.org: Permission denied (publickey).
fatal: Could not read from remote repository
This was caused by the fact that I had pasted my ssh key into the wrong GitLab account (28hui instead of Yianhu80), which meant that the terminal could not establish a connection with the remote repository. To fix this, I simply pasted my .pub ssh key into the account associated with the GitLab repository and re-ran the cloning command.
MkDocs
Creating the Documentation Website with MkDocs
This process was completed with the tremendous help of this tutorial.
To start, I installed MkDocs by typing this command into the MacOS terminal:
I installed it through homebrew, but it can also be installed with python by typing this command:
After installing MkDocs, I changed my terminal directory to my repo yian-hu so that the website would be generated inside it. I then created a new website by typing the following command.
This generated a new website project with the following file structure:
I then opened the project in VSCode and navigated to the mkdocs.yml file. This file serves as the control center of any MkDocs website and allows users to construct and customize the structure, style, and build of their site. In my mkdocs.yml file, I first changed my site named to 'Yian Hu's Fab Academy Documentation'.
To see and test my active website, I ran this command in the terminal.
This gave the output:
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.20 seconds
INFO - [00:01:56] Serving on
http://127.0.0.1:8000/2026/labs/charlotte/students/yian-hu/
Following the given link took me to my website. The link utilizes IP address 127.0.0.1 and operates on port 8000.
Creating Structure Within the Website
With the website created, the next step was to create structure within it. The basic skeleton of my website included an about page, a final project page, and an assignments tab that contains all weeks and assignments. This translated to the following file structure.
The index.md file serves as the about section of my documentation page and is where I introduce myself by providing background information and motives for joining Fab Academy. The assignments folder is where I will be documenting each weeks and it's assignments, and is where the bulk of my webpage will be located. It also contains an images folder, which is where I will be storing all of my images so that they can be linked within each page.
After I created the basic structure of my website, the next step was to modify it to enable customization and change its appearance. First, I downloaded the material theme by running this command in the terminal.
Then, I added the material theme to the mkdocs.yml file to apply it throughout the entire site. This step ended up looking like this.
After applying the theme, I looked for more customization with MkDocs on the internet, and came across a helpful tutorial that explained how to create code blocks and annotations in MkDocs with the material theme. I also found another tutorial from the same website that taught me how to include images in my documentation. Both tutorials altered the mkdocs.yml file and utilized markdown extensions to add customization. Here is what the file contents looked like afterwards.
site_name: Yian Hu's Fab Academy Documentation
use_directory_urls: true
site_url: https://yianhu80.gitlab.fabcloud.org/yian-hu/
site_description: Documentation for Yian Hu's Fab Academy 2026
site_author: Yian Hu
nav:
- Home: index.md
- Assignments:
- Week 01:
- assignments/Week 1/GitLab.md
theme:
name: material
features:
- content.code.copy
- content.code.select
- content.code.annotate
palette:
primary: white
accent: navy
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- attr_list
- md_in_html
- pymdownx.blocks.caption
extra:
annotate:
json: [.s2]
Pushing and Pulling
Pushing and pulling is an essential part of any form of work with GitLab or GitHub because it allows the user to upload their local commits to the remote repository (push) and sync their remote repository with a local working branch (pull). Consistently pushing essentially allows for the user's work to be secured within the remote repository, protecting it from possible machine failure or other local issues. Each push also creates a CI/CD pipeline, which runs tests and security scans that give feedback on code quality. Pulling is incredibly useful in group projects, as it allows for users to maintain the most up-to-date version of their local working branch by fetching changes from the remote repository.
To push and pull, I simply ran commands from this list.
git push # pushes changes to the default remote repository
git push origin branch-name # pushes changes to a specific branch
git push -u origin branch-name # pushes and sets an upstream
git push --force # forces a push by overwriting remote history (this is dangerous because it can irreversably delete other people's work)
git push --force-with-lease # safer version of git push --force
git push --all # pushes all branches
git push --tags # pushes tags
git pull # pulls changes from the default remote and branch
git pull origin branch-name # pulls changes from a specific branch
git fetch # pulls without auto-merging
While pushing my work, I encountered a detrimental error. After running the git push command, I would promptly receive this error.
remote:
remote: ========================================================================
remote:
remote: You are not allowed to push code to this project.
remote:
remote: ========================================================================
remote:
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.
This error was caused by the fact that the command could not detect a remote repository and therefore had no destination when pushing code. Even after attempting several fixes, such as re-establishing connection with my GitLab profile using ssh -T git@gitlab.com and even deleting and re-adding my ssh key, I would still recieve the same fatal or "permission denied" errors. After consulting the help of my peers and ChatGPT, I was able to denote the root of the error. It turns out that I had connected my SSH key to the wrong account, so I was pushing to a remote repository that literally did not exist. This resulted in the fatal: Could not read from remote repository error because there was no repository to read from. To fix this issue, I deleted the existing SSH key from the wrong account and used the following commands to generate a new SSH key, add it to the right account, and then verify its identity so that my computer will use it moving forwards.
-
Generating the key
-
Adding the Key to GitLab
Paste the output in your GitLab profile under "SSH Keys"
-
Configure SSH to Use the Key for GitLab
This should open up the config file. I configured it to look like this.
-
Clear Cached SSH Identities and Add the New Identity
-
Test Connection to GitLab
This should output something like this.
Once completing these steps, I successfully connected to the correct GitLab account and could freely push and pull from the remote repository.