Document Details

## Create a pipeline

1. Open your Azure DevOps organization in a web browser by going to `https://dev.azure.com/{your DevOps organization}`
1. Select **New project** to create a new project.
1. Give your project a name and optional description and then select **Create**.
1. On the **Welcome to the project** page, select **Pipelines** and then **Create Pipeline**.
1. Select **GitHub** as the location of your code.
1. Select **Authorize AzurePipelines** to authorize Azure Pipelines to access your GitHub account.
1. On the **Select a repository** page, select your fork of the IoT Central CI/CD GitHub repository.
1. When prompted to log into GitHub and provide permission for Azure Pipelines to access the repository, select **Approve & install**.
1. On the **Configure your pipeline** page, select **Starter pipeline** to get started. The *azure-pipelines.yml* is displayed for you to edit.

## Create a variable group

An easy way to integrate key vault secrets into a pipeline is through variable groups. Use a variable group to ensure the right secrets are available to your deployment script. To create a variable group:

1. Select **Library** in the **Pipelines** section of the menu on the left.
1. Select **+ Variable group**.
1. Enter `keyvault` as the name for your variable group.
1. Enable the toggle to link secrets from an Azure key vault.
1. Select your Azure subscription and authorize it. Then select your production key vault name.

1. Select **Add** to start adding variables to the group.

1. Add the following secrets:
    - The IoT Central API Key for your production app. You called this secret `API-Token` when you created it.
    - The password for the service principal you created previously. You called this secret `SP-Password` when you created it.
1. Select **OK**.
1. Select **Save** to save the variable group.

## Configure your pipeline

Now configure the pipeline to push configuration changes to your IoT Central application:

1. Select **Pipelines** in the **Pipelines** section of the menu on the left.
1. Replace the contents of your pipeline YAML with the following YAML. The configuration assumes your production key vault contains:
    - The API token for your production IoT Central app in a secret called `API-Token`.
    - Your service principal password in a secret called `SP-Password`.
  
    Replace the values for `-AppName` and `-KeyVault` with the appropriate values for your production instances.

    You made a note of the `-AppId` and `-TenantId` when you created your service principal.

    

## Generate IoT Central API tokens

In this guide, your pipeline uses API tokens to interact with your IoT Central applications. It's also possible to use a service principal.

> [!NOTE]
> IoT Central API tokens expire after one year.

Complete the following steps for both your development and production IoT Central apps.

1. In your IoT Central app, select **Permissions** and then **API tokens**.
1. Select **New**.
1. Give the token a name, specify the top-level organization in your app, and set the role to **App Administrator**.
1. Make a note of the API token from your development IoT Central application. You use it later when you run the *IoTC-Config.ps1* script.
1. Save the generated token from the production IoT Central application as a secret called `API-Token` to the production key vault:

    

## Generate a configuration file

These steps produce a JSON configuration file for your development environment based on an existing IoT Central application. You also download all the existing device templates from the application.

1. Run the following PowerShell 7 script in the local copy of the IoT Central CI/CD repository:

    

1. Follow the instructions to sign in to your Azure account.
1. After you sign in, the script displays the IoTC Config options menu. The script can generate a config file from an existing IoT Central application and apply a configuration to another IoT Central application.
1. Select option **1** to generate a configuration file.
1. Enter the necessary parameters and press **Enter**:
    - The API token you generated for your development IoT Central application.
    - The subdomain of your development IoT Central application.
    - Enter *..\Config\Dev* as the folder to store the config file and device templates.
    - The name of your development key vault.

1. The script creates a folder called *IoTC Configuration* in the *Config\Dev* folder in your local copy of the repository. This folder contains a configuration file and a folder called *Device Models* for all the device templates in your application.

## Modify the configuration file

Now that you have a configuration file that represents the settings for your development IoT Central application instance, make any necessary changes before you apply this configuration to your production IoT Central application instance.

1. Create a copy of the *Dev* folder created previously and call it *Production*.
1. Open IoTC-Config.json in the *Production* folder using a text editor.
1. The file has multiple sections. However, if your application doesn't use a particular setting, that section is omitted from the file: