.. include:: /keyword.rst

.. _gitlab-account-setup:

====================
GitLab Account Setup
====================

|IOT-YOCTO| is currently hosted on |GITLAB| and is available in two different configurations:

- **Public** configurations are built with packages and recipes that are openly available. 
  This configuration lacks some proprietary features.
  Furthermore, certain proprietary components, such as ``libdram``, are provided in binary-only format.
  Neuron SDK support is available in the public flavor.
- **Private** configurations are functional superset of the public configurations,
  and requires access to private repositories.
  In this release, the private image provides these additional features on top of the public configuration:

    - Xtensa-ANN support on Genio 350
    - MT7663 proprietary Wi-Fi driver on Genio 350
    - eFuse writer on all Genio platform
    - ISP support on Genio 1200

For example, the Linux kernel fork for |IOT-YOCTO| is hosted in https://gitlab.com/mediatek/aiot/bsp/linux and you can access it without a GitLab account. However, certain proprietary packages are permission controlled, and require different license agreements.
These packages are currently located under the |AIOT-NDA| namespace.
Building these proprietary packages is disabled by default and can be :ref:`enabled during the build process <build-with-nda>`.

The prebuilt images for both **public** and **private** configurations are available in the :doc:`/sw/yocto/download` page.


.. important::

   You may skip to :doc:`env-setup` if you don't intend to build the private configuration.
   However, if you are behind a corporate firewall, we recommend you to check the :ref:`ssh-redirect` section to redirect GitLab SSH connections to HTTPS.
   
   If you want to build the private configuration, please continue to read the following sections.

Private Configuration Overview
==============================

To access these permission controlled packages and tools, you need to:

1. Sign up for a GitLab account.
2. Request access permission from your MediaTek contact window through email.
3. Generate access tokens for tools such as **git** to access source code repositories.

Setup GitLab Account
====================

Please visit https://gitlab.com/users/sign_up to create an account if you don't have one.
The GitLab **Username** and **Email** are required for permission setup.

Steps
-----

1. Visit https://gitlab.com/users/sign_up and fill the following information:
   
   * **Email** Please use your company email for registration, e.g. `firstname.lastname@your.company.domain` if possible.
   * **Username** Please choose an username that is similar to your email address, e.g. `firstname.lastname` or `firstname.lastname.company` if possible.

2. Install an 2FA authenticator on your mobile device. The following applications are known to work with `gitlab.com`:

   * Android: Google Authenticator
   * iOS: Google Authenticator, LastPass Authenticator

3. Check your email inbox and click the validation link in the confirmation email sent from `gitlab.com`. You might want to check your junk mailbox if you didn't see it in your inbox.
4. Login to |GITLAB| with your username and password.
5. Setup 2FA authenticator according to instructions on the website.

.. warning::

   Unlike login to the website with a browser, you cannot use the login password to fetch source code. Instead, you need to create **access tokens** and use the token as your git passwords.
   Please continue to following sections for permission and access token setup.


Apply for Access Permission
===========================

* Please email your GitLab **Username** and **Email** to your MediaTek contact window for account permission setup.
* Once the permission has been granted, you should receive a notification email from GitLab.com.

After receiving the notification from GitLab.com or from your MediaTek contact window, you should also be able to visit the following URL to confirm that you've been granted permissions to access |IOT-YOCTO| repositories:

|AIOT-NDA|

If you get a login page, a 404 error page or permission error page instead, please notify your MediaTek contact window.


.. _access-token:

Generate Access Tokens
======================

In order to fetch source code from git repositories via HTTPS protocol, instead of using the login password, you have to create an **access tokens** and use it as your git password.
To create an access token, follow these steps:

#. Visit https://gitlab.com/-/user_settings/personal_access_tokens,
   or choose **Preference** and then select **Access Tokens** on your GitLab personal page.

#. In the **Personal Access Token** section, fill the **Token name**, and make sure the following check boxes are ticked:
   
   * ``read_api``
   * ``read_repository``

#. Click the **Create personal access token** button.
   
   .. figure:: /_asset/sw_yocto_get-started_account-setup_access-token.png
      :width: 640px

#. A string representing the access token will be generated. Please store this token in a secure storage, preferably a password manager.
#. Use your GitLab **username** and this **token** as the git HTTPS username and password if prompted in the rest of the steps in this guide.

.. note::

   If you lose your access token, you can always revoke it in the web UI and create a new one. 
   For additional details, please refer to GitLab `documentation <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_.

SSH Setup
=========

Some components in |IOT-YOCTO| are provided by git over SSH protocol by default.
If your would like to use SSH to fetch |IOT-YOCTO|, please :ref:`setup SSH key <ssh-setup>`. 

.. hint::
   
   If your network environment does not support SSH, e.g. behind a corporate firewall, refer to :ref:`redirect git connection from SSH to HTTPS instead <ssh-redirect>`.

.. _ssh-setup:

Setup SSH Key
-------------

To fetch git repositories via SSH in `gitlab.com`, you need to visit https://gitlab.com/-/user_settings/ssh_keys and register your SSH public key first.
For details, please refer to https://docs.gitlab.com/ee/user/ssh.html.

.. _ssh-redirect:

Redirect SSH to HTTPS Download
------------------------------

You can also configure your git tool to redirect SSH connections to HTTPS instead. This might be required if you're behind corporate firewalls that
forbids access to SSH ports. To do so, add the following lines to your ``~/.gitconfig`` file:

.. code-block::

   ############################################ GitLab
   [url "https://gitlab.com"]
      insteadOf = ssh://git@gitlab.com


.. _confirm-account-permission:

Confirm Your Account Setup
==========================

You might want to try the following steps before proceeding to fetch and build |IOT-YOCTO|:

#. **Confirm account permission**: Do you see the web page when visiting https://gitlab.com/mediatek/aiot/nda?
#. **Confirm git HTTPS configuration**: Can you fetch the repository to your Linux host machine using the following command?
   
   .. code-block:: bash
      
      # Use generated access token as password, not your GitLab password.
      git clone https://gitlab.com/mediatek/aiot/nda/libdram.git

#. If successful, delete the ``libdram`` directory that's created:

   .. code-block:: bash

      rm -Rf libdram

#. **Confirm git SSH configuration**: Can you fetch the repository to your Linux host machine using the following command?

   .. code-block:: bash
     
      git clone git@gitlab.com:mediatek/aiot/nda/libdram.git

#. Once again, if successful, delete the ``libdram`` directory that's created:

   .. code-block:: bash

      rm -Rf libdram

Please check your access token, SSH public key, or ``~/.gitconfig`` settings if any steps above failed.