Overview #
Cyclr’s GitHub Integration feature enables you to export Template Releases directly to your own GitHub repository. You can also import Template Releases from your GitHub repository.
This provides you with a way to transfer Template Releases between Consoles if you have more than one Console, as well as an additional way to store backups of your Templates.
When you export a Template Release through the separate Export Release button, the resulting JSON file you would download contains all the information to re-create that Template Release, including the Releases of any Connectors used by it. That same mechanism is used by the GitHub Integration feature, but instead of downloading the file, it’s sent straight to your GitHub repository.
You’re also able to import Templates previously exported to GitHub into another Cyclr Console that’s configured to work with the same repository, which is how you can transfer them.
Note: GitHub Integration and permissions
To configure Cyclr’s GitHub Integration feature, your Console User will need to have the GitHub Integration “Edit” Permission enabled.
Once setup with valid details, any Console User with appropriate Permissions to Export or Import Template Releases will be able to send them to/retrieve them from GitHub.
Configuration #
Before the feature can be used, you must provide your Cyclr Console with the details to connect to your GitHub repository. You’ll also need to generate a “personal access token” from within GitHub.
Go to a Cyclr Console, then Settings > GitHub Integration:
You can decide to use the same details here for multiple Cyclr Consoles so they all point to the same repository and branch, and only change the Environment Name for each so they have their own folders there.
Explanation of those details:
| Field | Description |
|---|---|
| GitHub Repository Owner | Owner of the GitHub repository to connect to. |
| GitHub Repository Name | Name of the GitHub repository to connect to. |
| GitHub Branch Name | Name of a branch within the GitHub repository to work in. |
| GitHub personal access token | Used to obtain access to the repository. This should have “Read and write” permission on the repository. |
| Environment Name | Used by this Cyclr Console as the name of a folder to work in using the above details. Note: If you have multiple Cyclr Consoles for different stages of your development process, you could use this field to provide values such as “development” and “production” to enable each Console to store copies of Template Releases separately. You can then import other Consoles’ Template Releases. |
When selecting the Save button, Cyclr will immediately attempt to connect to the GitHub repository using the details provided. If that is unsuccessful for any reason – such as invalid details or the access token having expired – Cyclr won’t save those changes.
If it’s successful, a folder will be created in the repository using the value provided in the Console’s Environment Name, and that will contain a basic README.md file.
Push Template Release to GitHub #
If Cyclr has valid GitHub details – and your Console User has the Templates “View“ Permission – when you view the Releases of any Template in your Cyclr Console, there will be an additional Push Release to GitHub button shown:
Selecting that button will immediately push the Template Release to your GitHub repository.
The first time you push a Template Release, Cyclr will create a new folder called “Templates” in GitHub and your Template Release will be created there as a JSON file.
Import Template Release from GitHub #
Having exported a Template Release to your GitHub repository from one Console, you can then import it from GitHub into another Console, provided your Console User has the Templates “Edit” Permission.
When importing Template Releases from GitHub, you can choose to:
- Create a new Template – go to Templates > Template Library and select the Import Template button.
- Create a new Template Release in an existing Template – go to the Template Releases of the appropriate Template, then select the Import Release button.
For both options, you’ll be able to choose where the Template Release information comes from:
- You can upload a previously exported JSON file.
- Copy and paste JSON text content.
- Import from GitHub.
The Import from GitHub area shows a button for each folder found in the GitHub repository and branch defined in that Console, but ignores the folder with the same Environment Name. This means you can only import another Console’s Template Releases directly from GitHub.
Selecting one of the Environment Names shows a list of files found within it in GitHub:
From there you can choose the file to import before selecting the Import button to load it in.
