Integrate with source control

Integrate your source control system with Continuous Delivery for Puppet Enterprise (PE) by following the appropriate set of instructions on this page.

Status notification prefixes for source control

Once integration between your Continuous Delivery for PE installation and your source control provider is complete, Continuous Delivery for PE sends information about the outcome of each stage of each pipeline run to your source control provider.

By default, Continuous Delivery for PE labels each pipeline stage as follows when reporting to your source control provider: 
cd-pe/stage-<pipeline stage number>

This labeling system works just fine if you connect a control repo or module repo to one (and only one) workspace. But if more than one workspace is connected to a certain control repo or module repo, your source control system might receive identical notifications from multiple workspaces about multiple pipelines, and be unable to differentiate between them when performing automated testing.

To prevent this issue, you have the option of adding a status notification prefix to all the communications Continuous Delivery for PE sends from your workspace to your source control provider. By adding a status notification prefix, you ensure that your source control system is able to differentiate between and accurately act on pipeline status notifications coming from multiple workspaces to the same control repo or module repo.

To add a status notification prefix:
  1. In the Continuous Delivery for PE web UI, click Settings > Source control.
  2. In the Status notification prefix area of the page, click Edit prefix .
  3. Enter your chosen prefix. The name of your workspace is a good option. Click Save.

When you save your prefix, the example code updates to show prefixed pipeline status labels as they will be sent to your source control provider from this workspace.

Integrate with Azure DevOps Services

Continuous Delivery for PE works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Create an Azure DevOps Services OAuth application in order to integrate your Azure DevOps Services instance with Continuous Delivery for PE and start using these tools.

Before you begin
An administrator on your team must create an Azure DevOps Services OAuth application for Continuous Delivery for PE.
Note: These instructions apply only to the Azure DevOps cloud offering. The hosted version, Azure DevOps Server, is not compatible with Continuous Delivery for PE.

  1. Sign into Continuous Delivery for PE as the root user.

  2. Click Settings, then click Integrations.

    Tip: The authorization callback URL required to create your OAuth app is shown in the root console.

  3. Go to https://app.vsaex.visualstudio.com/app/register. Enter your company name.

  4. In the Application Information section, enter a name for your OAuth application, such as CD for PE.

  5. In the Application website field, enter the base URL for your Continuous Delivery for PE instance.

  6. In the Authorization callback URL field, enter the authorization callback URL printed in the root console.

  7. In the Authorized scopes section, select Code (read and write).

  8. Click Create Application. Your new application is created, and a new page showing the application's settings is displayed.
    Important: Leave this page open. You'll need the application settings information in the next step.

  9. Return to the Continuous Delivery for PE root console. On the Integrations page, enter the application ID and client secret for your Azure DevOps Services OAuth application and click Add.

Once an Azure DevOps Services OAuth application is established for your organization, each workspace must be authenticated with the application in order to integrate the Continuous Delivery for PE instance with Azure DevOps Services. This process involves granting code read and write permissions and adding a public SSH key, which enables cloning of modules and control repos during automated tasks.
Important: If your organization uses Azure DevOps Services branch permissions to limit user access to Git branches, review the permissions granted to Continuous Delivery for PE users and ensure that these users can force push to the relevant control repos and module repos.
Important: Azure DevOps Services only supports cloning over SSH. HTTP(S) cloning is not supported. To use Azure DevOps Services, SSL must be enabled on Continuous Delivery for PE.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, then click Azure DevOps.
  3. Click Add credentials to give Continuous Delivery for PE code read and write permissions for your Azure DevOps Services account. You are directed to a Microsoft page.
  4. Click Accept. You are directed back to the Source control page.
  5. Next, add the SSH key. Still in the Continuous Delivery for PE web UI, click SSH key.
  6. Click Show to display your public SSH key. Click Copy.
  7. In the Azure DevOps Services web UI, open the user menu and click Security, then click SSH public keys.
  8. Click Add and paste your public SSH key into the Key Data field. Add a description and click Save.

Integrate with Bitbucket Cloud

Continuous Delivery for PE works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Create a Bitbucket Cloud OAuth application in order to integrate your Bitbucket Cloud instance with Continuous Delivery for PE and start using these tools.

Before you begin
An administrator on your team must create a Bitbucket Cloud OAuth consumer for Continuous Delivery for PE.

  1. Sign into Continuous Delivery for PE as the root user.

  2. Click Settings, then click Integrations.

    Tip: The authorization callback URL required to create your OAuth consumer is shown in the root console.
  3. In your organization's Bitbucket Cloud account, create an OAuth consumer. See Create a consumer in the Bitbucket Cloud documentation for instructions.
    Give the OAuth consumer the following permissions:
    Category Permissions
    Account Email, Read
    Team membership Read
    Repositories Read, Write
    Pull requests Read, Write
    Webhooks Read and write
  4. When your OAuth application is created, note the key and secret shown on the OAuth settings page in the Bitbucket Cloud web UI.

  5. Return to the Continuous Delivery for PE root console. On the Integrations page, enter the client ID (key) and client secret for your Bitbucket Cloud OAuth consumer and click Add.

Once a Bitbucket Cloud OAuth application is established for your organization, each workspace must be authenticated with the application in order to integrate the Continuous Delivery for PE instance with Bitbucket Cloud.
Important: If your organization uses Bitbucket Cloud branch permissions to limit user access to Git branches, review the permissions granted to Continuous Delivery for PE users and ensure that these users have write access and the ability to rewrite history on the relevant control repos and module repos.
Note: Bitbucket Cloud only supports cloning over HTTP(S). SSH cloning is not supported.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, then click Bitbucket Cloud.
  3. Click Add credentials to give Continuous Delivery for PE code read and write permissions for your Bitbucket Cloud account.
  4. Click Add credentials.

    At this point you'll be redirected to Bitbucket Cloud to authorize the OAuth application set up by your workspace administrator.

    Give Continuous Delivery for PE the following permissions on your Bitbucket Cloud account:

    • Access organizations, teams, and membership (read-only)

    • Access user email addresses (read-only)

    • Access public and private repositories

  5. Click Authorize application.

Integrate with Bitbucket Server

Continuous Delivery for PEworks with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Integrate your Bitbucket Server instance with Continuous Delivery for PE in order to start using these tools.

Important: If your organization uses Bitbucket Server branch permissions to limit user access to Git branches, review the permissions granted to Continuous Delivery for PE users and create an exemption rule that ensures these users can force push to the relevant control repos and module repos.
Note: Bitbucket Server only supports cloning over SSH. HTTP(S) cloning is not supported.
Note: Continuous Delivery for PE supports Bitbucket Server 5.0 and newer versions.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, then click Bitbucket Server.
  3. In the Bitbucket Server host field, enter the public IP or DNS for your Bitbucket Server instance.
  4. In the Username and Password fields, enter the credentials associated with the account you wish to connect to Continuous Delivery for PE.
  5. In the SSH port field, enter the port number on which your Bitbucket Server listens for SSH requests. To locate this port number:

    1. In the Bitbucket Server web UI, click Administration (the gear icon) and then click Server settings.

    2. Locate the SSH port in the SSH access section of the Server settings page.

  6. Optional: Enter the SSH base URL for your Bitbucket Server if it is different from the host URL. To view your SSH base URL:

    1. In the Bitbucket Server web UI, click Administration (the gear icon) and then click Server settings.

    2. Locate the SSH base URL in the SSH access section of the Server settings page.

  7. Optional: Enter the SSH user for clones if it is something other than "git."
  8. Click Add credentials.

Integrate with GitHub

Continuous Delivery for PE works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Create a GitHub OAuth application in order to integrate your GitHub instance with Continuous Delivery for PE and start using these tools.  

Before you begin

An administrator on your team must create a GitHub OAuth application for Continuous Delivery for PE.

  1. Sign into Continuous Delivery for PE as the root user.

  2. Click Settings, then click Integrations.

  3. In your organization's GitHub account, create an OAuth application. See Creating an OAuth App in the GitHub documentation for instructions.
    Tip: In the Homepage URL field, enter the base URL for your Continuous Delivery for PE instance (http://<CD4PE-HOST-SERVER>:8080). The Authorization callback URL is shown in the Continuous Delivery for PE root console.

  4. Once your OAuth application is created, note the Client ID and Client Secret shown on the application's page in the GitHub UI.

  5. Return to the Continuous Delivery for PE root console. On the Integrations page, enter the client ID and secret for your GitHub OAuth application and click Add.

Once a GitHub OAuth application is established for your organization, each workspace must be authenticated with the application in order to integrate the Continuous Delivery for PE instance with GitHub.
Important: If your organization uses protected branches on GitHub, make sure that force pushing is allowed to protected branches, or that the GitHub Administrator user is used when connecting a control repo or module repo to Continuous Delivery for PE.
Note: GitHub only supports cloning over HTTP(S). SSH cloning is not supported.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, then click GitHub.
  3. Click Add credentials.

    At this point you'll be redirected to GitHub to authorize the OAuth application set up by your team's administrator.

    Give Continuous Delivery for PE the following permissions on your GitHub account:

    • Access organizations, teams, and membership (read-only)

    • Access user email addresses (read-only)

    • Access public and private repositories

  4. Click Authorize application.

Integrate with GitHub Enterprise

Continuous Delivery for PE works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Integrate your GitHub Enterprise instance with Continuous Delivery for PE in order to start using these tools.  

Important: If your organization uses protected branches on GitHub Enterprise, make sure that make sure that force pushing is allowed to protected branches, or that the GitHub Enterprise Administrator user is used when connecting a control repo or module repo to Continuous Delivery for PE.
Note: GitHub Enterprise only supports cloning over HTTP(S), SSH cloning is not supported.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, then click GitHub Enterprise.
  3. In the Host field, enter the public IP or DNS for your GitHub Enterprise instance.
  4. Create a token allowing Continuous Delivery for PE to access your GitHub Enterprise instance.
    1. In the GitHub Enterprise web UI, click your profile photo, then click Settings > Developer settings.
    2. Click Personal access tokens. Click Generate new token.
    3. Enter a token description, such as CD for PE.
    4. Select the repo, read:org, and user:email scopes.
    5. Click Generate token.
    6. Copy the personal access token created by GitHub Enterprise.
  5. In the Continuous Delivery for PE web UI, enter the GitHub Enterprise token in the Token field.
  6. Based on your GitHub Enterprise configuration, select either This instance uses a standard CA certificate or This instance uses a custom CA certificate. If you're using a custom certificate, paste the certificate in full in the Custom CA certificate field.
  7. Click Add credentials.

Integrate with GitLab

Continuous Delivery for PE works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Integrate your GitLab instance with Continuous Delivery for PE in order to start using these tools.

Important: If your organization uses protected branches on GitLab, make sure that the GitLab user account connected to Continuous Delivery for PE is assigned to a GitLab role with “allow” rules that enable the user to push to the protected branch.
Note: GitLab supports cloning over both SSH and HTTP(S). The cloning protocol is set per Continuous Delivery for PE workspace.
  1. In the Continuous Delivery for PE web UI, click Settings.
  2. Click Source control, and then click GitLab.
  3. In the Host field, enter the public IP or DNS for your GitLab instance.
  4. Create a token allowing Continuous Delivery for PE to access your GitLab instance.
    1. In the GitLab web UI, navigate to your user settings and click Access tokens.
    2. Enter a name for the application, such as CD for PE, and set an expiration date for the token.
    3. Select the api and read_user scopes.
    4. Click Create personal access token.
    5. Copy the personal access token created by GitLab.
  5. In the Continuous Delivery for PE web UI, enter the GitLab token in the Token field.
  6. Select whether your workspace will clone GitLab repositories via SSH or HTTP(S).
    1. For SSH:
      • Optional: Add the SSH user's credentials in the SSH user field.
      • Optional: In the SSH port field, specify the port on which your GitLab server listens for SSH requests. The default port number is 22.
    2. For HTTP(S):
      • If you're using a custom certificate, paste the certificate in full into the Custom CA certificate field.
  7. Click Add credentials.