Agent onboarding

Once your agent runs successfully in bridge_dev mode - with all MCP tool calls returning 200 OK, LLM working, and audit logging active - you are ready to onboard the agent image to the Bridge Platform.

Important - Canonical Reference:

The complete, authoritative guide with every detail, YAML snippet, and parameter table is here. This page is a summary. If anything below seems incomplete, refer to the full guide above — it is the source of truth.

Prerequisites

Before starting onboarding, confirm:

Checkpoint	How to verify
Agent runs end-to-end in bridge_dev	python main.py completes with "status": "success"
MCP tool calls return 200 OK	Logs show HTTP/1.1 200 OK for every MCP call
LLM calls succeed	Logs show 200 OK on /chat/completions
Audit records created	Logs show 201 Created on /api/audit/v4/records
Agent registered in catalog	agent-catalog-registration.json submitted via /kaif/v3/agent-catalog/agents
Deployment created	deployment-registration.json submitted via /kaif/v3/deployment/agentic
Governance signoffs complete	All 4 files in governance/ set to approved: true

Quick summary of each step

Step 1: Create repo from template

Browse templates in kyndryl-agentic-ai org → click "Use this template" → name it bdg-sw-agents-your-agent → keep Private.

Step 2: Add required teams

Team	Role
bdg-sw-agents-admin	Admin — provisions secrets, creates release branches
bdg-sw-agents-read-write	Write — developers who push code
bdg-sw-agents-read-only	Read — stakeholders and reviewers

Without these teams, onboarding and release cut will fail.

Step 3: CI/CD — Build & Security Orchestrator

Create .github/workflows/build-and-security.yml using the reusable orchestrator:

Input parameters:

Parameter	Required	Default	Description
python-version	No	"3.12"	Python version for unit tests and quality checks
test-framework	No	"pytest"	"pytest" or "unittest"
test-directory	No	"tests"	Directory where test files are located
use-private-registry	No	false	Set true if requirements.txt has private packages from JFrog. Requires pyinstall.sh in repo root.
docker-build-args	No	""	Docker build arguments (--build-arg KEY format). When using pyinstall.sh, pass "--build-arg DEVOPS_ARTIFACTORY_USER --build-arg DEVOPS_ARTIFACTORY_APIKEY".
codeql-language	No	"python"	Language for CodeQL static analysis

Secrets (required):

Secret	Purpose
SECURITY_TOKEN	GitHub PAT for security scanning
AFAAS_USER	JFrog Artifactory username
AFAAS_TOKEN	JFrog Artifactory access token

These secrets are provisioned automatically during onboarding (Step 4). You do not need to create them manually.

Four gates enforced in sequence:

Gate	What
🧪 Quality	Unit tests with ≥85% code coverage enforced
🔍 CodeQL	Static security analysis
🔒 Security	Dependency + code + secret scanning
🐳 Docker	Build → JFrog Xray CVE scan → push to Artifactory

Note: Do not call individual workflows (e.g. docker-build.yml) directly — the orchestrator is the only supported entry point. Direct calls will be blocked.

Step 4: Request onboarding

Open issue at bdg-sw-agents-images-onboarding → New Issue

Select "Repo onboarding: configure Docker Credentials"

Enter repo name only (e.g. bdg-sw-agents-my-agent, not kyndryl-agentic-ai/bdg-sw-agents-my-agent)

A Technical Owner and Business Owner comment /approve

Bot provisions secrets (SECURITY_TOKEN, AFAAS_USER, AFAAS_TOKEN) automatically

Step 5: Develop & push

Your repo comes pre-configured with:

What	Where
Agent logic	src/agents/
Tools	tools.py
Configuration	settings.py, config.py
Docker build	Dockerfile
CI/CD pipeline	.github/workflows/build-and-security.yml (set up in Step 3)
Unit tests	tests/

Push code → CI/CD triggers automatically on pushes and pull requests to main, master, and release-* branches. All security and quality gates are enforced centrally — individual repos cannot skip any gate.

Unit tests are mandatory: The CI/CD pipeline enforces ≥85% code coverage. Your tests/ directory must contain meaningful test cases for the build to pass. Teams can use GitHub Copilot to help write test cases for their agent workflows, tools, and nodes.

Step 6: Governance signoffs

Complete all 4 files in governance/:

File	What to review
SECURITY_SIGNOFF.yaml	Secrets management, authentication, data protection, AI security
OSSC_LEGAL_SIGNOFF.yaml	Open-source compliance, license review
BUSINESS_FUNCTIONAL_SIGNOFF.yaml	Business requirements, functional validation
TECHNICAL_SIGNOFF.yaml	Architecture review, technical approval

For each file:

Set approved: true

Fill in the approver block: yaml approver: name: Your Name email: [email protected] date: "2026-03-06"

Set all checklist items to true

Fill in agent_name and version

Commit and push to main

Note: If any signoff is incomplete, the release cut request will be automatically rejected with a detailed report of what's missing.

Step 7: Request release cut

Go to bdg-sw-agents-images-onboarding → New Issue

Select "Release cut: create release branch"

Enter your repo name only

Submit the issue

What happens next:

Step	Automated Action
1	Bot validates your repo exists
2	Bot checks if a release branch already exists (duplicate guard)
3	Bot clones your repo and validates all 4 governance signoff files
4	If governance passes → 🤖 Copilot reviews your repo's structure and security
5	Bot posts the Copilot review findings and RM approval instructions
6	A Release Manager (RM) reviews the Copilot analysis and comments /approve
7	Bot creates a release-YYYY.MM.DD branch (targeting next Wednesday)
8	Issue is closed with the branch details and deployment payload

Copilot Review - After governance passes, the platform runs an AI-powered review:

Review	What it checks
Structure Review	Project layout, Dockerfile, dependencies, CI/CD readiness
Security Review	Hardcoded secrets, dependency security, Docker security, input validation

The review is informational only — it does not block approval, but gives the RM context. It runs within your Copilot Business licence boundary — code is not retained.

After release cut: - A release-YYYY.MM.DD branch is created on your repo - The CI/CD pipeline auto-triggers for the release branch - Docker image is built, scanned, and pushed to JFrog Artifactory

Step 8: Get the image tag and complete registration

After the CI/CD pipeline finishes on the release branch:

Go to your repo → Actions → click the latest build run

Open the docker-build-and-push job logs

Find the success line: Notice: ✅ Pushed kyndryl.jfrog.io/kyn-cto-kaif-docker-local/bdg-sw-agents-your-agent:release-YYYY.MM.DD--<sha>-<ts>

Copy the full image tag (e.g. kyndryl.jfrog.io/kyn-cto-kaif-docker-local/bdg-sw-agents-your-agent:release-2026.03.27--5d45dd2-1774525017)

Update your catalog registration — set the image field in your agent-catalog-registration.json to the new image tag, then call the PUT or PATCH API

Create a fresh deployment registration — submit a new deployment via /kaif/v3/deployment/agentic with the updated agent_catalog_id. The platform will now run your agent from this Docker image.

Updates: Every time you cut a new release, grab the new image tag from the build logs, update the catalog registration, and create a fresh deployment.

Complete checklist:

Created repo from a template (Step 1)

Added bdg-sw-agents-admin (Admin), bdg-sw-agents-read-write (Write), and bdg-sw-agents-read-only (Read) teams (Step 2)

Created .github/workflows/build-and-security.yml using the orchestrator (Step 3)

Submitted [Onboard] issue and got secrets provisioned (Step 4)

Pushed code and CI/CD pipeline is passing (Step 5)

Completed all 4 governance signoff files with approved: true (Step 6)

Submitted [Release Cut] issue and got release branch created (Step 7)

Issue Labels Reference

Label	Meaning
onboarded 🔵	Secrets provisioned
release-cut-done 🟢	Release branch created
invalid-request 🔴	Repo doesn't exist
governance-failed 🔴	Signoffs incomplete
duplicate-release 🟠	Release branch already exists