Get startedSign in

Integrate with your Source Control Provider

Setting up an SCM Connection in Plural to integrate with Github, GitLab, or BitBucket

Overview

Plural has the ability to spawn pull requests, post review comments, and other functionality to integrate with your standard SCM (Source Control Management) workflows. The most impactful of these is the PR Automation api, which allows you to spawn templated pull requests to do common tasks like:

  • provision new clusters
  • drive deployment pipelines
  • in conjunction with Stacks, provision associated kubernetes or cloud infrastructure (databases, IAM, networks)

To get this working you'll first need to give your Plural Console scoped access tokens to your SCM.

Prerequisites

Some things you'll need to run this tutorial:

  • Plural Console admin Permissions
  • SCM Provider Personal Access Token
  • SCM Provider Organization admin Permissions
    • This is only required when creating the webhook
    • The workload cluster can still be created without the SCM webhook

Create a New SCM Connection

Creating an SCM Connection is easiest just using our UI. You can then reference that created resource via k8s CRD to drive other workflows. Step by step, you'll want to:

  • Navigate to https://{your-console-domain}/pr/scm
  • Click the Create Connection Button at the Top Right
  • Fil in the Required Fields
    • Provider Type: The SCM Provider Hosting Git Repositories
    • Name: Reference Name for the Provider
      • ℹ️ NOTE: The cluster-creator PR Automation looks for github by default, but is arbitrary and can be changed
    • Token: The Personal Access Token to use.
  • Click Create
Create SCM Connection Modal
Info:

For github tokens, the minimal permissions needed will be repo permissions. You can also use a Github App if you'd like the token to not be scoped to a specific user. For Github Apps, recommended permisions are read/write for Code, Pull Requests and Workflows (so you can write PR Automations for Github Actions, but technically optional).

Create an ScmConnection CRD Instance

Once the connection is created in the UI we can reference it with a CRD instance

  • ❕ Ensure the Name Provided in the UI matches the spec.name in the CRD Exactly
  • An ScmConnection yaml template for GitHub exists in bootstrap/pr-automation/scm.yaml, you'll simply need to uncomment it. It should look like this:
yaml
apiVersion: deployments.plural.sh/v1alpha1
kind: ScmConnection
metadata:
  name: github
spec:
  name: github
  type: GITHUB

You should now be able to commit and push, and Plural will sync it in (or create a PR to merge it into your main branch):

git commit -m "setup a Plural scm connection"
git push
Info:

plural up by default creates an apps service syncing all subfolders of the bootstrap folder in the repo it creates. Since we created this file in bootstrap/pr-automation that means that root service-of-services will sync it appropriately and we just need to git push to apply the change.

You can also check this service in the console (CD > Services > apps) to see if the CRD was deployed successfully. You should see 10/10 components in "Running" state.

Add an SCM Provider Webhook

Plural listens to incoming PRs to drive a couple of workflows:

  • labeling the status of spawned PRs generated by PR Automations. Without a webhook, they'll just remain OPEN perpetually.
  • listening for PRs linked to stacks so we can generate plan runs for terraform/pulumi/etc, and post-back the results as a PR comment.

If you want that functionality, simply add a webhook in your SCM by doing the following:

  • Navigate to https://{your-console-domain}/pr/scm-webhooks

  • Click the Create Webhook Button

  • Fill the Required Fields

    • Provider Type: The SCM Provider Hosting Git Repositories
      • This may be obvious, but you need to select the same provider as the console webhook
    • Owner: The Organization or Group Within the SCM Provider
    • Secret: The Webhook Secret to Share, you can generate a cryptographically secure one with plural crypto random

  • Click Create

    • Copy the Webhook URL and note the secret to use within the SCM Provider Webhook

  • Create the Webhook with the SCM Provider

You can create this webhook at whatever scope you'd prefer. Depending on the scope, the permissions needed will likely vary. A simple place to start is just creating a webhook scoped to your plural up repository.

Here's some docs to help you work through the webhook creation process for a lot of SCM providers:

Edit on Github