Using the feature branch workflow

Use the feature branch workflow to safely and efficiently move new code from an isolated development environment through initial testing and validation and then into your organization's staging, review, and promotion to production process. This guide provides an outline of this core Continuous Delivery for PE workflow; adapt the steps as needed to meet your team's requirements and best practices.

Part 1: Develop and test code changes

The first phase of the feature branch workflow focuses on writing new code in a feature branch, then testing and validating that code.

Before you begin

Create a regex branch pipeline for the control repo or module repo you’re working on. This pipeline can be as simple or complex as you need it to be, but at minimum it must:

Use commits as a pipeline trigger
Contain a deployment using the feature branch deployment policy

We also strongly advise including jobs that perform syntax validation tests in your regex branch pipeline before the deployment stage. Here’s a sample regex branch pipeline as it appears in the web UI:
Regex branch pipeline with two jobs and a deployment using the feature branch deployment policy

Regex branch pipeline with two jobs and a deployment using the feature branch deployment policy

Here’s what the pipeline above looks like when expressed as code:

pipelines:
  /feature_.*/:
    triggers:
    - "PULL_REQUEST"
    - "COMMIT"
    stages:
    - name: "Lint/Parser validation"
      steps:
      - type: "JOB"
        name: "control-repo-puppetfile-syntax-validate"
        concurrent_compilations: 0
        all_deployments: false
      - type: "JOB"
        name: "control-repo-template-syntax-validate"
        concurrent_compilations: 0
        all_deployments: false
      auto_promote: "all_succeeded"
    - name: "Deploy feature environment"
      steps:
      - type: "DEPLOYMENT"
        name: "Feature branch deployment on cdpe-delivery"
        policy:
          name: "cd4pe_deployments::feature_branch"
        concurrent_compilations: 0
        all_deployments: false
        pe_server: "cdpe-delivery"
      auto_promote: false

In your source control system, navigate to the control repo or module repo you want to update.
Create a feature branch. Make a new branch based on the master branch and name it feature_<BRANCHNAME>, substituting a relevant ticket number, fix description, or feature name for <BRANCHNAME>.

Continuous Delivery for PE automatically recognizes feature branches by their names. By default, the software uses feature_.* as the regular expression that triggers regex pipelines, so it’s important to give your feature branch the feature_ prefix.
Tip: If you need to use a different naming convention for your control repo or module repo’s feature branches, you can change the regular expression in the web UI by clicking Manage pipelines.
On your feature branch, make your code changes.
When your work is complete, commit the changes to the feature branch and push the commit to your source control system. This commit triggers your regex branch pipeline. You can monitor the pipeline's progress in the web UI.

When your pipeline is triggered, Continuous Delivery for PE runs any jobs and impact analysis tasks you've set up. If the promotion conditions set in your pipeline are met (if all the jobs succeed, for example), the pipeline starts a feature branch deployment.

How does a feature branch deployment work? Using Code Manager, Continuous Delivery for PE deploys the code in your commit to a Puppet environment with the same name as the branch that triggered the pipeline. If an environment with this name doesn't already exist (as is most likely the case), Continuous Delivery for PE creates it.
When the feature branch deployment is complete, run Puppet on a test node, specifying the special environment created by Continuous Delivery for PE. This Puppet run will apply your changes to the test node so you can review them. You can run Puppet from the command line or from the PE console:
1. From the command line: Run puppet job run --nodes <TEST_NODE_NAME> --environment <feature_BRANCHNAME>
  
  Tip: For more on the puppet job run command, see Running Puppet on demand from the CLI.
2. From the PE console: Navigate to the Run Puppet page and create a job with the following settings:
  - Job description: Enter a description for your test run
  - Environment: Select Select an environment for nodes to run in and choose the environment that matches your feature branch name
  - Schedule: Now
  - Run Mode: Leave these options unchecked
  - Inventory: Select Node list and add the name of your test node
  Click Run job.
When the Puppet run is complete, navigate to your test node and review your changes. If further work is needed, repeat steps 3 through 5 until your code is ready for deployment to production.
When you're satisfied with your new code, move on to Part 2: Review and merge to production.

Part 2: Review and merge to production

In the second phase of the feature branch workflow, the new code is reviewed and merged to the master branch, then deployed to production. Along the way, Continuous Delivery for PE provides checks and safeguards to ensure new code is only sent to production nodes when it has been fully vetted.

Before you begin

Make sure your master branch pipeline uses pull requests as a pipeline trigger and includes a PR gate.

In your source control system, create a pull request from your feature_<BRANCHNAME> branch to the master branch.

Note: If you're a GitLab user, you might be more familiar with the term "merge request" than "pull request." Although the two terms refer to the same concept and can be used interchangeably, for the sake of simplicity and consistency, the Continuous Delivery for PE web UI and these instructions use the term "pull request" (PR).
The pull request triggers a run of your master branch pipeline, which tests your PR code against the jobs and impact analysis report tasks included in the pipeline before the PR gate. You can monitor the pipeline's progress in the Continuous Delivery for PE web UI.
The success or failure of each stage of the pipeline is also displayed on the pull request's page in your source control system.
The appropriate stakeholders on your team can now review the results of the jobs and impact analysis reports generated by the pipeline. If the PR is approved, merge it into the master branch.

Note: After the PR is merged, you can safely delete the feature_<BRANCHNAME> branch you've been using from your source control system.

Merging the PR (which your version control system views as a commit to the master branch) automatically re-triggers the master branch pipeline. The pipeline starts over from the top, re-running all the jobs and impact analysis tasks and making sure the newly updated master branch code is fully tested and vetted.

Since this pipeline run was triggered by a commit, the pipeline proceeds past the PR gate and performs any tasks included in the pipeline after the PR gate, such as additional jobs or deployment to a staging environment.
Once the code is deployed to a staging environment, perform additional testing by running Puppet against test or staging nodes, specifying the staging environment. The scope of this testing should be determined by your team or company best practices.
When testing is complete and the code changes have been approved, promote the code to the production environment.
In most cases, the master branch pipeline does not auto-promote to a deployment to the production environment. A stakeholder must click Promote in the pipeline to trigger the final stage. This kicks off a deployment to the production environment.

However, if the production environment is a protected environment, the deployment requires review and approval from a member of a designated approval group before it can proceed. The deployment remains in a pending state until an approval decision is provided.
Note: See Require approval for deployments to protected Puppet environments for more information on setting up approval groups.
Finally, if necessary, run Puppet to apply the new code to the nodes in your production environment. Depending on which deployment policy you've used, a Puppet run might be included in the deployment Continuous Delivery for PE performs. Otherwise, you can trigger Puppet manually, or wait for the next scheduled Puppet run.

Results

When the Puppet run is complete, your code changes are officially deployed to production.