CI / CD

In the dynamic world of software development, transitioning from development to production environments poses significant challenges, often involving the meticulous movement of configurations, workflows, and other essential data.

This guide delves into how utilizing Descope's GitHub CI/CD template facilitates a smoother transition of resources from development projects to production environments and significantly enhances efficiency and reliability.

By automating tasks traditionally performed manually, developers can focus on their core work, reducing errors and saving valuable time. This approach accelerates the development cycle and fosters a more robust and agile development process.

Prerequisites

Before you begin utilizing the CI/CD template, you will need to have a few items outlined below.

1. You'll need the project ID you use as a development or sandbox and the project ID you use as a production environment. Essentially, you will need the project IDs for the project you are exporting from and the project you are importing to. These are on the Project settings page.
2. You'll also need to generate a management key within the company settings area for Management Keys. When scoping the management key, ensure it has access to both projects you are exporting/importing from/to.

For this guide, we'll be using the projects referenced below.

Deploy the CI/CD Template

Navigate to Descope's CI/CD Template within GitHub, and then select Use this template.

After selecting Use this template, you will be prompted to create a new repository from the template.

Configure Secrets and Variables

Once the repository has been created, you must add the project IDs and management key to the secrets and variables section of the GitHub repository. This can be done by clicking into the repository's settings, then going to Secrets and Variables, then clicking Actions.

The management key should be stored as a secret by clicking the New Repository Secret button. Then creating the secret stored as MANAGEMENT_KEY.

Next, switch to the variables tab and add two new variables for PRODUCTION_PROJECT_ID and STAGING_PROJECT_ID.

• PRODUCTION_PROJECT_ID - the project ID of the project you are importing to
• STAGING_PROJECT_ID - the project ID of the project you are exporting from

Configure Workflow Permissions

The workflows must be allowed to create pull requests and update the repository.

• In your repo's Settings page, go to Actions and select General on the side panel.
• Scroll to the Workflow permissions section.
• Make sure the Read and Write permissions option is selected.
• Ensure the Allow GitHub Actions to create and approve pull requests option is checked.

Usage

Upon configuring the repository from the template, there will be no project data stored. The following sections will outline how to create a pull request from staging and progress with publishing to production.

Create Pull Request from Staging Project

To create a pull request from the staging environment, follow these steps:

• Go to the Actions page in your repo.
• Select the Create Pull Request from Staging Project workflow.
• Press the Run workflow button and confirm.

• After a short while, a new Pull Request will be created. This can be seen under the Pull Requests tab in the repository.
• You can confirm that the added files contain your staging project's settings and configurations.
• Approve and merge the Pull Request to trigger an automatic deployment into your production project.

You will now see a ProjectSnapshot folder in the repo with files representing all the settings and configurations of your project. Note that the path where the files are stored can be customized in the workflow files.

Deploy to Production Project

Upon successfully approving the pull request, the Deploy to Production Project will automatically run. You can check the status of this run by navigating to the Actions tab within GitHub and then reviewing All workflows or selecting the Deploy to Production Project action from the left menu.

Once this workflow has successfully completed, your Descope flows, styling configurations, etc from your sandbox project will be successfully deployed to your production project. For details of what is included in a project export, see our overview of partial project imports which covers the file structure and editable configurations.

Handling Secrets During Production Deployments

When running the Deploy to Production Project action within the GitHub repo, you may hit a scenario where you've added a new connector (or OAuth provider secrets) within your development environment that has not been created within your production environment. When this occurs, you'll have a failed deployment for the GitHub action. The Descope repository template makes resolving these issues a breeze. The failed deployment will give you exact details about how to fix the problem in the format exampled below.

From the message displayed, we see a connector named Test, which does not have a configuration within the production environment. To resolve this, you need to rerun the workflow manually supplying the JSON displayed within the field for An optional JSON object with additional secrets to inject into the snapshot data.

The JSON can be copied from the message within the failed production deployment. An example can be seen below.

{
  "connector-abc": {
    "name": "Test",
    "secrets": {
      "accessKeyId": "xxxxxxxxxxxxxxx",
      "secretAccessKey": "yyyyyyyyyyyyyy"
    }
  }
}

Once you have copied the JSON and updated the credentials, you can redeploy by:

• Going to Actions
• Click the Deploy to Production Project action
• Click Run workflow - providing the completed JSON within the An optional JSON object with additional secrets to inject into the snapshot data field
• Click Run workflow per the below example.

After completing these steps to resolve the credential error, your connector credentials and other data will be migrated to your production project.