Integrating with your Git Provider

Integrating with a Git provider such as GitHub, or GitLab

Pipekit integrates with Git providers such as GitHub and GitLab to provide a seamless GitOps experience for your users. This guide will walk you through the steps to integrate them with Pipekit.

These examples assume you are self-hosting Pipekit on the subdomain pipekit.example.com. Replace this with your actual domain.

GitHub

1. Go to https://github.com/organizations/example/settings/apps replacing example with your github organization.

2. Click on "New GitHub App"

3. Fill in the details:

   • GitHub App name: [Choose a unique App name]

   • Homepage URL: https://pipekit.example.com

   • Callback URL: https://pipekit.example.com/accounts/github

   • Add a second Callback URL: https://pipekit.example.com/api/id/v1/sso/github/callback

     • Tick "Request user authorization (OAuth) during installation"

   • Webhook URL: https://pipekit.example.com/api/events-handler/v1/events/github

   • Repository permissions:

     • Administration: Read & Write

     • Checks: Read & Write

     • Contents: Read & Write

     • Deployments: Read & Write

     • Pull requests: Read & Write

     • Webhooks: Read & Write

   • Subscribe to events:

     • Create

     • Pull request

     • Push

     • Repository

4. Click "Create GitHub App"

5. Generate a private key and download it as prompted.

6. Note down the App name, App ID, Client ID and generate a new Client Secret.

7. Populate the Helm Chart Values with the collected information and install Pipekit.

8. Install Pipekit and log in with the Break Glass User account.

9. Create an organization and cluster. Go back to the organization and click settings and then press the GitHub button to authenticate the Org with GitHub.

10. Install the Github App into the repo(s) you wish Pipekit to interact with.

GitLab

1. Enable gitProviders.gitlab.enabled in the Helm Chart Values to configure Pipekit to use GitLab.

2. Go to your Organization settings in Pipekit and click on "GitLab" to authenticate your Organization with GitLab.

3. Enter a PAT that has the following scopes:

• api

• read_user

• read_repository

1. Choose a random string for the gitProviders.gitlab.webhookSecret and apply it to the Helm chart values. This will be used to automatically create a webhook in GitLab to post events to Pipekit.

BitBucket Data Center

1. Enable gitProviders.bitbucket.enabled in the Helm Chart Values to configure Pipekit to use BitBucket.

2. Ensure a secure gitProviders.bitbucket.webhookSecret is set. This is used to automatically create webhooks in BitBucket to notify Pipekit.

3. Go to your Organization settings in Pipekit and click on "BitBucket Data Center" to authenticate your Organization with GitLab.

4. Enter your HTTP access token that has the following rights:

• PROJECT_READ

• REPO_ADMIN

Azure DevOps

Pipekit supports both Azure DevOps Services (cloud, dev.azure.com/{org}). One Pipekit account corresponds to one Azure DevOps organization; projects within that organization are surfaced in Pipekit's repo picker grouped under their project name.

Helm chart configuration

1. Enable gitProviders.azureDevOps.enabled in the Helm Chart Values.

2. Set gitProviders.azureDevOps.webhookBasicAuthUser and gitProviders.azureDevOps.webhookBasicAuthPass to a username/password pair of your choice. Pipekit configures every Service Hook subscription it creates to deliver with these Basic auth credentials and verifies them on each incoming delivery.

Authentication: Personal Access Token (PAT)

1. In Azure DevOps, create a PAT with the following scopes:

   • Code: Read, Write, & Status

   • Project & Team: Read

2. The PAT owner must be a Project Administrator — or have the Edit subscriptions project permission — so Pipekit can create Service Hook subscriptions on the repo. There is no longer a standalone "Service Hooks" PAT scope; Microsoft has made vso.hooks* private, so this project-level permission is the gating mechanism.

3. In Pipekit, connect the account by submitting the organization URL (https://dev.azure.com/{org} for Services, your server URL for Server) and the PAT.

Service Hooks

Pipekit creates three Service Hook subscriptions per repo on first attach: git.push, git.pullrequest.created, and git.pullrequest.updated. Pull request updates are filtered to source-branch push notifications. Branch creation, tag creation, and tag updates are all carried by git.push. Cleanup on detach removes all three. There is no global Service Hook subscription — every repo manages its own.

Webhook delivery URL

https://<your-pipekit-host>/api/events-handler/v1/events/azure-devops

Next Steps

If you haven't done so, continue to create a cluster and then create a pipe to start using Pipekit.

You have now successfully integrated your git provider with your Organization. This will allow you to use a number of Pipekit's features:

• Create Pipes that run Workflows stored in your Git repositories.

• Create and manage Pipes that use Run Conditions to trigger Workflows on GitHub events.

• The WorkflowTemplates features of Pipekit.

• Manage Workflow Priorities

• Manage Namespace Permissions through GitOps.

Populating the repository cache in Pipekit

If you enable a Git Provider, a Kubernetes cron job will be installed into the cluster that will run every night to query your git provider for an updated list of Pipekit-accessible repositories and store them in the Pipekit database. This is done to ensure that Pipekit has the most up-to-date list of repositories to work with and prevents excessive API calls to your git provider.