Development Platform Integrations¶

This section covers integrating Pixee Enterprise Server with various development platforms and source code management systems.

Azure DevOps Integration¶

Azure DevOps integration allows Pixee Enterprise Server to work with your Azure DevOps repositories. Pixee can authenticate using either a personal access token (the default) or a Microsoft Entra service principal.

Authentication methods¶

Choose one authentication method at install or configuration time:

Personal Access Token (PAT) (default): Pixee authenticates with a personal access token over HTTP Basic auth. Works against both Azure DevOps Services and on-prem Azure DevOps Server.
Entra Service Principal (SPN): Pixee authenticates with a Microsoft Entra service principal using the OAuth 2.0 client-credentials flow, sending the resulting bearer token on both REST and Git operations. Use this when your organization has standardized on Entra and disallows personal access tokens.

Warning

Service-principal authentication is supported only against Azure DevOps Services (dev.azure.com). On-prem Azure DevOps Server must use a personal access token.

Requirements¶

For PAT authentication:

Your Azure DevOps organization name
A personal access token with a custom scope (not "Full access", which grants broader permissions than necessary) that includes:
- Code (Read & Write) — read repositories, push fix branches, and open and update pull requests
- Build (Read) — read builds and download build artifacts
- Work Items (Read & Write) — required only when a work item ID is configured

For SPN authentication:

Your Azure DevOps organization name
A Microsoft Entra app registration (service principal) in your tenant. From the registration you need the tenant (directory) ID, the application (client) ID, and a client secret.
The service principal must be added to your Azure DevOps organization as a user and granted Code (Read & Write) access on the repositories Pixee operates on. It also needs Work Items (Read & Write) when a work item ID is configured.

Info

The webhook user and password are optional properties for Azure DevOps webhook authentication. If configured, these credentials will be used to authenticate incoming webhook requests from Azure DevOps. Webhook authentication is independent of the PAT/SPN choice.

Configuration¶

Embedded ClusterHelm Deployment

For embedded cluster deployments, navigate to the admin console, Config tab and then to the Development Platforms section.

Select the Azure DevOps checkbox to enable Azure DevOps integration, then choose an authentication method.

For Personal Access Token, enter:

Organization: Your Azure DevOps organization name
Token: Your personal access token, scoped as described under Requirements

For Entra Service Principal, enter:

Organization: Your Azure DevOps organization name
Entra tenant ID, application (client) ID, and client secret

Webhook credentials (optional): Username and password for webhook authentication if desired.

For Helm deployments using a personal access token, add the following to your values.yaml:

platform:
  scm:
    azure:
      authType: "PAT"
      organization: "<your azure devops organization name>"
      token: "<your personal access token>"
      # Optional: For webhook authentication
      # webhook:
      #   user: "<your webhook username>"
      #   password: "<your webhook password>"
      # Use existing secret instead of creating one
      existingSecret: ""
      secretKeys:
        # -- The secret key containing the token
        tokenKey: "token"
        # -- The secret key containing the webhook password
        webhookPasswordKey: "webhookPassword"

For a Microsoft Entra service principal, set authType: "SPN" and provide the service-principal credentials instead of a token:

platform:
  scm:
    azure:
      authType: "SPN"
      organization: "<your azure devops organization name>"
      spn:
        tenantId: "<your entra tenant id>"
        clientId: "<your service principal application/client id>"
        clientSecret: "<your service principal client secret>"
      # Use existing secret instead of creating one
      existingSecret: ""
      secretKeys:
        # -- The secret key containing the service-principal client secret
        clientSecretKey: "clientSecret"

Linking a work item to Pixee's pull requests¶

Some Azure DevOps repositories require every pull request to reference a work item, most commonly through the Require linked work item branch policy. Others require the reference on the commit that lands on the target branch. Set a work item ID and Pixee covers both: it links that work item to every pull request it opens, and it inserts a #<work item ID> reference at the front of every commit message it writes on Azure DevOps repositories.

Embedded ClusterHelm Deployment

In the admin console, Config tab, Development Platforms section, set Work Item ID to the numeric ID of an existing work item.

platform:
  scm:
    azure:
      workItemId: "12345"

The work item must already exist in the configured organization — Pixee links an existing work item and never creates one. The same work item is linked to every pull request Pixee opens.

Warning

The credential Pixee authenticates with must have Work Items (Read & Write) access. Linking writes a relation on the work item, so with Code-only access Azure DevOps accepts the pull request, reports success, and then silently discards the link.

Which merge option each mechanism covers¶

Both mechanisms are needed, because which commit lands on the target branch depends on the repository's merge option. Setting Work Item ID enables both, so every merge option is covered.

Merge option	Commit that lands on the target branch	What carries the work item reference
Merge (no fast-forward)	Azure DevOps generates a merge commit	the pull request link, plus the reference Pixee puts in the pull request title
Squash commit	Azure DevOps generates a squash commit	the same
Rebase and fast-forward	Pixee's own commits, replayed	the commit message itself
Semi-linear merge	Pixee's commits plus an Azure DevOps merge commit	both

Azure DevOps builds its merge commit message as Merged PR <id>: <pull request title>, followed by the description and then a trailing Related work items line. That trailing line is the first content lost when Azure truncates the message, which is why Pixee puts the reference at the front of the pull request title and at the front of the commit summary line rather than at the end.

If you already set a work item ID

Before this release, Work Item ID affected pull requests only. It now also changes the commits Pixee writes: on Azure DevOps repositories every commit message begins with #<work item ID>, where it previously began with Git Commit Message Prefix, or with nothing when no prefix was set. Nothing needs to be reconfigured — but if anything downstream reads Pixee's commit message text, such as a pipeline check or a changelog generator, review it before upgrading.

Do not repeat the reference in the commit message prefix¶

Git Commit Message Prefix (platform.gitCommitMessagePrefix) applies to every SCM, so a prefix containing #12345 reaches your GitHub, GitLab, and Bitbucket commits too — where it means nothing, and where on GitHub #12345 cross-links whatever issue or pull request happens to have that number.

If you previously put the work item reference in the commit message prefix because it was the only way to get it onto the commit, remove it now and keep Work Item ID set. Pixee then inserts the reference on Azure DevOps repositories only.

Nothing breaks if you leave both configured. When the prefix already carries the reference as a standalone #<work item ID> token, Pixee leaves it exactly as you set it and your commit messages do not change. If your prefix wraps or punctuates the reference — [#12345], #12345: — Pixee does not recognize it and adds its own, so the reference appears twice. Removing it from the prefix avoids that.

BitBucket Cloud Integration¶

BitBucket Cloud integration allows Pixee Enterprise Server to work with your BitBucket repositories and requires account credentials with specific permissions.

For security, it is recommended to create and use an API token for BitBucket Cloud integration rather than using personal credentials. See the BitBucket API Token documentation for information on creating an API token.

Note

BitBucket API tokens require your account's email address for API authentication, while Git operations use your username. Make sure to configure both values.

Requirements¶

BitBucket Cloud integration requires:

A BitBucket Cloud username (used for Git operations)
Your BitBucket account email address (used for API authentication)
An API token with the following scopes:
- read:user:bitbucket
- read:workspace:bitbucket
- read:repository:bitbucket
- read:pullrequest:bitbucket
- write:repository:bitbucket
- write:pullrequest:bitbucket

Configuration¶

Embedded ClusterHelm Deployment

For embedded cluster deployments, navigate to the admin console, Config tab and then to the Development Platforms section.

Select the BitBucket checkbox to enable BitBucket Cloud integration.

Enter the following information in the configuration fields:

Username: Your BitBucket Cloud username (used for Git operations)
Email Address: Your BitBucket account email address (used for API authentication)
API Token: Your BitBucket API token

For Helm deployments, add the following to your values.yaml:

platform:
  scm:
    bitbucket:
      username: "<your bitbucket cloud username>"
      emailAddress: "<your bitbucket account email address>"
      apiToken: "<your bitbucket api token>"
      # Use existing secret instead of creating one
      existingSecret: ""
      secretKeys:
        # -- The secret key containing the API token
        apiTokenKey: "apiToken"

GitHub Integration¶

GitHub integration allows Pixee Enterprise Server to work with GitHub.com or self-hosted GitHub Enterprise Servers and requires a custom GitHub app to be created.

Pixee Enterprise Server is able to integrate with GitHub.com and self-hosted GitHub Enterprise Servers. If you are self-hosting a GitHub enterprise server or otherwise have configured GitHub enterprise server on a domain other than github.com, see the Configuration section below for instructions on setting your custom GitHub domain.

GitHub integration comes in the form of a custom GitHub app, which will be needed to configure GitHub integration in Pixee Enterprise Server. A custom GitHub app configures webhook events, event destination, and permissions for enhanced GitHub integration. In creating this application, we have followed the best practices provided by GitHub.

Info

Network communication between your GitHub (.com or Enterprise Server) and Pixee Enterprise Server must exist. This can vary based on the deployment configuration of GitHub Enterprise Server and Pixee Enterprise Server.

GitHub App Setup¶

Unless otherwise instructed, leave the existing default values provided by GitHub.

Go to https://github.com/settings/apps, replace github.com with your own private GitHub host as needed.
Click New GitHub App button.
Set the GitHub App name to something unique (i.e. "AcmePixeebotApp"), save this value for later.
Set Homepage URL to anything (i.e. "https://pixee.ai"), this can be updated later.
Set the Callback URL to the URL of your host/cluster in the following format http://acme.getpixee.com/api/auth/login.
Check Request user authorization (OAuth) during installation.
Check Active under Webhook.
Set Webhook URL, to the URL of your host/cluster in the following format http://acme.getpixee.com/github-event.
Set Webhook Secret to a secret value, a randomly generated string will work (save this for later).

Set these Repository permissions:

Repository permissions	Access
Checks	Read and write
Code scanning alerts	Read and write
Commit statuses	Read and write
Contents	Read and write
Dependabot alerts	Read and write
Issues	Read and write
Metadata	Read-only
Pull Requests	Read and write
Workflows	Read and write

Set these Organization permissions:

Organization permission Access

Members Read-only
Set these Account permissions:

Account permissions Access

Email addresses Read-only
Check to Subscribe to events for the following:
- Code scanning alert
- Check Run
- Create
- Dependabot alert
- Issue Comment
- Issues
- Pull request
- Pull request review
- Pull request review comment
- Pull request review thread
- Push
- Repository
For Where can this GitHub App be installed? select Only on this account, this can be updated later.
Click Create GitHub App button.
Once the GitHub App is created, you should see the GitHub App configuration page.
Copy App ID and save for later.
Scroll down and click Generate a private key, download the private key file and save for later.

Configuration¶

Select your installation method for instructions.

Embedded Cluster DeploymentHelm Deployment

For embedded cluster deployments, navigate to the admin console, Config tab and then to the Development Platforms section.

Select the GitHub checkbox to enable GitHub integration.

If you are self-hosting a GitHub enterprise server or otherwise have configured GitHub enterprise server on a domain other than github.com, be sure to select custom domain for the GitHub domain setting in the Pixee Enterprise Server admin console and enter your custom GitHub domain.

After creating up your GitHub App, insert the following data into the appropriate fields on the Pixee Enterprise Server admin console configuration screen:

app name
app id
app private key (downloaded from browser)

For Helm deployments, add the following to your values.yaml:

platform:
  github:
    appName: "<your custom GitHub app name>"
    appId: "<your custom GitHub app id>"
    appWebhookSecret: "<your custom GitHub app webhook secret>"
    appPrivateKey: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
    # -- Use an existing secret instead of creating one
    existingSecret: ""
    secretKeys:
      # -- The secret key containing the appWebhookSecret
      appWebhookSecretKey: appWebhookSecret
      # -- The secret key containing the appPrivateKey
      appPrivateKeySecretKey: appPrivateKey   
    # For GitHub Enterprise hosted at domains other than github.com, uncomment set your GitHub Enterprise url:
    # url: "https://github.your-company.com"

Tip

Be sure to check the indentation is correct for each line of the GitHub app private key

Verification¶

If you enabled GitHub integration and created a custom GitHub app, you can verify your GitHub App connectivity by checking your GitHub App's event log. This log can be accessed through your GitHub App's settings under the "Advanced" section. See GitHub.com for more information.

GitLab Integration¶

Pixee Enterprise Server is able to integrate with https://gitlab.com as well as self-hosted GitLab servers. If you have a self-hosted GitLab server, see the Configuration section below for instructions on setting your custom GitLab base URI.

Requirements¶

GitLab integration requires:

A GitLab personal access token with the following scopes:
- api
- read_user
- read_repository
- read_api
- write_repository
- ai_features
- read_registry
- read_virtual_registry
(Optional) Self-hosted GitLab server base URI if not using GitLab.com
(Optional) Webhook secret for GitLab webhook integration

Tip

It is recommended to use a GitLab service account to generate the personal access token rather than a personal user account. Service accounts are not tied to individual users, which avoids disruption if a team member leaves or their account is modified. The service account should be granted access to the groups or projects that Pixee will manage.

Configuration¶

Embedded ClusterHelm Deployment

For embedded cluster deployments, navigate to the admin console, Config tab and then to the Development Platforms section.

Select the GitLab checkbox to enable GitLab integration.

Enter the following information in the configuration fields:

Token: Your GitLab personal access token with the required scopes listed above
Base URI (optional): Your self-hosted GitLab server URL
Webhook secret (optional): Secret for webhook authentication

For Helm deployments, add the following to your values.yaml:

platform:
  scm:
    gitlab:
      # For self-hosted GitLab, add:
      # baseUri: "https://gitlab.your-company.com"
      token: "your-personal-access-token"  # requires scopes: api, read_user, read_repository, read_api, write_repository, ai_features, read_registry, read_virtual_registry
      # If you are using GitLab webhooks, provide the webhook secret:
      # webhookSecret: "your-gitlab-webhook-secret"
      # Use existing secret instead of creating one
      existingSecret: ""
      secretKeys:
        # -- The secret key containing the token
        tokenKey: "token"
        # -- The secret key containing the webhookSecret
        webhookSecretKey: "webhookSecret"

Webhook Configuration¶

If you want to use webhooks to notify Pixee of build events, you'll need to configure webhooks in your GitLab project.

The webhook URI should be: https://<example-pixee-server.com>/api/v1/integrations/gitlab-default/webhooks

For detailed instructions on configuring GitLab webhooks, see the GitLab Webhook Documentation.

The webhook secret configured in Pixee Enterprise Server should match the secret token configured in your GitLab webhook settings.