.. highlight:: shell

.. _gitlab:

GITLAB @Jlab
*************
The JLab User Gitlab instance is available here: `<https://code.jlab.org/>`_ .

Login Procedure
---------------
Once you go to the site you will see the login page and select "Login with your institution Credentials" button.

Then you will land in following page:

.. image:: _static/gitlab/login_page.png
   :align: center
   :alt: Gitlab Login Page

|

The default permission and resource level depends which authentication method you choose on your first login.

1. JLab login (Everyone with an @jlab.org account should do this!)
    a. You will be automatically granted access to a number of Hall, Experiment, and/or Division GitLab groups based on your CUE unix group assignments.
    b. You will be automatically granted space to create and manage personal repositories.

2. Other login:
    a. You will only have read only access to open/public projects.
    b. For anything else, someone would need to grant you privileges to the repositories. Please talk to your `Compute Coordinator <https://jlab.servicenowservices.com/kb?id=kb_article_view&sysparm_article=KB0014686>`_ .


Create/Import Projects
----------------------

Creating a New Project
^^^^^^^^^^^^^^^^^^^^^^

To create a new project:

1. Click on the "+" icon in the top navigation bar.
2. Select "New project/repository".
3. Choose "Create blank project" or select a template.
4. Fill in the project details:

   - Project name
   - Project URL: This determines where your project will be located in GitLab's structure.
        
        - Personal namespace: Projects created here will have a URL like `https://code.jlab.org/username/project-name`
        - Group namespace: If you're part of a group, you can create projects within that group. The URL will be `https://code.jlab.org/group-name/project-name`
        - Subgroup namespace: For more complex organizations, you can use subgroups. The URL structure would be `https://code.jlab.org/parent-group/subgroup/project-name`
   
   - Project slug (URL): This is a URL-friendly version of your project name, automatically generated from the project name but can be customized. It will be used in the project's URL and should be unique within the namespace.
   - Visibility level:

     - Private: Only project members can access
     - Internal: Any authenticated user can access
     - Public: Anyone can access (useful for open-source projects)
 
5. Click "Create project".

**Tips for choosing the right namespace:**

    - Personal projects are great for individual work or experiments.
    - Group projects are ideal for team collaborations or department-wide projects.
    - Consider your project's scope and who needs access when deciding on the namespace.
    - You can transfer projects between namespaces later if needed, but it's best to start in the right place.

Importing an Existing Project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Click on the "+" icon in the top navigation bar.
2. Select "New project/repository".
3. Choose "Import project".
4. Select the source of your project (e.g., GitHub, Bitbucket, repository URL and more).

Let's focus on importing from Github.

Importing from GitHub
"""""""""""""""""""""

To import a project from GitHub, you'll need to authenticate using a personal access token (PAT).

Using a Personal Access Token, first generate a GitHub personal access token:

   - Go to https://github.com/settings/tokens
   - Click "Generate new token (classic)"
   - Give your token a descriptive name
   - Select the following scopes:
     - `repo` (Full control of private repositories)
     - `read:org` (Read org and team membership, read org projects) (optional bu recommended)
   - Click "Generate token"
   - Copy the generated token (you won't be able to see it again)

5. Paste your GitHub personal access token
6. Click "List your GitHub repositories"
7. Select the repositories you want to import
8. For each repository, you can:
   - Change the target namespace (where it will be imported in GitLab)
   - Change the target repository name
   - Set the visibility level (Private, Internal, or Public)
9. Click "Import" to start the import process.


**Tips for a smooth import:**
- Ensure your GitHub email address matches your GitLab email for proper author attribution
- Large repositories may take some time to import
- You can check the import status on the project page after starting the import

After the import is complete, you'll have a fully functional GitLab project with your GitHub repository's history, branches, and tags. Issues, pull requests, and wiki pages will also be imported if you selected those options.


GitLab CI/CD
*************

GitLab CI/CD is a built-in Continuous Integration/Continuous Deployment system in GitLab. It allows you to automate your software development workflows, from building and testing to deploying your applications.

Key features:

- Automated pipelines triggered by code changes
- Multi-stage pipelines for complex workflows
- Built-in container registry
- Support for various programming languages and frameworks

For more detailed documentation, visit:
`GitLab CI/CD Documentation <https://docs.gitlab.com/ee/ci/>`_

Analogy to GitHub Actions
-------------------------

GitLab CI/CD is analogous to GitHub Actions. Both are CI/CD systems integrated into their respective platforms. The main differences are:

1. Configuration: GitLab uses ``.gitlab-ci.yml``, while GitHub uses ``.github/workflows/*.yml``
2. Runners: GitLab has its own runner system, while GitHub Actions uses its own hosted runners
3. Integration: GitLab CI/CD is more tightly integrated with other GitLab features

Building Docker Images with Kaniko
----------------------------------

Kaniko is a tool for building container images inside a container or Kubernetes cluster, without requiring a Docker daemon. Here's a basic GitLab CI/CD configuration using Kaniko:

.. code-block:: yaml

   build:
     image:
       name: gcr.io/kaniko-project/executor:debug
       entrypoint: [""]
     script:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
       - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG

This job builds a Docker image using the Dockerfile in your repository and pushes it to the GitLab Container Registry.

For more details: `Using kaniko to build Docker images <https://docs.gitlab.com/ee/ci/docker/using_kaniko.html>`_

.. Commenting out the next bit.  I think the code block above covers what we need 
   and avoids link-rot.  (The 'image url' below is 404'ing already.)
.. Example ``.gitlab-ci.yml`` in code.jlab.org is linked `here <https://code.jlab.org/panta/LaDlib/-/blob/main/.gitlab-ci.yml?ref_type=heads>`_ where a image is build from existing Dockerfile by passing some environment vars and pushed the image to gitlab container regsitry here: `container_registry <https://code.jlab.org/panta/LaDlib/container_registry/38>`_.

GitLab Container Registry
-------------------------

GitLab Container Registry is a secure and private registry for Docker images. It's fully integrated with GitLab, allowing you to store and manage your Docker images within your GitLab projects.

To use it:

1. Enable the Container Registry for your project.

    - Go to settings -> General -> expand "Visibility, project features, permissions" and check the "Container registry"
    - You can set the visibility of the image registry according to the needs of your project.

2. Configure your CI/CD pipeline to push images to the registry
3. Use the images in your deployments

More info: `GitLab Container Registry Documentation <https://docs.gitlab.com/ee/user/packages/container_registry/>`_

The base URL for JLab gitlab container registry is: `<https://codecr.jlab.org>`_ .

Base URL for jlab gitlab container registry is: `<https://codecr.jlab.org>`_ .
Fo example to use one of the image in my personal repo:

.. code-block:: console

  docker run [options] codecr.jlab.org/panta/ladlib:v0.0.1


GitLab Pages
------------

GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab. 

To use it:

1. Enable the Container Registry for your project. 
        - Go to settings -> General -> expand “Visibility, project features, permissions” and check the “Wiki”
        - You can set the visibility of the pages according to the needs of your project.

Here's a basic configuration:

.. code-block:: yaml

   pages:
     stage: deploy
     script:
       - mkdir .public
       - cp -r * .public
       - mv .public public
     artifacts:
       paths:
         - public
     only:
       - main

This job creates a ``public`` directory with your static content and deploys it to GitLab Pages.

More info: `GitLab Pages Documentation <https://docs.gitlab.com/ee/user/project/pages/>`_

Example repo with page is `here <https://code.jlab.org/panta/hcana_container_doc>`_  with corresponding page is this doc `<https://pages.jlab.org/panta/hcana_container_doc/>`_ . Where my ``.gitlab-ci.yml`` is:


.. code-block:: yaml

    image: python:3.7-alpine
    
    pages:
    stage: deploy
    before_script:
        - apk add --no-cache make
    script:
        - pip install -U sphinx sphinx-rtd-theme sphinx-copybutton
        - make html
        - mkdir public
        - cp -r docs/html/* public
    artifacts:
        paths:
        - public
    rules:
        - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH