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.
- Use commits as a pipeline trigger
- Contain a deployment using the feature branch deployment policy
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 main 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:
From the command line: Run
puppet job run --nodes <TEST_NODE_NAME> --environment <feature_BRANCHNAME>Tip: For more on the
puppet job runcommand, see Running Puppet on demand from the CLI.
From the PE console: Navigate to the Run
Puppet page and create a job with the following
- 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.
- From the command line: Run
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 main 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.
In your source control system, create a pull request from your
feature_<BRANCHNAME>branch to the main 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 main 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 main 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 main branch) automatically re-triggers the main branch pipeline. The pipeline starts over from the top, re-running all the jobs and impact analysis tasks and making sure the newly updated main 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 main 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.