TABLE OF CONTENTS

• Overview
  • Scheduled
  • Action-driven
• GitHub integration
  • Create the Personal Access Token
  • Mirror the repository
  • Create a Direktiv Authentication Token
  • Action-driven GitHub 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.

GitHub integration

Create the Personal Access Token

The integration into GitHub using a Personal Access Token (PAT) is straightforward. The first step would be to create a PAT on GitHub (if you don't already have one) using the following steps:

1. Make sure you have logged into GitHub and have access to the repository you want to synchronise. 
2. Click on your profile icon (top-left) and select the "Settings" option. This will load your user profile settings page
3. In the left-hand menu, select the "Developer Settings", which will take you to the GitHub Apps default landing page.
4. In the drop-down on the left, select the "Personal access tokens" option.

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:

ghp_waw9jauruk0QuvVs43uC2kaTWIF1t7kPkbob

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

Mirror the repository

The GitHub repository can be added on a namespace level or on a directory level. The configuration for the GitHub 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 GitHub above
• Ref: the branch to synchronise
• Cron: if using a scheduled synchronisation
• Token: PAT token created

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 GitHub to run an action on 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. 

Action-driven GitHub integration

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

The create an GitHub Action, the following steps can be followed:

1. In the GitHub repository, select the Actions tab to create a new action.
2. Select the "Create your own workflow"
3. 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

   4. DIREKTIV_TOKEN: authentication token created in Direktiv for the namespace (this should be a secret configured in Settings -> Secrets and variables -> Actions -> New repository secret)

name: Direktiv Synchronisation

# Controls when the workflow will run

on:
  push:
    branches: [ "main" ]

env:
  DIREKTIV_URL: ''
  DIREKTIV_NAMESPACE: ''
  DIREKTIV_DIRECTORY: ''

jobs:
  run-updater:
    runs-on: ubuntu-latest
    steps:
    - name: REST API with curl to ${{ env.DIREKTIV_URL }}
      run: |
        curl -X POST "${{ env.DIREKTIV_URL }}/api/namespaces/${{ env.DIREKTIV_NAMESPACE }}/tree${{ env.DIREKTIV_DIRECTORY }}?op=sync-mirror&force=true" -H "direktiv-token: ${{ secrets.DIREKTIV_TOKEN }}"

The repository containing the code is available from https://github.com/direktiv/direktiv-github-action/blob/main/action.yaml or the action can be directly imported from the GitHub Marketplace