Skip to content

LinearB On-Prem Agent Post-Deployment Configuration Guide

This guide provides detailed instructions for post-deployment configuration of the LinearB On-Prem Agent. Follow these steps to configure the agent, set up integrations, and enable webhook processing.

Table of Contents

  1. Prerequisites
  2. Step 3: Launch Shell in agent-cli Pod
  3. Step 4: Set Up a New Integration
  4. Step 5: Register Git Repositories
  5. Step 6: Installing a Git Provider Webhook
  6. Step 6.c: Bitbucket Webhook Note

Prerequisites

Ensure you have the following before proceeding:

  • Access to the Kubernetes cluster with the LinearB On-Prem Agent deployed.
  • kubectl installed and configured for your cluster.
  • Access to the required credentials and tokens for Git and Jira integrations.

Step 3: Launch Shell in agent-cli Pod

Step 3.a: Enter the Pod

The following steps involve configuration after the cluster is up and running. Ensure your kubectl command points to the relevant cluster by running:

kubectl config use-context <cluster-name>

To launch a shell inside the agent-cli pod, run:

kubectl exec -it $(kubectl get pod  -n linearb -l app.kubernetes.io/name=agent-cli -o jsonpath="{.items[0].metadata.name}") -- /bin/bash

Step 3.b: Run Basic Health Checks

Once inside the pod shell, verify the agent's connectivity to LinearB Cloud by running:

python agent-cli.py health-checks

Expected output:

Running health check for 'LinearB agent API connectivity'...
...
Health check tests summary:
---------------------------------------
LinearB agent API connectivity: True

Step 4: Set Up a New Integration

The following commands should be executed inside the agent-cli pod.

Step 4.a: Add a Git Integration

To add a new Git integration, run:

python agent-cli.py add-git-integration --provider <provider> --token <PAT Token> --self_hosted_uri <Self hosted Git URI>
 --account_id <Admin Account ID> --token_username <token username, for bitbucket_server only>
  • Replace <provider> with github, gitlab, or bitbucket_server.
  • For GitHub, ensure you use a Personal Access Token (classic), as fine-grained tokens are unsupported.
  • Use --git_ssl_no_verify=true for self-signed certificates or add the custom root certificate in the local-values.yaml.

Test the integration setup by running:

python agent-cli.py validate-git-token --integration_id <integration-id>

Expected output:

Git instance access and token validated successfully: {"required_scopes":["user:email","repo","read:user","read:discussion"], ...}

Step 4.b: Add a Jira Integration

To add a Jira integration, follow these steps:

  1. Create a new application link in Jira:

    • Go to Jira Administration > Applications > Application Links.
    • Use the following redirect URL: https://app.linearb.io/public/jira/challenge_callback.
    • Configure as External application with Read permission.

  2. Run the CLI command: 

    python agent-cli.py add-jira-integration --account_id=<account_id> --self_hosted_uri=https://<jira_url>

  3. Follow the CLI wizard to complete the setup.

Expected response:

Integration created successfully. The Integration id is: <integration id>

Save the <integration id> for later use.
Note you may retrieve the integration id by running:

  python agent-cli.py list-integrations

Step 5: Register Git Repositories

To register repositories with the LinearB agent, use one of the following commands:

  • Single Repository Registration: 

    python agent-cli.py register-single-repository --integration_id <integration-id> --repo_name <repo-name> --git_org <git-organization-for-github>

  • Multiple Repositories Registration: 

    python agent-cli.py register-repositories --integration_id <integration-id> --query_str <repo-search-string> --page_size <number-of-repos-to-fetch> --git_org <git-organization-for-github>

Step 6: Installing a Git Provider Webhook

The On-Prem Agent provides an HTTP endpoint to receive real-time webhooks from your Git provider. The endpoint is accessible at [webhook endpoint] as defined below for K3D and cloud deployments, respectively.

  • For K3D a health check endpoint is available at http://<k3d host address>:8081/health.
  • For Cloud deployments, the endpoint is accessible at http://<load-balancer-address>:80/health.

Step 6.a: Installing GitHub Organization-Level Webhook

If using GitHub Enterprise, set up an organization-level webhook:

  1. Refer to the GitHub Organization-Level Webhook Guide.
  2. Replace the URL with [webhook endpoint]/hooks/github?integration_id=[integration_id] and leave the secret empty.
  3. Verify the webhook by checking for a green checkmark.

Step 6.b: Installing GitLab Group-Level Webhook

For GitLab, set up a group-level webhook:

  1. Use the URL [webhook endpoint]/hooks/gitlab?integration_id=[integration_id].
  2. Required triggers: Push Events, Tag Push Events, Comments, and Merge Request Events.
  3. SSL verification is optional, based on the [webhook endpoint].

Step 6.c: Bitbucket Webhook Note

Bitbucket Server does not support server-level webhooks. A webhook is automatically created for each repository when added to the LinearB agent.