Connect your code to the Designer

Add a code source - the CLI, an upload or a repository - so your designs can be matched to what was really built.

In short

A code source tells {{brand}} what was built. It reads only the structure - service names, how they connect and their endpoints - never code or a secret value. Readings arrive three ways: the {{brand}} CLI, files you upload, or a repository {{brand}} reads on every push.

Before you start

• Who: someone who manages the Designer here adds a code source. A person who may only view the Designer sees no "Add code source". The token you give must be able to read only.
• Plan: Designer is part of every plan, Free included. The Free plan limits how many designs a workspace keeps; Plan & usage shows the limit and what you hold. The Free plan allows one code source and a few readings a day; the paid plans allow more. Connecting a repository comes with a paid plan.
• First: pick CLI, upload or repository, and make a read-only token if you connect a repository (see the table for your IT team).

Steps

1. On the Designer home, choose "Code", then press "Add code source".
2. Choose "Scan with the CLI", give it a "Name" such as shop-backend, and press "Add the source".
3. Copy the command it shows and run it in the repository's folder, on your machine or in a pipeline step, with an access token in KAMOCORE_TOKEN.

1. Press "Add code source", choose "Upload files", name it and press "Add the source".
2. Drop your docker-compose files, Helm charts, Kubernetes manifests or OpenAPI documents, then press "Read N files".

1. Press "Add code source" and choose "Connect a repository". It is offered once an organization admin has connected a code host in Organization settings.
2. Choose the "Connection", then type the "Repository" as the example under the field shows, and a "Branch to follow" if not the default branch.
3. Give it a "Name" if you like, and press "Connect".
4. The first reading starts at once. The connection's webhook reads again on every push; until it hears one, an hourly check stands in.
5. Press "Test connection", then "Done".

Result: the source shows "Last read" with what it found, such as "12 services, 9 connections, 40 endpoints". Open an architecture and press "Check against code" to compare it.

1. On the Designer home, choose "Code" and press "Import from repository". It shows in an organization that has a git connection, to people who manage the Designer here.
2. Under "Repository", choose the "Git connection", type the "Repository" as the host writes it, such as acme/shop, and the "Branch", then press "Next".
3. Under "What to map", choose the "Code to map": "Backend", "Web" or "Both". Under "Bring into", choose the products that look for what they can use, then press "Find what is there".
4. Under "What was found", open a group to see its items and tick what to bring in; a large group is ticked only when you choose it. Under "Bring into", pick where the items go, or "A new one" with its name, then press "Next".
5. Under "Keep in step", choose "As drafts to review" or "Add at once", and press "Import".

Result: "Imported" counts what was added, updated and left out, and says "Following acme/shop at main." With "As drafts to review", changes from later pushes wait in "From the repository" until someone presses "Accept" or "Ignore".

Good to know

• Add --dry to the CLI command to print exactly what would be sent. It sends nothing.
• Uploads take at most 10 MB and 300 files together. The files are read for their structure and then thrown away.
• A name that looks like a secret is left out of a reading; the source counts how many.
• Connecting a repository comes with a paid plan. On other plans the "Connect a repository" card says so and cannot be chosen: scan with the CLI or upload files.
• Without the webhook, an hourly check looks for a new commit. "Read now" reads at once.
• Readings run as the person whose token was given. "Take it over" makes them run as you, when that person can no longer manage the source.
• Deleting a source deletes its readings. Designs keep everything drawn in them.
• A reading also names the database tables each service reads or writes. The System map shows them under "Tables it reads or writes" for the service you choose, and a change to a service names its tables beside its APIs wherever {{brand}} says what a change touches.
• The line above the sources counts those reading well, failing, paused, and switched on with no reading for 7 days, and says when the newest reading came. A stale or failing source means designs are matched against old code.
• People who may only view the Designer see no "Add code source". Someone who manages the Designer here can add one.
• What happens next: the source shows "Last read" with what it found. Take it back by deleting the source; its readings go, and your designs keep everything drawn in them.
• "Import from repository" brings a repository's components, screens, flows and tables into designs, and its API requests and SQL into API Tester and SQL Tester in the same pass. "Connect a repository" keeps a code source your designs are checked against. Nothing is overwritten: later changes arrive beside what people made.

Give a token that can only read A GitLab token with api or write scopes is refused. Azure DevOps cannot tell {{brand}} what a token may do, so give it only Code (Read).

Details for your IT team

• Self-hosted servers: switch on "It runs on our own ..." and give the https "Address of your server" with no user name, password or ? part.
• {{brand}} reads only files that describe the system: compose, Helm, Kubernetes, project files and OpenAPI.
• The CLI's token must be allowed to change Designer data.

If something goes wrong

• "Test connection" marks a step "Failed": the step names what to change - the host, the token, the repository, the branch, or a token that can do more than read.
• "This does not look like a repository path for this provider." - check the example under "Repository".
• "None of these files describes services: upload compose, Helm, Kubernetes or OpenAPI files."
• "The files are larger than 10 MB together." - leave some files out.
• A source says "Failing": its last problem is shown with how to fix it; see /help/settings/fix-a-company-connection for a connection code.

Related

• /help/designer/live-match
• /help/designer/design-drift
• /help/settings/access-tokens
• /help/api-testing/test-impact