Introduction

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.

Projects used for the CI/CD template explanation within Descope docs.

Deploy the CI/CD Template

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

Utilize the Descope CI/CD template within GitHub.

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

Create a repository for use with the Descope CI/CD template within GitHub.

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.

Configure Secrets for use with the Descope CI/CD template within GitHub.

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

Configure management key secret for use with the Descope CI/CD template within GitHub.

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 project ID variables for use with the Descope CI/CD template within GitHub.

Configure project ID variables for use with the Descope CI/CD template within GitHub - 1.

Configure project ID variables for use with the Descope CI/CD template within GitHub - 2.

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.

Configure workflow permissions for use with the Descope CI/CD template within GitHub.

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.

Create Pull Request from Staging Project with the Descope CI/CD template within GitHub.

  • 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.

Previous of the created Pull Request from Staging Project with the Descope CI/CD template within GitHub.

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.

File structure after committing the pull request Staging Project with the Descope CI/CD template within GitHub.

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. Note: You can edit the workflow actions to address partial imports or overriding of items and configurations.

Deploy to Production Project action with the Descope CI/CD template within GitHub.

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.

Failed deployment to Production Project action with the Descope CI/CD template within GitHub when the credential details are necessary.

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.

Rectifying a failed production deployment with the Descope CI/CD template within GitHub by supplying connector or OAuth provider credentials.

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