# Integrating with your Git Provider

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](/self-hosting-pipekit/helm-chart.md) with the collected information and install Pipekit.
8. Install Pipekit and log in with [the Break Glass User account](/self-hosting-pipekit/initial-login-and-break-glass-account.md).
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](/self-hosting-pipekit/helm-chart.md) 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

4. 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](/self-hosting-pipekit/helm-chart.md) 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](/self-hosting-pipekit/helm-chart.md).
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](https://learn.microsoft.com/en-us/azure/devops/service-hooks/view-permission?view=azure-devops) project permission — so Pipekit can create [Service Hook](https://learn.microsoft.com/en-us/azure/devops/service-hooks/overview?view=azure-devops) subscriptions on the repo. There is no longer a standalone "Service Hooks" PAT scope; Microsoft has made `vso.hooks*` [private](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops), 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](/pipekit/clusters.md) and then [create a pipe](/pipekit/pipes.md) 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](/pipekit/pipes.md) that run Workflows stored in your Git repositories.
* Create and manage Pipes that use [Run Conditions](https://github.com/pipekit/pipeline-mono/blob/gitbook/docs/pipekit/pipes/managing-pipes/run-conditions.md) to trigger Workflows on GitHub events.
* The [WorkflowTemplates](/pipekit/templates.md) features of Pipekit.
* Manage [Workflow Priorities](/pipekit/clusters.md#queuing)
* Manage [Namespace Permissions](/pipekit/organization/permissions.md) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pipekit.io/self-hosting-pipekit/integrating-with-your-git-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.