Integrate with source control

Integrate your source control system with Continuous Delivery for Puppet Enterprise (PE) by following the instructions for your source control provider.

Status notification prefixes for source control

Once you've integrated your Continuous Delivery for PE installation with your source control provider, Continuous Delivery for PE sends information about the outcome of each stage of each pipeline run to your source control provider.

When reporting to your source control provider, Continuous Delivery for PE uses the following default format to label each pipeline stage: cd-pe/stage-<pipeline stage number>

This labeling system is adequate if you connect a control repo or module repo to one (and only one) workspace. But if you connect multiple workspaces to a certain control repo or module repo, your source control system might receive identical notifications from multiple workspaces about multiple pipelines. The source control system can't differentiate between these identical notifications when performing automated testing.

To prevent this issue, you can add a status notification prefix to all communications Continuous Delivery for PE sends from your workspace to your source control provider. With the status notification prefix, your source control system can 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 section, click Edit prefix .
  3. Enter a prefix, such as your workspace's name. Click Save.

After saving your prefix, the example code updates to show the prefixed pipeline status labels that this workspace sends to your source control provider.

Integrate with Azure DevOps Cloud Services

Continuous Delivery for Puppet Enterprise (PE) works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. You must create an Azure DevOps Services OAuth application to integrate your Azure DevOps Services instance with Continuous Delivery for PE and start using these tools.

Before you begin
Important: In order for a control repo in Continuous Delivery for Puppet Enterprise to deploy Puppet code from a Puppet Enterprise (PE) instance, you need to configure Code Manager/r10k in PE to communicate to that control repo. For Azure DevOps Services, the SSH URL configured in Code Manager/r10k needs to include the Git SSH username. For example: ssh://git@<YOUR.ADO.SERVER.COM>:puppet/control.git.
An administrator on your team must create an Azure DevOps Services OAuth application for Continuous Delivery for PE.
  1. Sign into Continuous Delivery for PE as the root user, and click Settings > Integrations. The authorization callback URL required to create your OAuth app is shown in the root console.
  2. Go to https://app.vsaex.visualstudio.com/app/register.
  3. 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 Continuous Delivery for PE root console.
  7. In the Authorized scopes section, select Code (read and write).
  8. Click Create Application. When you are redirected to the page showing the new application's setting, stay on this page.
    Important: Don't close this page. You 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 you have an Azure DevOps Services OAuth application for your organization, each workspace must be authenticated with the application in order to integrate your Continuous Delivery for PE instance with Azure DevOps Services. To do this, you must grant code read and write permissions and add a public SSH key, which allows 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. Make sure these users can force push to the relevant control repos and module repos.

Azure DevOps Services only supports cloning over SSH. HTTP(S) cloning is not supported. You must enable SSL on Continuous Delivery for PE to use Azure DevOps Services.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select Azure DevOps from the Source menu.
  3. Click Add credentials to give Continuous Delivery for PE permission to read and write code to your Azure DevOps Services account.
    You are redirected to a Microsoft page.
  4. Click Accept.
    You are redirected back to the Source control page.
  5. In the Continuous Delivery for PE web UI, click SSH key.
  6. Click Show to display your public SSH key, and click Copy.
  7. In the Azure DevOps Services web UI, open the user menu, click Security, and then click SSH public keys.
  8. Click Add and paste your public SSH key into the Key Data field.
  9. Add a description and click Save.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with Azure DevOps Server on prem

Continuous Delivery for Puppet Enterprise (PE) works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. Integrate your Azure DevOps Server instance with Continuous Delivery for PE to start using these tools.

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. Make sure these users can force push to the relevant control repos and module repos.

Azure DevOps Services only supports cloning over SSH. HTTP(S) cloning is not supported.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select Azure DevOps from the Source menu.
  3. Select Connect to Azure DevOps on prem.
  4. In the Host field, enter the public IP or DNS for your Azure DevOps instance.
  5. Create a token allowing Continuous Delivery for PE to access your Azure DevOps instance. In the Azure DevOps Server web UI:
    1. From the View your profile menu, click Security.
    2. From Personal access tokens, click New Token
    3. Enter a token name.
    4. Set Organization to All accessible organizations.
    5. Select as long of a lifetime as your security policy allows.
    6. Select Full Scope.
    7. Click Generate token.
    8. Copy the personal access token created by Azure DevOps.
  6. In the Continuous Delivery for PE web UI, enter the Azure DevOps Server token you just created in the Token field.
  7. Based on your Azure DevOps Server configuration, select either This instance uses a standard CA certificate, or This instance uses a custom CA certificate. If you are using a custom certificate, paste the full certificate in the Custom CA certificate field.
  8. Click Add credentials.
  9. In the Continuous Delivery for PE web UI, click SSH key.
  10. Click Show to display your public SSH key and click Copy.
  11. In the Azure DevOps Services web UI, open the user menu, click Security, and then click SSH public keys.
  12. Click Add and paste your public SSH key into the Key Data field.
  13. Add a description and click Save.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with Bitbucket Cloud

Continuous Delivery for Puppet Enterprise (PE) works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. You must create a Bitbucket Cloud OAuth application 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, and click Settings > Integrations.
  2. In your organization's Bitbucket Cloud account, create an OAuth consumer. Instructions to Create a consumer are in the Bitbucket Cloud documentation. The authorization callback URL required to create your OAuth consumer is shown in the root console.
  3. Give the OAuth consumer these permissions:
    Category Permissions
    Account Email, Read
    Workspace membership Read
    Repositories Read, Write
    Pull requests Read, Write
    Webhooks Read and write
  4. After creating the OAuth application, 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 you have a Bitbucket Cloud OAuth application for your organization, each workspace must be authenticated with the application in order to integrate your 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. Make sure these users have write access and the ability to rewrite history on the relevant control repos and module repos.

Bitbucket Cloud only supports cloning over HTTP(S). Bitbucket Cloud does not support SSH cloning, and it does not support pull requests from forks. Jobs run on pull requests from forks will fail.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select Bitbucket Cloud from the Source menu.
  3. Click Add credentials to give Continuous Delivery for PE permission to read and write code to your Bitbucket Cloud account.
  4. Click Add credentials.
    You're redirected to Bitbucket Cloud to authorize the OAuth application set up by your workplace administrator.
  5. Click Grant access to allow Continuous Delivery for PE to access your Bitbucket Cloud account.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with Bitbucket Server

Continuous Delivery for Puppet Enterprise (PE) works 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 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. Create an exemption rule to ensure these users can force push to the relevant control repos and module repos.

Bitbucket Server only supports cloning over SSH. Bitbucket Server does not support HTTP(S) cloning, and it does not support pull requests from forks. Jobs run on pull requests from forks will fail.

Continuous Delivery for PE supports Bitbucket Server versions 5.0 and newer.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select Bitbucket Server from the Source menu.
  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 want 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. If your Bitbucket Server's SSH base URL is different from the host URL, enter the SSH base 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. Enter the SSH user for clones if it is something other than git.
  8. Click Add credentials.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with GitHub

Continuous Delivery for Puppet Enterprise (PE) works with your existing source control system to track changes to your Puppet code and manage code deployments to your nodes. You must create a GitHub OAuth application 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, and click Settings > Integrations.
  2. In your organization's GitHub account, create an OAuth application. Instructions for Creating an OAuth App are in the GitHub documentation. In the Homepage URL field, enter the base URL for your Continuous Delivery for PE instance (http://<CD4PE-HOST-SERVER>). The Authorization callback URL is shown in the Continuous Delivery for PE root console.
  3. After creating your OAuth application, note the Client ID and Client Secret shown on the application's page in the GitHub UI.
  4. 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 you have a GitHub OAuth application for your organization, each workspace must be authenticated with the application in order to integrate your Continuous Delivery for PE instance with GitHub.

Important:

If your organization uses protected branches on GitHub, make sure you allow force pushing to protected branches, or that you use the GitHub Administrator user to connect control repos or module repos to Continuous Delivery for PE.

GitHub only supports cloning over HTTP(S). SSH cloning is not supported.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select GitHub from the Source menu.
  3. Click Add credentials.
    You're redirected to GitHub to authorize the OAuth application set up by your team's administrator.
  4. Click Grant access to allow Continuous Delivery for PE to access your GitHub account.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with GitHub Enterprise

Continuous Delivery for Puppet Enterprise (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 to start using these tools.

Important:

If your organization uses protected branches on GitHub Enterprise, make sure you allow force pushing to protected branches, or that you use the GitHub Enterprise Administrator user to connect control repos or module repos to Continuous Delivery for PE.

GitHub Enterprise only supports cloning over HTTP(S). SSH cloning is not supported.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select GitHub Enterprise from the Source menu.
  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 View your profile and more (profile photo icon) and then click Settings.
    2. Click Developer settings > Personal access tokens > 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 full certificate in the Custom CA certificate field.
  7. Click Add credentials.
What to do next
After integrating with your source control provider, Add repositories.

Integrate with GitLab

Continuous Delivery for Puppet Enterprise (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 to start using these tools.

Important: If your organization uses protected branches on GitLab, make sure 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.

GitLab supports cloning over both SSH and HTTP(S). You set the cloning protocol for each Continuous Delivery for PE workspace.

  1. In the Continuous Delivery for PE web UI, click Add new source.
  2. Select GitLab from the Source menu.
  3. In the Host field, enter the resolvable HTTP or HTTPS URL for your GitLab instance, such as http://gitlab.example.com.
    The URL must be formatted as a resolvable HTTP or HTTPS address even if you are using an SSH connection.
  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 clones 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 full certificate into the Custom CA certificate field.
  7. Click Add credentials.
What to do next
After integrating with your source control provider, Add repositories.

Update webhooks

You must update the webhooks that connect Continuous Delivery for PE to your source control system if you change the location of your Continuous Delivery for Puppet Enterprise (PE) installation, change the hostname when migrating your Puppet Application Manager (PAM) installation, or change the backend service endpoint.

  1. In the Continuous Delivery for PE root console, click Settings > Webhooks.
  2. Enter the backend service endpoint:
    • If you changed your Continuous Delivery for PE installation location, enter the backend service endpoint for your previous Continuous Delivery for PE installation.
    • If you changed the hostname when migrating your PAM installation, run kubectl describe pod <CD4PE_POD> |grep BACKEND to get the backend service endpoint.
  3. Click Update webhooks.
Results
Continuous Delivery for PE updates all webhooks according to your configuration.