TABLE OF CONTENTS

• Overview
  • Scheduled
  • Action-driven
• GitLab integration
  • Create the Personal Access Token
  • Mirror the repository
  • Create a Direktiv Authentication Token
  • Pipeline driven GitLab integration

Overview

Direktiv supports different mechanisms for Git authentication. The most common one is using access tokens, but SSH keys are also supported. When a new namespace or directory is created it can be connected to a Git repository.

The Git integration between Direktiv and a Git repository is always one-way. Direktiv will synchronise the repository from the Git provider. The frequency or method of synchronisation is up to the user:

• Scheduled: using the "Cron" feature described above
• Action driven: from GitLab or GitHub

Scheduled

This uses a simple cron job configuration. The structure of a cron configuration is shown below:

Here are a couple of examples:

Action-driven

These are discussed separately in the sections below.

GitLab integration

Create the Personal Access Token

The integration into GitLab uses either a Personal Access Token (PAT) or a Project Access Token. The first step would be to create a PAT on GitLab (if you don't already have one) using the following steps:

1. Make sure you have logged into GitLab and have access to the project you want to synchronise. 
2. Click on your profile icon (top-left) and select the "Preferences" option. This will load your user profile settings page
3. In the left-hand menu, select the "Access Tokens", which will take you to the GitLab Personal Access Tokens creation page.

From here the user can create a PAT. Remember to save the PAT as it cannot be copied or changed after the window is closed / navigated away from.

The GitHub token will look something similar to this:

glpat--Egp7KHqCuJRBqiUJJnj

This can now be used to authenticate the pull request from Direktiv to GitLab.

Mirror the repository

The GitLab repository can be added on a namespace level or on a directory level. The configuration for the GitLab integration is shown below.

The configuration settings are:

• Namespace/folder: new namespace or folder to create (depending which level the repository is being synchronised)
• Authentication Method: Access Token being used as created in GitLab above
• Ref: the branch to synchronise
• Cron: if using a scheduled synchronisation
• Token: PAT token in the following format:

nouser:{token}

The status of the mirror and synchronisation can be seen on the "Mirror Info" button in the top-right of the Explorer view.

Create a Direktiv Authentication Token

Since we're configuring GitLab to run an CI/CD pipeline to Direktiv (i.e. synchronise the repository), authentication is needed to the Direktiv instance.

The create an authentication token for the Enterprise Edition, the following steps can be followed:

1. Make sure you have logged into Direktiv and have access to the namespace you want to synchronise. 
2. Click on the "Permissions" option in the left-hand menu. This will load the Group Policy and Policy Editor options. 
3. In the top-right corner of the "Group Policy" window, click on the "+Auth Token" option. 
4. The following options are needed to configure the Authentication Token:
   1. Lifetime: the duration for which this token should be valid in ISO861 format. Example, a token that needs to last for 1 year would be "P1Y". To represent a duration of "three years, six months, four days, twelve hours, thirty minutes, and five seconds": "P3Y6M4DT12H30M5S"
   2. Token description: describe the use for the token, as it will be displayed as a pop-up when hovering over the token once created
   3. Permissions: select the permissions to allocate to the token. For Git integration the minimal permissions should explorerManage & explorerView. 

Pipeline driven GitLab integration

Now that we have the GitLab project successfully synchronised with GitHub and we have a Direktiv Authentication token, GitLab can be configured to automatically invoke a pipeline to the Direktiv namespace to synchronise the repository (as an example on a code push).

The create an GitLab pipeline, the following steps can be followed:

1. In the GitLab interface, select the the "Settings", and then the "CI/CD" option.
2. In the CI/CD Settings page, scroll down to the "Variables" section and click the "Expand" button.
3. Create a masked variable for the Direktiv Authentication Token with the following settings:
   1. Key: DIREKTIV_TOKEN
   2. Value: paste the Direktiv Authentication Token in here
   3. Type: Variable
   4. Mask Variable: Select
4. Select the "CI/CD" option on the top-level menu and then the "Editor"
5.  Paste the workflow configuration below and configure the following variables:

   1. DIREKTIV_URL: Direktiv URL and port in the format https://(direktiv-url):(direktiv-port)

   2. DIREKTIV_NAMESPACE: namespace in Direktiv to synchronise

   3. (OPTIONAL) DIREKTIV_DIRECTORY: if the sync is happening to a directory, add the full path for the sync i.e. /workflows/directory

stages: # List of stages for jobs, and their order of execution
  - sync

sync-job: # This job runs in the sync stage, which is the only stage
  stage: sync
  variables:
    DIREKTIV_URL: "https://dev.direktiv.io"
    DIREKTIV_NAMESPACE: "demo-namespace"
    DIREKTIV_DIRECTORY: ""
    DIREKTIV_HEADER: "direktiv-token: ${DIREKTIV_TOKEN}"
  script:
    - echo "Sending the sync request ${DIREKTIV_URL}"
    - curl -v -X POST "${DIREKTIV_URL}/api/namespaces/${DIREKTIV_NAMESPACE}/tree${DIREKTIV_DIRECTORY}?op=sync-mirror&force=true" -H "${DIREKTIV_HEADER}"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'

The repository will now be synchronised with the Direktiv instance on a code push.