Fab Academy 2018 - Version Control

class: center, middle

.logo[![](https://github.com/Academany/academany-mkt/raw/master/fabacademy2017/logo/fabacademy.png)]

_January 29th, 2018_

# Gitlab

**Fiore Basile**

[fiore.basile@gmail.com](mailto:fiore.basile@gmail.com)

.logo_tiny[
![](https://github.com/Academany/academany-mkt/raw/master/fabacademy2017/logo/academany.png)
]
---

## What is Gitlab?

Integrated platform for software* development

.tall-img[![](images/gitlab.png)]

<small>(*) Not only software, also websites, documentation, etc</small>
---

## What is FabCloud
<div style="float: right">
<img src="images/fabcloud.png" style="width: 200px">
</div>

Online services for the Fab Lab Network

Goals:

- Collect all projects in a single place

- Host the Fab Lab Network's websites

- Provide a tool for collaboration and communication between labs

- Any lab and individual can use it for projects and websites also outside Fab Academy

- Register new accounts using [fablabs.io](http://fablabs.io)

Go to

https://gitlab.fabcloud.org

to find our own installation of Gitlab.
---

.small-img[
![](images/gitlabvsgithub.png)
]
Gitlab is like Github, they offer similar features, but:

- **Gitlab is open source** -> it's possible to self-host it on our own server

- Github is **free for public projects**, but you need to **pay for private** projects

- Gitlab provides built-in **Continuous Integration**, more about it later

- **Github has a huge community of users**, useful for publicity

- You can **install Gitlab on any Linux computer** using [OmniBus](https://docs.gitlab.com/omnibus/README.html) or [Docker](https://hub.docker.com/r/gitlab/gitlab-ce/)

- We host it in the [cloud](images/nocloud.jpg) on [Amazon EC2](https://aws.amazon.com/it/ec2/)
  on a [t2.xlarge](https://aws.amazon.com/it/ec2/instance-types/)

---

## Gitlab & FabAcademy

We use GitLab for all the content related to Fab Academy.

So you should **learn how to use it**.

#### What we do with Gitlab

1. Keep all student files under [version control](http://fabacademy.org/2018/recitations/version-control.html)

1. Track groups of students, labs, instructors and staff

1. Publish the FabAcademy [site](http://fabacademy.org/2018)

1. Publish and host [lab](http://fabacademy.org/2018/labs.html) and [student](http://fabacademy.org/2018/students.html) pages

1. Publish documents like the [Fab Academy Handbook](http://fabacademy.org/2018/docs/FabAcademy-Handbook/)

1. Track what needs to be [done](https://gitlab.fabcloud.org/academany/fabacademy/2018/staff/issues) and communicate using Issue trackers

1. Take meeting notes using [Markdown](https://docs.gitlab.com/ee/user/markdown.html), see this [example](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md)

1. Build sites and documentation using [static site generators](http://www.staticgen.com)

---

##  Getting started

Setup you profile

- Login to Gitlab, click on the upper right icon and Settings

- You can add a secondary email address

- You can set your [avatar image](http://gravatar.com) and add some more info about you

####  WARNING:  Don't change your username or email, or bad things will happen

---

## Notifications settings

**Mandatory, or you won't receive important messages from the class**

Click on Notifications and set it to **Watch**
.bordered[
![](images/notifications-settings.png)
]

- You can also setup notifications _selectively_ in each project's dashboard

- Check the _Receive notifications about your own activity_ flag to confirm you receive
notifications, then open a ticket to yourself

---

## SSH Keys

**Mandatory, or you won't able to push your website**.

SSH Keys allow you to use the GIT repository securely, without requiring a password every time.

#### Generate your [SSH Key](https://docs.gitlab.com/ce/ssh/README.html#generating-a-new-ssh-key-pair)

- Linux and MacOS
  ```terminal
  ssh-keygen -t rsa -C "your.email@example.com" -b 4096
  ```

- Windows
  [Using PuttyGEN](https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen)

---

### Add the public key to your authorized keys

.full-width[![](images/add_ssh_key.png)]

---

## Preferences

- You can change Theme

- You can change Synthax hilighting colors

.small-img[![Theme](images/theme.png)]

---

## Version control

- Gitlab uses [GIT](http://git-scm.org)

- Allows to create projects

- Each project is a GIT Repository

- You can have [personal projects](https://gitlab.fabcloud.org/dashboard/projects) and shared projects

- You can _star_ projects to find them easily

- You also have access to your *group's* projects

---

## Edit your website

- Web interface

- Cloning with SSH

- Pushing with SSH

---

### Web interface

- Navigate to [https://gitlab.fabcloud.org/dashboard/projects](https://gitlab.fabcloud.org/dashboard/projects)

- Look for the project with your *username* and click on it

- Good idea to add a **star** to it

.center[![](images/star.png)]

---

.center[.full-width[![](images/aitor.png)]]

[Example student](https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/barcelona/students/student-name)

---

### Cloning with SSH

**Make sure you added your SSH key and set correct permissions**

Copy the repository URL from the web interface

![](images/cloneurl.png)

**Make sure SSH is selected**

Open a terminal

```terminal
git clone git@gitlab.fabcloud.org:academany/fabacademy/2018/labs/b....
```

If you followed a [GIT Tutorial](https://git-scm.com/book/en/v2) you know what to do from here.

---

## Groups and projects

- Groups and subgroups allow to organize people and projects into a hierarchy
- Users are member of groups
- Groups have access to projects with Developer or Master _roles_

.center[.tall-img[![Gitlab Groups and Members](images/group-members.png)]]

---

.full-width[![Gitlab Groups and Projects - Academany](images/gitlab-groups.png)]

---

### Instructors

- You are members of the following groups:
  ```terminal
  Academany > Fab Academy > 2018 > Your Lab > Your Lab Instructor Groups
  ```
  
- You have access to the:
  
  ```terminal
  - Academany > Fab Academy > 2018 > staff
  - Academany > Fab Academy > 2018 > class
  - Academany > Fab Academy > 2018 > Your Lab > site
  - Academany > Fab Academy > 2018 > Your Lab > local
  ```
---

### Students
  
- You are members of the following groups:
  ```terminal
  Academany > Fab Academy > 2018 > Your Lab > Your Lab Students Groups
  ```
- You have access to the:
  ```terminal
  Academany > Fab Academy > 2018 > class
  Academany > Fab Academy > 2018 > Your Lab > students > *
  ```
---

## Issue trackers

- Gitlab allows to track todo items using Issue trackers

- For each project you have access to, you can browse and create issues:

.center[.full-width[![](images/issues.png)]]

---

## Using issues

- Communicate with the class / Replacing emails

- Track your personal tasks (in your projects)

- Use them as kanban boards

- Assign issues to milestones

.center[.full-width[![](images/kanban.png)]]

---

## Issues vs Email

- **Threaded conversations**, so you can catch up quickly and find discussions easily

- **Reply using issues**. Click on the **link in the footer** of the email!

- **No spam.** Keep the conversation relevant

- Everybody will still receive email notifications, **use with care**

- **Close issues **when they are complete

---

## Kanban boards

- You can use issues for creating Kanban boards, similar to [Trello](http://trello.com)

- [Kanban](https://en.wikipedia.org/wiki/Kanban_board) was invented by Toyota for car manufacturing

- Kanban boards show how work progresses i.e. from todo, to doing, to done

- Click on boards to see your issues as a Kanban board

- Good way to track your assignments, project tasks, or personal errands

---

## Milestones

Another way to organize your work, is to group issues into [Milestones](https://en.wikipedia.org/wiki/Milestone_(project_management))

- Each **milestone** represents an **important step** in your project

- **Assign issues to a Milestone**, when all are completed you reached your Milestone

- Easy to distinguish more urgent work from what can be done later

- You can assign **start and end dates** to each milesone

- Milestone help spiral development, and meeting deadlines!

---
## Website Publishing

Using gitlab you can publish content that will be served via Web.

- Your student website, find the link in the [students list](http://fabacademy.org/2018/students.html)

- Your personal website, create a project named `<username>.fabcloud.io`, and browse it
  ```terminal
  http://<username>.fabcloud.io
  ```

- Any other personal project, the address will be
  ```terminal
  http://<username>.fabcloud.io/<project_name>
  ```

---

## How to publish your website

Publishing your website is done using [Gitlab CI](https://docs.gitlab.com/ee/ci/quick_start/)

1. You create a [gitlab-ci.yml](https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/barcelona/students/student-name/blob/master/.gitlab-ci.yml) file of type HTML

2. You upload a [static webpage](https://en.wikipedia.org/wiki/Static_web_page)

3. Every time you update any file in your projects (using git or the web interface) your website will be updated*

(*) updates are almost immediate, but not realtime

---

## GitLab CI

You can do much more with GitLab CI.

CI stands for [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) a common practice of software development.

What this is capable of:

- Compile websites with static site generators

- Create books using Gitbook

- Test software

- Resize images

- ...much more

---

## How does it work?

- Using [Docker](https://www.docker.com/)

- GitLab CI allows to start a virtual server

- install software on it

- and execute it for performing one or more tasks

- storing results and publishing them on the web

This process is described by the **gitlab-ci.yml** file you create into a folder

---

## Build process

.center[.full-width[![](images/gitlab-ci-workflow.png)]]

---

## Pipelines
Each time this happen we are running a **Pipeline** on a **Runner**

.center[.full-width[![](images/types-of-pipelines.svg)]]

You can monitor pipelines in the [Gitlab CI Menu](https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/barcelona/students/student-name/pipelines)

---

## Building websites

Using Gitlab CI you can make your website using a [static site generator](http://staticgen.com)

For example [Jekyll](http://jekyllrb.com).

1. Install [RubyGems](https://rubygems.org/pages/download)
2. Run the following

```terminal
  $ gem install jekyll bundler
  $ jekyll new mysite
  $ cd mysite
  $ jekyll serve
  ```
  then browse to http://localhost:4000

3. Add your repository as remote, and push the content of _mysite_ to gitlab

4. Create [a .gitlab-ci.yml using the Jekyll template](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_four.html)

---
## .gitlab-ci.yml for jekyll

```yaml
image: ruby:2.3.                         ## use docker ruby version 2.3 image

variables:
  JEKYLL_ENV: production                 ## tell jekyll to make a production build
  
cache:
  paths:                                 ## keep a cache of vendor/
  - vendor/                              ## path for faster build

before_script:
  - bundle install --path vendor         ## install jekyll and deps in vendor

pages:
  script:
  - bundle exec jekyll build -d public   ## run jekyll with output in public/
  artifacts:
    paths:
    - public                             ## keep and store the results in public/
  only:
  - master                               ## work only on master branch

```

NOTE: Don't copy text after #, this is a comment

---

## Building documentation

Another common use of Gitlab-CI is to build documents using Markdown, thanks to the
[Gitbook Toolchain](https://toolchain.gitbook.com/).

Gitbook allows to generate:

- A **web-ready** version of your book

- A **PDF** version

- A **mobi/epub** version for e-book readers

All from the same source files.

---

## How to create a gitbook

1. Create a new project / repository i.e. `my-book-project`

2. Install [Gitbook CLI](https://toolchain.gitbook.com/)
```terminal
$ npm install -g gitbook-cli
```

3. Setup an empty book using the terminal
```terminal
$ mkdir my-book-project
$ cd my-book-project
$ gitbook init
Installing GitBook 3.2.3
...
```
4. Edit your book

- Edit the contents of `README.md`, the book's cover page
  - Create new files in [Gitbook Markdown](https://toolchain.gitbook.com/syntax/markdown.html)  
  - And add a link to them into the `SUMMARY.md`, the book's index

---

## How to build a gitbook

4. Test your book using
```terminal
$ gitbook build
```
and opening the generated `index.html` in the `_book/` folder

5. Add a `.gitignore` file containing `_book/` into your folder, so you commit just the source

6. Push the folder in Gitlab, and add the Gitbook [.gitlab-ci.yml](https://gitlab.fabcloud.org/academany/fabacademy/2018/docs/FabAcademy-Handbook/blob/master/.gitlab-ci.yml) 
   
7. Browse your generated gitbook at

`http://<youruser>.fabcloud.io/my-book-project`
     
8. Download the PDF version of your book

`http://<youruser>.fabcloud.io/my-book-project/book.pdf`

---

## Fab Academy gitbooks

- [Fab Academy Handbook](http://fabacademy.org/2018/docs/FabAcademy-Handbook/)

- [Fab Academy Assessment](http://fabacademy.org/2018/docs/FabAcademy-Assessment/)

- [Fab Academy Tutorials](http://fabacademy.org/2018/docs/FabAcademy-Tutorials/)

- [Fab Academy Resources](http://fabacademy.org/2018/docs/FabAcademany-Resources/)

Browse the [repository](https://gitlab.fabcloud.org/academany/fabacademy/2018/docs/FabAcademy-Handbook)
and [.gitlab-ci.yml](https://gitlab.fabcloud.org/academany/fabacademy/2018/docs/FabAcademy-Handbook/blob/master/.gitlab-ci.yml) file for an example

---

## Wikis

- Gitlab also provides a [Wiki](https://en.wikipedia.org/wiki/Wiki) for each project

- Wikis are a good way to write the documentation for a software or hardware project

- Wikis use Markdown, but allow for easy [hyperlinking](https://gitlab.fabcloud.org/help/user/markdown#wiki-specific-markdown)

- To create a new page, add a link:
```
[Title](pagename)
```
Save and click on it.

We expect you to learn HTML and publish a basic side, but for example a good idea is to keep your notes during class on a wiki in your personal website.

---

## Gitlab API

Gitlab offers a [rich API](https://docs.gitlab.com/ee/api/README.html) (application programming interface) for accessing most of the features available via GUI.

**What you can do with the API?**

- Query your groups and projects

- Upload / Edit files

- Open issues

- Check your repo size

- Start CI jobs

- ... almost anything you can do with the GUI

---

## Using the API

- Get your [Personal API Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)

- Pass it to API calls
  ```terminal
  curl --header "Private-Token: SpdRM-dN4xsCGGrcZQRR" \
     https://gitlab.fabcloud.org/api/v4/projects
  ```
  You will get a JSON
  ```json
  [
    {
      "id": 713,
      "description": "",
      "name": "my-great-project",
      "name_with_namespace": "fibasile / my-great-project",
      "path": "my-great-project",
      ...
  ```

---

## Access API from Python

Install the [Python API Wrapper](https://github.com/python-gitlab/python-gitlab)

```python
import gitlab

gl = gitlab.Gitlab('https://gitlab.fabcloud.org', 
                   private_token='SpdRM-dN4xsCGGrcZQRR')
# list all the projects
projects = gl.projects.list()

for project in projects:
    print(project)

# list all project issues
    issues = project.issues.list()
    # Filter using the state, labels and milestone parameters
    issues = project.issues.list(milestone='1.0', state='opened')
    # Order using the order_by and sort parameters
    issues = project.issues.list(order_by='created_at', sort='desc')
    
```

Check the [Docs](https://docs.gitlab.com/ee/api/README.html) for more examples

---

# References

- [Gitlab Documentation](https://docs.gitlab.com/)

- [Gitlab Markdown](https://docs.gitlab.com/ee/user/markdown.html)

- [Gitlab API Docs](https://docs.gitlab.com/ee/api/README.html)

- [Python API wrapper Docs](http://python-gitlab.readthedocs.io/en/stable/)

- [Gitlab CI](https://docs.gitlab.com/ee/ci/yaml/README.html)