As a best practice, each deployment environment (development, staging, production, etc.) should map to a Control Plane Org.

The primary benefit of having each environment under a separate Org is that definitions of different GVCs and workloads can be applied to different Orgs without the need to include an environment name in any object.

For example, in the development Org, you could apply nearly the same YAML manifest files (used by cpln apply) as the production Org with different content for your secrets.

During the promotion process, the image that was built for development can be referred to by other workloads in the same Org and across Orgs. This is a great time saver for lengthy build processes.

​
Promotion using GitHub Actions

By leveraging the functionality of GitHub Actions, promoting code changes from one environment to another is as easy as committing/pushing your code and opening/merging pull requests.

This example project contains three GitHub Actions (in the ./.github/workflows directory) that perform the following:

  1. On a pull request (or updates to an existing pull request) to the main branch, the application is containerized and pushed to the dev Org’s private image registry. The GVC and Review Workload is created/updated by applying the YAML contents of the files ./cpln/cpln-gvc.yaml and ./cpln/cpln-workload.yaml. The name of the Review Workload will be prefixed by the name of the branch that created the pull request.
  2. When a pull request is accepted and the code is merged to the main branch, a dev workload is updated (or created if it doesn’t exists) in the dev Org by applying the same files as step 1, except that the workload name is prefixed with dev. This allows the application to be reviewed and tested before being pushed to the production Org.
  3. The promotion to the stage and prod environment is accomplished by manually executing the Deploy-To-Stage-or-Prod workflow and selecting the target environment. The target GVC and Workload in the production Org is updated (or created if it doesn’t exists) by applying the YAML contents of the files ./cpln/cpln-gvc-prod.yaml and ./cpln/cpln-workload.yaml. The main difference between the two GVC files is that the prod version contains the Pull Secret that is needed to pull the image from the dev Org and the stage and prod workloads refers to the image that was pushed to the development Org.

​
Review Workload

The above example demonstrates the concept of a Review Workload. This workload allows for review and testing of the application before being promoted to upstream workloads. The deployment of the Review Workload occurs when a pull request from a feature branch to the main branch is opened. The application will only be promoted to the dev workload if the pull request is closed and merged.

​
Permissions

To control which users have the ability to perform sensitive actions, such as merging a pull request, you can utilize the built-in capabilities of GitHub by creating a custom repository role.

Review these instructions on how to create a role.

​
Notes

  • The example above demonstrates promoting code across four environments (review and development in one Org, and staging and production in a separate Org). Of course, you can arrange each environment within its own Org, or mix multiple environments within an Org as shown in the example. There is no limit to the number of Orgs / environments that can be created. This example can be adapted to suit your unique deployment requirements.

  • For more complex applications, each environment’s GVC / workload should be configured with its own: