StyleBook configuration

Import and synchronize StyleBooks from GitHub repository

Consider a scenario where you are using CI/CD processes for your development. Or, a scenario where you are managing all the application source code and deployment artifacts in GitHub.

In the GitHub repository, you might be maintaining several StyleBooks for deploying the Citrix ADC configurations and managing these StyleBooks. You must upload these StyleBooks to Citrix Application Delivery and Management. With this feature, you can directly import your StyleBooks present in GitHub into Citrix Application Delivery and Management. You don’t need to manually copy them from GitHub and then upload them into Citrix Application Delivery and Management. Or, manually synchronize the files in both Citrix Application Delivery and Management and GitHub. Also, you can import and synchronize configuration packs from GitHub.

To import StyleBooks and configuration packs, define a repository in Citrix Application Delivery and Management that represents a GitHub repository. Provide the GitHub repository URL and your username and API token created in GitHub. That means, only authorized users who have a valid account in GitHub can import and sync StyleBooks.

After creating the repository, you can sync Citrix Application Delivery and Management with your GitHub repository. Citrix Application Delivery and Management connects to GitHub and imports StyleBooks and Configuration Packs found in that repository. Citrix Application Delivery and Management then validates the StyleBooks and adds them to the list of StyleBooks in Citrix Application Delivery and Management. StyleBooks are not added to Citrix Application Delivery and Management if they fail validation. You can identify and correct the errors on your StyleBooks. Then, commit the updated versions into your GitHub repository. Later you can try importing them or syncing them again into Citrix Application Delivery and Management.

Important

  • StyleBooks files can be imported and synchronized from any branch of a GitHub repository.

  • You can import and synchronize StyleBooks that have dependent StyleBooks associated with them too. These dependent StyleBooks can be in the Github repository or already present in Citrix Application Delivery and Management.

  • The synchronization of StyleBooks from a GitHub repository must be initiated manually from the Citrix Application Delivery and Management GUI or API. That is, currently, importing and syncing of StyleBooks does not happen automatically based on your GitHub commit activity.

  • The configuration pack file that you want to import must be in the JSON format. Also, the configuration file contents must follow the exported configuration format. Under your GitHub repository, the files associated with the configuration pack must be in the configpacks folder.

You can import StyleBook files to Citrix Application Delivery and Management from any folder in the GitHub repository. To import configuration packs, do the following:

  1. Create a folder with name configpacks under the root directory. Make sure all files associated with configurations are in this folder.

  2. In the configpacks folder, create a JSON file that contains the payload for the configuration pack. This payload is used to synchronize configuration packs. The following is an example payload:

    {
        "config_key": "unique-key-for-configpack",
    
        "parameters": {
            "param-name1": "param-value1",
            "param-name": "param-value2",
            "param-namen": "param-valuen"
        },
        "stylebook": {
            "namespace": "some namespace",
            "name": "somename",
            "version": "spme-version"
        }
    }
    <!--NeedCopy-->
    
    • config_key - A unique ID or name to identify a configuration pack in Citrix Application Delivery and Management. If you do not specify config_key, Citrix Application Delivery and Management auto-generates the ID on creating the configuration pack.

      If the specified ID is found in the Citrix Application Delivery and Management GUI, the sync action updates the configuration pack in the Citrix Application Delivery and Management GUI. Else, it creates a configuration pack with the specified ID.

    • parameters - It contains all the necessary parameters to create or update the configuration pack.

    • stylebook - It is a mandatory property in a JSON file. It contains a namespace, version, and StyleBook name with which you want to associate the configuration pack.

  3. In the configpacks folder, keep all the files that are associated with the configuration pack such as certificates, signature files, and XML files.

Add a repository

  1. In Citrix Application Delivery and Management, go to Applications > Configuration > Repositories. Click Add.

  2. In the Add Repository window, enter the following parameters:

    • Name - Type the name of the repository. This name can be the same as the repository name in GitHub or a different one.

    • Repository URL - Type the GitHub repository URL.

      You can specify a GitHub enterprise URL. It helps you import or synchronize StyleBooks and configuration packs from GitHub enterprise accounts.

    • User Name - Type the username that you use to access the GitHub account or enterprise account.

    • API Token - This token is used to access your GitHub repository. For information on how to create API tokens for your GitHub repository, see the GitHub documentation for creating personal access tokens.

    Add a GitHub repository

  3. Click Create.

    The repository is created in Citrix Application Delivery and Management.

Repository options

The following are the additional options for your repositories:

  • Edit - You can edit the repository URL, user name, and API token.

  • Delete - You can delete the repository along with all the StyleBooks present in Citrix Application Delivery and Management that were imported previously from that GitHub repository.

    Note

    You cannot delete a repository from Citrix Application Delivery and Management if it has any StyleBooks that have configuration packs associated with them. First, delete all the configuration packs of these StyleBooks. You can later remove the repository from Citrix Application Delivery and Management to clean up the StyleBooks from that repository.

  • Reset - You can remove all StyleBooks in Citrix Application Delivery and Management synced from that repository without actually deleting the repository entry.

  • List files - You can see a list of all StyleBooks present in Citrix Application Delivery and Management that originates from the GitHub repository.

List of GitHub repositories

Steps to import StyleBooks and configuration packs from GitHub

After you complete the prerequisites, follow the steps to import StyleBooks and configuration packs from a GitHub repository:

  1. Optional, add a repository if you haven’t added.
  2. Select the repository in the Repositories page.
  3. Click Sync.
Import and synchronize StyleBooks from GitHub repository