Github Template

This guide walks you through deploying Descope’s GitHub CI/CD template so you can promote project resources from one Descope project to another (such as from development or sandbox to production) using GitHub Actions.

Prerequisites

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

1. The Descope project IDs for the project you are exporting from and the project you are importing to. These are on the Project settings page.
2. A management key created on the Company Settings page of the console. 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 Github 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.

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.