The Direktiv GitHub Action syncrhonises the GitHub repository on which the action is executed with the Direktiv instance and namespace (or folder).
Make sure that you have
- GitHub account with Actions enabled
- Direktiv Authenticaiton Token
- Direktiv URL
- Direktiv namespace (and optionally the full path to the directory if syncing to a directory)
Since we're configuring GitHub to run an action on Direktiv (i.e. synchronise the repository), authentication is needed to the Direktiv instance. If the Open Source version has been deployed, then the authentication token is the "apikey" value configured during the installation (it's also used to authenticate when logging into the frontend).
The create an authentication token for the Enterprise Edition, the following steps can be followed:
- Make sure you have logged into Direktiv and have access to the namespace you want to synchronise.
- Click on the "Permissions" option in the left-hand menu. This will load the Group Policy and Policy Editor options.
- In the top-right corner of the "Group Policy" window, click on the "+Auth Token" option.
- The following options are needed to configure the Authentication Token:
- 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"
- Token description: describe the use for the token, as it will be displayed as a pop-up when hovering over the token once created
- Permissions: select the permissions to allocate to the token. For Git integration the minimal permissions should
explorerManage
&explorerView
.
NOTE: The token is generated and copied to the clipboard. Please take note of the token as it is not recoverable once created.
The GitHub action is executed on a push event and therefore starts whenever a Git commit happens. The Workflow has a single action that executes a HTTP(S) POST to the Direktiv instance with the following structure:
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 }}"
It uses the Direktiv Authorization Token to authenticate to Direktiv and then syncrhonises via its trigger. The result is that all the details from the Git push are transferred to the Direktiv mirror.
An example of workflow
name: Direktiv namespace 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 }}"
- A secret with name DIREKTIV_TOKEN and value your Direktiv API token ( https://knowledge.direktiv.io/git-authentication-with-access-tokens )
- An environment variable called DIREKTIV_URL with a value of the Direktiv instance:
https://{fqdn}:{port}
- An environment variable called DIREKTIV_NAMESPACE with a value of the Direktiv namespace:
workflows
- An optional environment variable called DIREKTIV_DIRECTORY with the full path for the sync:
/workflows/directory
Click the Done button to save your changes and commit.
Now next time you commit anything in your GitHub repository the Direktiv action will also execute.
The action will report if the action was successful. This will be standard curl
output