Integrate with your Source Control Provider
Set Up a 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
- ℹ️ NOTE: The cluster-creator PR Automation looks for
- Token: The Personal Access Token to use.
- Click
Create
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 inbootstrap/pr-automation/scm.yaml
, you'll simply need to uncomment it. It should look like this:
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.
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
ButtonFill 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
- Provider Type: The SCM Provider Hosting Git Repositories
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: