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
- Prerequisites
- Step 1: Launch Shell in
agent-cliPod - Step 2: Set Up a New Integration
- Step 3: Register Git Repositories
- Step 4: Installing a Git Provider Webhook
- Integration Data Storage Backend
Prerequisites
Ensure you have the following before proceeding:
- Access to the Kubernetes cluster with the LinearB On-Prem Agent deployed.
kubectlinstalled 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:
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:
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>withgithub,gitlab, orbitbucket_server. --token_usernameis required forbitbucket_serveronly.- For GitHub, ensure you use a Personal Access Token (classic), as fine-grained tokens are unsupported.
- Use
--git_ssl_no_verify=truefor self-signed certificates, or add the custom root certificate in local-values.yaml.
Test the integration setup by running:
Expected output:
Add a Jira Integration
To add a Jira integration, follow these steps:
-
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.
-
Run the CLI command:
-
Follow the CLI wizard to complete the setup.
Expected response:
Save the <integration id> for later use.
Note you may retrieve the integration id by running:
Step 3: Register Git Repositories
To register repositories with the LinearB agent, use one of the following commands:
-
Single Repository Registration:
-
Multiple Repositories Registration:
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:
- Refer to the GitHub Organization-Level Webhook Guide.
- Replace the URL with
<webhook_endpoint>/hooks/github?integration_id=<integration_id>and leave the secret empty. - Verify the webhook by checking for a green checkmark.
GitLab Group-Level Webhook
For GitLab, set up a group-level webhook:
- Use the URL
<webhook_endpoint>/hooks/gitlab?integration_id=<integration_id>. - Required triggers: Push Events, Tag Push Events, Comments, and Merge Request Events.
- 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. The webhook endpoint will be [webhook endpoint]/hooks/bitbucket_server?integration_id=[integration_id]. Note that the endpoint will be taken from global.AGENT_HOST_URL (mapped to AGENT_HOST_URL in common-chart-values configmap in linearb namespace)
Integration Data Storage Backend
The integrations you add above, together with their tokens, are stored in a small JSON document. Where that document lives is controlled by global.INTEGRATIONS_STORAGE_BACKEND in local-values.yaml:
| Value | Where the data is kept |
|---|---|
minio (default) | A db.json object inside the bundled MinIO local-db bucket. |
secrets | A Kubernetes Secret named integrations in the release namespace, created and maintained by the agent. |
The setting is read by the agent-api and agent-cli services. An unrecognised value — secret or k8s, for example — falls back to minio without reporting an error, so check the spelling if a change appears to have had no effect.
MinIO Is Deployed Either Way
Selecting secrets changes only where integration data is written. The MinIO deployment, its PersistentVolumeClaim and the volume sized by PV_SIZE are still created, because other parts of the agent use that storage. Choosing secrets is not a way to run without MinIO.
Size Limit When Using secrets
A Kubernetes Secret cannot exceed 1 MiB, and the agent rewrites the whole document on every change. A large number of integrations, or integrations carrying many tokens, can reach that ceiling, after which writes fail. If you expect a large configuration, stay with minio.
Deleting the Namespace When Using secrets
The commands in this and the following sections assume the agent is installed in the linearb namespace. If you deployed it elsewhere, substitute your namespace and pass --namespace <namespace> to backup_restore_db_json.sh.
The integrations Secret can carry a finalizer. While it does, kubectl delete namespace linearb does not complete — the namespace stays in Terminating until the finalizer is cleared. Check before deleting the namespace:
If that prints nothing, no action is needed. Otherwise, save the contents first if you still need them:
kubectl get secret integrations -n linearb -o jsonpath='{.data.db\.json}' | base64 --decode > db.json
Then clear the finalizer:
Backing Up Integration Data
backup_restore_db_json.sh reads and writes the MinIO bucket only. It does not detect which backend is active, so on a deployment using secrets it will appear to succeed while backing up whatever stale copy MinIO still holds.
The script keeps its file one directory above the script itself — run from the extracted package directory, that is ../db.json. --backup writes that file and refuses to run if it already exists; --restore reads it.
- Backend
minio: use./backup_restore_db_json.sh --backupand--restore. - Backend
secrets: use thekubectl get secretcommand shown above to export the data. To restore it, run:
Switching Between Backends
Changing the value does not move existing data — copy it across yourself. Copy it into the new location before the redeploy, so that the services never start against an empty or out-of-date document. Stop agent-api and agent-cli for the duration so that no integration is added or changed during the copy.
Run these commands from the extracted package directory, where deploy.sh and backup_restore_db_json.sh live.
From minio to secrets:
# 1. Stop the services that write integration data
kubectl -n linearb scale deployment -l 'app.kubernetes.io/name in (agent-api,agent-cli)' --replicas=0
# 2. Export the current document from MinIO to ../db.json
./backup_restore_db_json.sh --backup
# 3. Create the Secret from that file (replaces it if one is left over from an earlier switch)
kubectl -n linearb create secret generic integrations --from-file=db.json=../db.json \
--dry-run=client -o yaml | kubectl apply --server-side -f -
# 4. Under global: in local-values.yaml, set INTEGRATIONS_STORAGE_BACKEND: "secrets", then redeploy
./deploy.sh --namespace <namespace> --version <your chart version>
# 5. Make sure both services are running again
kubectl -n linearb scale deployment -l 'app.kubernetes.io/name in (agent-api,agent-cli)' --replicas=1
From secrets to minio:
# 1. Stop the services that write integration data
kubectl -n linearb scale deployment -l 'app.kubernetes.io/name in (agent-api,agent-cli)' --replicas=0
# 2. Export the current document from the Secret to ../db.json, where backup_restore_db_json.sh reads it
kubectl get secret integrations -n linearb -o jsonpath='{.data.db\.json}' | base64 --decode > ../db.json
# 3. Load the file into the MinIO bucket (MinIO runs whichever backend is selected)
./backup_restore_db_json.sh --restore
# 4. Under global: in local-values.yaml, set INTEGRATIONS_STORAGE_BACKEND: "minio", then redeploy
./deploy.sh --namespace <namespace> --version <your chart version>
# 5. Make sure both services are running again
kubectl -n linearb scale deployment -l 'app.kubernetes.io/name in (agent-api,agent-cli)' --replicas=1
After switching, confirm your integrations are intact by running python agent-cli.py list-integrations from the agent-cli pod (see Step 1) before removing the old copy. After moving to minio, the old copy is the integrations Secret: clear its finalizer if it has one (see Deleting the Namespace), then kubectl delete secret integrations -n linearb.