class: center, middle .logo[  ] ### Recitation _Monday January 30th, 2023_ # Version control & GitLab **Presented by Julian Gallimore** --- # Agenda 1. [What is Git](#chapter-git) 1. [Fabcloud platform](#chapter-fabcloud) 1. [Setup your local environment](#chapter-git-setup) 1. [Git pushing changes](#chapter-git-push) 1. [GitLab CI](#chapter-gitlab-ci) --- name: chapter-fabcloud class: center, middle background-image: url(images/versioncontrol.png) # FABCLOUD .logo_tiny[  ] * Fablabs.io (mapping platform and authentications) * GitLab self-hosted: [gitlab.fabcloud.org](https://gitlab.fabcloud.org/) * Mattermost self-hosted: [chat.academany.org](https://chat.academany.org/) * Nueval (custom evaluation platform): [nueval.fabacademy.org](https://nueval.fabacademy.org/) --- layout: true **Fab Cloud platform** --- ## What is GitLab GitLab is a web-based tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration and deployment pipeline features, using an open-source license, developed by GitLab Inc. > https://about.gitlab.com/ .logo_medium[  ] --- ## What is FabCloud Our self-hosted version of GitLab, were we host all projects related to the academies and host student documentation websites. User login is managed by our Single-Sign-On service [fablabs.io](http://fablabs.io) (You should have an email with details how to login). > https://gitlab.fabcloud.org/ .logo_small.center[  ] --- ## Fablabs.io - Online platform that maps the FabLab network world-wide - Provides the user account logins for our tools GitLab & Nueval --- ## Gitlab & FabAcademy structure We use GitLab for all the content related to Fab Academy. #### What we do with Gitlab 1. Keep all student files under version control 1. Host published websites of students (with [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html) and using [static site generators](http://www.staticgen.com)) 1. Track [groups](https://gitlab.fabcloud.org/academany/fabacademy/2023/labs) of students, labs, instructors 1. Host the FabAcademy class [site](http://fabacademy.org/2023) for (schedule, labs, students list pages) 1. Discuss class [issues](https://gitlab.fabcloud.org/academany/fabacademy/2023/class/-/issues) 1. Use Gitlab as a project management tool (issues, milestones, boards) 1. Take meeting notes using [Markdown](https://docs.gitlab.com/ee/user/markdown.html). --- ### Fab Academy GitLab structure .logo_medium.center[  ] --- class: middle, center ### Demo the GitLab web interface Visit [gitlab.fabcloud.org/academany/fabacademy/2023/](https://gitlab.fabcloud.org/academany/fabacademy/2023/) --- layout: true **Git** --- name: chapter-git # What is Git > [git-scm.com](https://git-scm.com) - Git is a tool used for tracking to your project files - Saving your changes is called a Commit - Everything is stored in a Repository - View history of all commits (who/when/what changed) - Revert/restore past changes (good if anything breaks) - Push commits (changes) to remote central repo (upstream/origin) - Multiple locations can sync their changes with origin [Learn Git by Atlassian](https://www.atlassian.com/git/tutorials/what-is-version-control) [Wikipedia.org/wiki/Git](https://en.wikipedia.org/wiki/Git) --- name: chapter-gitlab-ci # GitLab CI One of the killer features of Gitlab. CI stands for [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) a common pracmtice of software development. .full-width[  ] --- layout: true **GitLab CI** --- ## What this is capable of: - Compiling websites with static site generators - Make beautiful documentation using Gitbook, Sphinx, Mkdocs - Automated Testing for software - Resizing images - Integrating content from different sources - ...much more Read more at [Gitlab Docs](https://docs.gitlab.com/ee/ci/) --- ## How does it work? - You commit a `.gitlab-ci.yml` file in your repo (see [HTML example](https://gitlab.com/pages/plain-html/-/blob/master/.gitlab-ci.yml)) - Push the commit - Then a "runner" server will pick up your commit and start a "Pipeline" process for that commit - Reading the `.gitlab-ci.yml` file will execute the above script in a [Docker](https://www.docker.com/) container. - After completing the steps in the `yml` file, GitLab stores the results (or publishes the file on the web for "pages" job) .caption[ Keep in mind, only the most recent Pipeline matters. So older pipelines from previous pushes/commits that failed can be ignore if the most recent commit passed successfully. ] GitLab has a list of example repositories for common static static site generators or HTML, have a look at some of their `.gitlab-ci.yml` examples at: [gitlab.com/pages](https://gitlab.com/pages) --- ## CI build process flow .full-width.center[  ] --- ## CI Pipelines Each time your commits get pushed, these are example tasks that can happen in a **Pipeline** on a **Runner** .center[.full-width[]] You can monitor pipelines in the "Gitlab CI/CD" menu item. --- ## Example: CI file ```yml # What type of container should run this job (where the script will run) image: busybox # This is the "job" name pages: # This tells GitLab which group the "job" belongs stage: deploy # These are the commands that will be run in the job (ie. for HTML nothing needs to be compiled) script: - echo "nothing to do" # BUT if using mkdocs, one would write the following: - mkdocs build --site-dir public # Tells GitLab which folder to copy out of the "job" to send to another "job" artifacts: paths: # Select the public folder, so that in this case can be published to GitLab Pages - public # Defines when to run this "job" when a commit is pushed (eg. for the default branch only) rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` --- ## CI examples Keep in mind, to deploy to GitLab Pages there needs to be a folder called "public" with the HTML to publish. * [Mkdocs student template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs) (can copy if you want mkdocs) * [Snippet: Using NPM with framework example](https://gitlab.fabcloud.org/-/snippets/120) (React,Vue,Angular,etc) * [Snippet: Idea for Node install and cli TailwindCSS](https://gitlab.fabcloud.org/-/snippets/117) * [Snippet: Plain HTML example ](https://gitlab.fabcloud.org/-/snippets/118) * [Initial student repo template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-html) --- class: middle, center ### Demo GitLab CI interface Visit [gitlab.fabcloud.org/academany/fabacademy/2023/site](https://gitlab.fabcloud.org/academany/fabacademy/2023/site/-/pipelines) --- layout: true **ACCOUNT SETUP** --- class: middle, center ## Setup Git locally --- name: chapter-git-setup class: middle center ## Install Git on your computer See [git-scm.com/downloads](https://www.git-scm.com/downloads) on installation ideas .caption[ For example macos using Homebrew cli with _brew install git_ or Ubuntu with `apt install git` ] --- ## SSH Keys Git uses the SSH protocol to establish secure communication between your computer and the GIT server hosting your repository. This makes sure only you can update your repository and nobody else can tamper the communication. **Without SSH Key you can only use the web interface**. SSH Keys allow you to use the GIT repository securely, without requiring a password every time you push. #### Generate your [SSH Key](https://docs.gitlab.com/ee/user/ssh.html#generate-an-ssh-key-pair) - Linux and MacOS ```terminal ssh-keygen -t ed25519 -C "your.email@example.com" ``` - Windows [Using PuttyGEN](https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen) --- ### Add the public key to your GitLab profile [See GitLab docs](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account) .caption[ Go to the top navigation bar, click your Profile image > Settings > SSH Keys ] Copy the **PUBLIC key** only, from where you just created the keys: ```terminal cat ~/.ssh/id_ed25519_fabcloud.pub ``` .full-width[  ] --- ## Clone your project locally Go to your students project page, in GitLab, and look for the blue "clone" button to copy the SSH URL. Then in your terminal, enter the command `git clone` followed by the copied URL. ```terminal git clone <git@gitlab.fabcloud.org/url-to-git-repo-here> <name-of-folder> ``` --- ## Setup Git locally It is a good idea to configure git on your computer with your name and email, so that when you make commits they can be attributed to you. ```terminal git config user.name "Your Name" git config user.email "your.email@example.com" ``` .caption[ Please use the same name and email address as you use to login to GitLab (check your GitLab settings). Keep in mind if you have other Git accounts when using the `--global` parameter to change the email for all repos. ] See commit author below, from `git log`: .logo_medium.center[  ] --- name: chapter-git-push ## How to push local changes After making some changes to files, you will want to push these changes to GitLab so they can get published. First have a look at the state of your working directory and staging area. ```terminal git status ``` Next selected the changed files, moving them to the staging area. ```terminal git add docs/path-to-your-file.md ``` Commit the selected changes in the staging area, including a message. ```terminal git commit -m "Added my name" ``` Push your new commit to remote repository, GitLab. ```terminal git push ``` --- ## About Git staging process The diagram below illustrates the different areas in your local git repository. .full-width[  ] --- ## Check errors when pushing Example what an error looks like when pushing in GIT. .full-width[  ] .caption[ This error is GitLab limiting you to 10MB per commit. Amend your previous commit to remove some larger images/files. ] --- ## How to pull latest changes It is a good idea to always check if there are commits on the remote repository you do not have locally. This can happen if you made changes directly on GitLab or someone else pushed some commits. ```terminal git pull --rebase ``` .caption[ Make sure you have no pending changes in your working directory before pulling. It is safe to run this command all the time, as there is no destructive behavior by default ] To reset your local repo to match what is in GitLab (removing any local changes and pending commits). This is good way if things are just not working and you are stuck. ```terminal git reset --hard origin/main ``` --- ## Extra useful commands To see what has changed in the file contents of your working directory. ```terminal git diff ``` .caption[ The markings `---` means line was removed, while `+++` means adding a line. ] See a log of all recent commits ```terminal git log --graph ``` .caption[ You can also see visual graph history of commits in GitLab or with a GUI application ] --- layout:true --- # Additional links - [Learn Git by Atlassian](https://www.atlassian.com/git/tutorials/what-is-version-control) (nice descriptions and diagrams) - [Learn Git by GitTower](https://www.git-tower.com/learn/) - [Dangit, Git!](https://dangitgit.com/) (common git problems) - [Fab Academy 2019 Tutorials Git cheat ](https://fabacademy.org/2019/docs/FabAcademy-Tutorials/week01_principles_practices_project_management/git_simple.html) - [Fiore's recitation from 2019](http://fabacademy.org/2019/recitations/version-control/) - [Recitation 2020 by Kris and Viktor.](http://academany.fabcloud.io/fabacademy/2020/recitations/version-control/)