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 1: Launch Shell in agent-cli Pod
  3. Step 2: Set Up a New Integration
  4. Step 3: Register Git Repositories
  5. Step 4: Installing a Git Provider Webhook

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 1: Launch Shell in agent-cli Pod

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

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 2: Set Up a New Integration

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

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>
  • Replace <provider> with github, gitlab, or bitbucket_server.
  • --token_username is required for bitbucket_server only.
  • 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 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

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 3: 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 4: 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.

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.

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 .

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.