Constructing pipelines in the web UI

Build and manage pipelines for your control repo or module in the Continuous Delivery for Puppet Enterprise (PE) web UI using the tools built into the interface. The steps on this page walk through the process of setting up and using a basic pipeline.

Create a pipeline

Set up a pipeline to enable automatic testing of new code by adding stages and jobs in the Continuous Delivery for Puppet Enterprise (PE) web UI.

Every pipeline must have at least one stage.
  1. In the Continuous Delivery for PE web UI, click Control repos, and click the name of the control repo you want to create a pipeline for.

    Continuous Delivery for PE automatically creates a pipeline for the branch you selected when you set up the control repo (the main branch). The branch name is at the top of the Pipelines section. You can set up pipelines for other branches in the repo if you want to automatically test code changes that Continuous Delivery for PE makes on your behalf. To create a pipeline for a different branch, click Add pipeline . If you don't want a pipeline, click Delete pipeline .

    You can also go to Modules to create pipelines for module repos.

  2. Click Add stage and enter a Stage name.
  3. Select Jobs from the Select item dropdown menu, select a job from the Select jobs list, click Add stage to add the job to the pipeline, and click Done.
  4. If you only need to run a single test on new code, the pipeline can be as simple as one stage with one job. If you want to add additional tests, you can either add them to the same stage or create another stage to contain other jobs.
    1. To add another job to the same stage, click More actions , select Add item to stage, and repeat step 3.
    2. To add another stage to your pipeline, repeat steps 2 and 3.
    Note: All steps (jobs, deployments, and so on) in a stage run concurrently. If you need certain steps to occur after others, use stages to separate them.
    To reorganize, delete, or rename stages, click More actions .
  5. Once you have a pipeline with two stages, an promotion step is automatically added between the stages. Select Auto promote and choose a promotion condition from the dropdown menu. The promotion condition tells the pipeline how to decide if it can continue to the next stage. The promotion conditions, from most to least restrictive, are:
    • All succeeded: The pipeline continues to the next stage only if all tasks in the current stage finish with "succeeded" or "done" status.
    • All completed: The pipeline continues to the next stage if all tasks in the current stage finish with "succeeded," "done," or "failed" status. The pipeline stops if any task in the current stage was canceled.
    • Any succeeded: The pipeline continues to the next stage if at least one task in the current stage finishes with a "succeeded" or "done" status.
    • Any completed: The pipeline continues to the next stage if at least one task in the current stage finishes with a "succeeded," "done," or "failed" status. The pipeline stops if all tasks in the current stage were canceled.
  6. Optional: If you want the pipeline to run on both commits and pull requests, click Manage pipelines to enable pull requests as a pipeline trigger.
Results
This pipeline runs on one branch in one control/module repo.

Create a regex branch pipeline

Most pipelines are linked to a single branch in your control repo or module repo. A regex branch pipeline can recognize and act on changes to any branch in your control/module repo that has a name matching the regular expression you set.

A regex branch pipeline lets you use a single pipeline for all feature branches you and your team create (and destroy) in the process of developing new code. Regex branch pipelines use naming conventions to detect branches to run the pipeline against. You define the naming convention when you create the pipeline. When you commit to (or create a pull request for) a feature branch that has a name matching the naming convention, Continuous Delivery for Puppet Enterprise (PE) automatically runs the regex pipeline against that branch.
  1. In the Continuous Delivery for PE web UI, click Control Repos or Modules and select the control repo or module repo where you want to create the regex pipeline.
  2. Click Add pipeline .
  3. In the Add pipeline window, select Branch regex.
    Each control repo or module repo can have only one regex branch pipeline. If the Branch regex option is not available, then a regex branch pipeline already exists for this repo.
  4. In the Configure regex field, enter the naming convention, as a regular expression, that you want the regex branch pipeline to use to detect feature branches (and initiate pipeline runs against those branches).
    The default regular expression is feature_.*. If you use the default regex, your feature branch names must follow the feature_<BRANCHNAME> naming convention. For example, a branch named feature_1234 triggers the pipeline, but a branch named 1234_feature does not.
    Tip: All team members must follow this naming convention when creating feature branches if they want their changes to trigger the regex branch pipeline. We strongly recommend using the default regular expression or one that's similarly simple and memorable.
  5. Click Add pipeline. The regex branch pipeline is created.
  6. Click Manage pipelines to select whether the regex branch pipeline is triggered by commits, pull requests, or both.
  7. Build out your pipeline by adding stages, jobs, impact analysis tasks, deployments, and promotion conditions.
Results
This pipeline runs on any branch that matches the defined naming convention in the associated control/module repo.

Test code automatically with a pipeline

After creating a pipeline for your control repo's main branch, when you commit new code to the main branch, the pipeline tests the code (by running the jobs you selected) and reports any errors or failures.

Before you begin
Create a pipeline
  1. To trigger the pipeline, make a trivial change, such as adding a line to a README file, in your control repo's main branch, and commit your change.
  2. In the Continuous Delivery for PE web UI, click Control repos and click the name of the control repo you just committed to.
  3. The Events area shows the push event initiated by your commit and an entry for each job in the pipeline. Job statuses appear here and update to report success or failure when a job run is complete.
    Each event summary includes a link to the commit in the control repo, and each job event includes a job number. Click the job number to go to the Job details page, where you can see the job's log for its run and review error messages.

Test pull requests automatically

If you enable pull requests as a pipeline trigger, your pipeline automatically tests new code when a pull request (PR) is opened against the relevant branch. Add PR gates to pipelines to test new code but stops the pipeline before it can advance to further tests or deployment.

Before you begin
Create a pipeline that has pull requests as a pipeline trigger.
A PR gate stops the pipeline at a certain point if the pipeline was triggered by a pull request. With a PR gate, you can automatically run acceptance tests on new pull requests while manually managing additional testing or deployment based on the results of the initial automated tests.
GitLab users: Pull request is another term for merge request. For the sake of simplicity and consistency, the term pull request (PR) is used in the Continuous Delivery for PE web UI and documentation.
  1. To add a PR gate to your pipeline, navigate to the pipeline in the web UI.
  2. In your pipeline's first stage, click More actions , select Add item to stage, and select Pull request gate.
  3. Click Add PR gate, and click Done if the PR gate was added successfully.
    Important: A pipeline can only have one PR gate. To move a PR gate, delete the existing gate and create a new one in the desired stage.
  4. To test PR gate, switch to a branch in your control repo other than the main branch. Make a trivial change (such as adding a new line to the README file) in your control repo, commit your change, and open a pull request against the main branch for this commit.
    Remember: You must make the pull request against the branch associated with the pipeline.
  5. In the Continuous Delivery for PE web UI, click Control repos, then click the name of the control repo you just created the pull request against.
  6. The Events area shows the pull request event initiated by your commit and entries for jobs in your pipeline before the PR gate. Notice that jobs in pipeline stages beyond the PR gate have not been triggered.

Deploy code automatically with a pipeline

You can use a control repo pipeline to automatically deploy new code to a specified set of nodes every time a commit is made.

Before you begin
Create a pipeline
  1. In the Continuous Delivery for PE web UI, click Control repos, and click the name of the control repo you've created a pipeline for.
  2. Click Add stage.
  3. In the Add new stage window, select Deployment from the Select item dropdown menu.
  4. Select your Puppet Enterprise instance and the node group you want to deploy changes to when this pipeline runs.
  5. Select a deployment policy.
    You can use one of the Built-in deployment policies or create Custom deployment policies.
    Tip: If this is your first pipeline and you're just testing the process, select Direct deployment policy.
  6. Optional: Set termination conditions for this pipeline's deployments, and choose the number of nodes that can fail before the deployment is stopped.
  7. Click Add Stage and click Done. Your new stage, containing the deployment details, is added to the pipeline.
  8. To test the deployment, make a trivial change (such as adding a new line to the README file) on the main branch of your control repo and commit your change.
  9. In the Continuous Delivery for PE web UI, click Control repos and click the name of the control repo you just committed to.
  10. The Events area shows the push event initiated by your commit and a deployment event. The deployment status appears here and updates to report success or failure when the deployment is complete.
    Each event summary includes a link to the commit in the control repo, and deployment events include a deployment number. Click the deployment number to go to the deployment details page.
  11. You can run the same deployment again from the web UI by retriggering the webhook. In the Events area, locate the push event you want to rerun and click View webhook.
    The webhook's request and response data is shown in the Webhook data pane. This can be useful for troubleshooting.
  12. Click Redeliver webhook and confirm your action. The Events area shows the new event triggered by the redelivery of the webhook.
    If you made changes to your pipeline since the last time this webhook was delivered, the redelivered webhook follows the current pipeline's sequence and rules.