Add the deploy-to-goldline skill
We strongly recommend giving your assistant the skill below. Without a clear guide, an assistant can get stuck, skip important steps, or take a long route to something simple. The skill walks it through each stage of a Goldline deployment: building and pushing images, registering versions, deploying, and checking the result.
Install it
Save the skill to .claude/skills/deploy-to-goldline/SKILL.md in your project:
mkdir -p .claude/skills/deploy-to-goldline
curl -fsSL https://goldline.tech/docs/skills/deploy-to-goldline/SKILL.md \
-o .claude/skills/deploy-to-goldline/SKILL.md
You can also download SKILL.md directly.
Use it
Your assistant should pick the skill up on its own when you ask it to deploy
to Goldline. You can also invoke it explicitly with /deploy-to-goldline.
The skill
SKILL.md
.claude/skills/deploy-to-goldline/SKILL.md
---
name: deploy-to-goldline
description: Build, push, register and deploy an app onto Goldline via the Goldline MCP server. Use whenever the user asks to deploy, ship, release, or roll out something to Goldline — including redeploys after a code change ("deploy this", "ship it").
---
# Deploy to Goldline
Goldline is an AI native deployment orchestration platform: you register what you're
deploying (application → services → versioned manifests), then request a
deployment; Goldline's control plane hands it to an agent on the target cluster.
All Goldline interaction goes through the `goldline` MCP server's tools.
**Goldline is the status authority** — deployment state and diagnostics come
from its tools. **DO NOT** under any circumstances try to debug Goldline deployments
with the user's native kube context, cloud shell, etc. If you cannot find a solution
using the Goldline tools, ask the user to get support from the Goldline team.
Bash is for building/pushing images only.
When a tool's parameters are unclear, read its schema rather than guessing.
(If tools are deferred in your environment, load them with ToolSearch,
e.g. query `+goldline`.)
## Never debug via cluster access
**Do not use the user's kube context — under any circumstances — unless they
explicitly ask you to in that message.**
**This is an abstract SaaS. Users are not expected to have any technical reasoning
or logic as to why deployments may be failing & will NOT have the right answers. It
is up to you the LLM, and the Goldline MCP, to provide the right answers.**
The average user has **no cluster access at all**, so
any diagnosis that depends on it produces an answer they cannot reproduce,
verify, or act on. A conclusion reached through `kubectl` is worse than no
conclusion: it looks authoritative while resting on something outside the
product.
This is **especially** true for users who are engineers, who may have Kube access,
but not to the target cluster. They may not have the right context, or the
right permissions, or even the right cluster. It is **imperative** that you do not
use their kube context, or any other means of cluster access, to debug a Goldline
deployment.
Concretely, never reach for any of these to investigate a Goldline problem:
- `kubectl` in any form — get/describe/logs/exec/patch/apply, any namespace
- `helm` (including `helm show values` against the Goldline chart registry)
- `istioctl`, Envoy admin endpoints, `pilot-agent request`
- ArgoCD — the CLI, the API, or reading `Application` CRs
- Inspecting Gateways, VirtualServices, Services, Endpoints, pods or istiod logs
This holds even when cluster access would obviously be faster, even when a
kube context is already configured and pointing at the right cluster, and even
when Goldline's own errors are vague or unhelpful (`External Call Error`,
`Database Error`, a bare 500, `SUCCEEDED` for something that plainly is not
working). Vague platform errors are **not** a licence to go around the
platform.
Diagnose only with what Goldline exposes: `get_deployment` (`status`, `reason`),
`get_job(job_uuid)`, `query_logs`, `query_metrics`, `get_application_status`,
and the listing/schema tools. If the platform's own surface cannot explain the
failure, **that is a finding in and of itself**. In this case — **say so and stop.**
Report what you observed, what you ruled out, and what you would need in order
to get further. An unexplained failure honestly reported is the correct outcome;
a platform gap surfaced this way is far more valuable to the user than a root
cause you dug out of their cluster, because it is a gap their whole user base is
hitting.
If the user does explicitly hand you the cluster ("use my kube context",
"go look at the pods"), that permission covers **that request only**. Return
to platform-only diagnosis afterwards, and never re-enter the cluster on your
own initiative later in the session.
Never mutate the cluster to work around a Goldline bug — no patching
VirtualServices, no editing Gateways, no `kubectl apply`. Goldline re-renders its
resources on the next deploy, so such fixes are silently reverted and leave the
user worse off than a clear bug report.
**Authentication comes first.** The server requires OAuth: if the only
goldline tools you can see are `authenticate` /
`complete_authentication`, call `authenticate`, give the user the
authorization URL it returns, and wait — the full toolset loads once
they complete the flow in a browser. If their browser errors on the
redirect, have them paste the callback URL back and pass it to
`complete_authentication`. Never try to work around auth with direct
HTTP calls.
## Inspecting Goldline (no deploy)
For read-only questions ("what's registered?", "what's deployed
where?"), resolve context as in step 0, then use the listing tools
directly: `get_all_applications(org_uuid)`, `get_all_services(org_uuid)`,
`get_all_deployments`, `get_service_manifest(service_uuid, version)`,
`query_metrics` / `query_logs`. No versioning, building, or manifest work
is involved — those belong to the deploy path below.
One naming quirk to know: environment/tenant/org tools take
`organisation_uuid`; application/service/deployment tools take `org_uuid`.
Same value, different parameter name.
## 0. Resolve context: org → tenant → environment
Every deploy targets one organisation, tenant, and environment, and nothing
in this repo hardcodes them — resolve them fresh each session (UUIDs differ
between Goldline installations; never reuse UUIDs from earlier
conversations or files).
1. `get_all_organisations` — one org visible: use it. Several: match
against what the user said ("the sandbox", their company name).
2. `get_all_tenants(organisation_uuid)` — same matching rule.
3. `get_all_environments(organisation_uuid, tenant_uuid)` — same again.
If after matching there is still a genuine choice (two plausible
environments, say), ask the user once, then remember the answer for the
rest of the session. Don't re-resolve before every call.
If the target is a **virtual environment**, additionally resolve it with
`get_all_virtual_environments` under the chosen environment — the venv's
parent environment is still required on the deploy request.
## 1. Resolve or create the application and services
- Application: `get_all_applications(org_uuid)`, else `create_application`.
One application groups the services that ship together.
- Services: `get_all_services(org_uuid)`, else
`create_service(org_uuid, service={name, repo_name})`. `repo_name` is the
container-repo name images for this service are pushed under.
- From each service capture `uuid` and `argocd_name` — `argocd_name`
becomes the Kubernetes Deployment/Service name, i.e. the in-cluster DNS
name other services use to reach it.
Redeploys over existing applications/services are normal — resolve, don't
recreate, and don't remark on it.
## 2. Version
Mint a fresh SemVer for each deploy — `0.1.<unix epoch>` works well.
Service versions are immutable: a 409 from version creation means it
exists, so mint a new one rather than reusing. Services that ship together
in one deploy can share the version string.
## 3. Build and push images
Images are pushed to the Goldline registry gateway, never straight to a registry of your
own. The gateway resolves the organisation from the login token and the service from
`<repo_name>`, then forwards to the organisation's configured backing registry,
creating the repository there on first push.
For each service being deployed, from its source directory:
```
docker build --platform linux/amd64 -t <gateway>/<repo_name>:<version> <dir>
docker push <gateway>/<repo_name>:<version>
```
- `<gateway>` is `portal.goldline.tech` for the production Goldline, otherwise ask the user
(it is whatever `CONVOY_REGISTRY_PROXY_HOST` their Goldline CLI (`convoy`) targets). The push path
is exactly `<gateway>/<repo_name>:<version>` with no org or project segment.
- If a push is rejected for auth, ask the user to run `convoy docker login` (with
their organisation's `--sso-provider` if they use one) and try again. Don't hunt
for credentials yourself and don't try plain `docker login`.
- If a push fails with `NAME_UNKNOWN`, the service in step 1 does not exist yet or its
`repo_name` differs from what you tagged. Fix that; don't rename the image to work
around it.
- It is **vital** images are built with the `--platform linux/amd64` flag. If the
user is resistant to this, inform them it is absolutely required for deployment
compatibility.
**Important**: **NEVER** attempt to push straight to any of the user's local
container registries. **ALWAYS** push to the Goldline registry. Goldline has a registry
gateway which forwards images to the organisation's registry. Under **no circumstances**
should you attempt to push straight to that registry — it is very likely the user
either does NOT have access to it, or is connected to another registry completely
separate from Goldline.
### The push target is NOT the image reference
This is the single most common way a Goldline deploy fails, and it fails in a way
that gives you almost no diagnostic. Two different hostnames are involved:
| | Value | Used for |
|---|---|---|
| **Push target** | the gateway, `<gateway>/<repo_name>:<version>` | `docker build -t` and `docker push` only |
| **Image reference** | the org's **backing registry** path | `manifest.image`, and the deploy request's `image` if it takes one |
The gateway forwards the image into the organisation's backing registry. What the
cluster later pulls is that backing-registry path — **not** the gateway hostname.
Writing the gateway host into `manifest.image` produces a deployment that fails at
preflight, before any pod is created.
**Never** put `portal.goldline.tech` or `convoy-registry.pytilia.io` in
`manifest.image` or in a deploy request. They are push endpoints.
### Finding the right registry for an org
Goldline exposes **no** registry configuration anywhere — not on the org, tenant,
environment, application or service record, and not in the variables tiers.
Do not go hunting for a setting; there isn't one. Resolve it like this:
1. **Existing service** — read it off the service's most recent **SUCCEEDED**
deployment (`get_all_deployments`) or its last good manifest
(`get_service_manifest`). Copy the host verbatim and change only the tag.
This is the authoritative answer and it is always available for a redeploy.
2. **New service, other services already deployed in the org** — take the host
the org's other successful deployments use.
3. **Nothing to copy from** — **ask the user.** Do not guess, and do not fall
back to the gateway hostname.
Never carry a registry host over from another organisation, from memory, or
from an example in this document. Rule 1 beats anything written here.
### Verify the push before registering anything
After pushing, confirm the image actually resolved:
```
docker manifest inspect <gateway>/<repo_name>:<version>
```
If that fails, stop — the push did not land, and no amount of changing the
image reference will help. Registering a version for an image that does not
exist burns an immutable version number for nothing.
### Failure signature
A wrong image reference looks like this, and nothing else:
- deployment goes to `FAILED` within a few seconds, with **`reason: null`**
- **no pod is ever created** — `query_logs` shows only the previously running
pod, undisturbed
- the Goldline agent's preflight logs `checking image <host>/<repo>:<version>`
naming the host you supplied
If you see that, compare the failing deployment's `image` against the last
SUCCEEDED deployment's `image` for the same service. If the host differs, that
is the bug.
**Do not respond by cycling registry hostnames.** Each attempt burns a version
and teaches nothing. Change the host **once**, to whatever the last SUCCEEDED
deployment used, and if it still fails, capture the `job_uuid` from the deploy
response, run `get_job(job_uuid)`, and report to the user — the deployment
record does not store the job UUID, so it is only visible in that response and
is the one real diagnostic available.
## 4. Author the manifest — you are the manifest generator
One manifest per service per version. Call the `convoy_generate_manifest`
prompt for the authoritative schema and rules, and build the manifest from
the service's **actual source code** — read it; never invent.
The parts that need judgement:
- **Environment variables → secrets map**: every env var the code reads
goes in `meta.secrets`, valued `true` if it's sensitive (tokens,
passwords — will live in a k8s Secret) or `false` for plain config.
- **Dependencies**: databases, caches, queues, and calls to other
Goldline-managed services (reference their `service_uuid` + version) or
external APIs. Only what the code actually uses.
- **`meta.change_summary`**: one plain line on what changed in this version
versus the last ("Initial deployment" first time). This is the changelog
a human reads in Goldline's UI — base it on the real diff, not the
service's general purpose.
- Never write the string "unknown" — use `null` for unknowable fields.
## 5. Register
Per service, in order: `create_service_version(service_uuid, version)`,
then `upload_service_manifest(service_uuid, manifest)`.
## 6. Deploy
`create_deployment(org_uuid, deployment)` with:
```jsonc
{
"application_uuid": "<uuid>", // omit only for venv deploys
"tenant_uuid": "<uuid>",
"environment_uuid": "<uuid>",
"virtual_environment_uuid": null, // set for venv deploys (child of environment)
"service_deployments": [
{
"service_uuid": "<uuid>",
"service_version": "<version>",
"image": "<registry>/<repo_name>:<version>",
"values": {"env": {"SOME_VAR": "plain value"}},
"secrets": {"API_TOKEN": {"secret_name": "<k8s secret>", "secret_key": "API_TOKEN"}},
"app_route": null // route prefix, for venvs or regular apps/services
}
]
}
```
- The deploy request itself carries image/values/secrets — Goldline does not
read them back out of the manifest (that's governance metadata), and it does
**not** inherit them from the previous deployment. See "Values and variable
scope" below before you send any redeploy.
- `service_deployments` may be a **subset** of the application: services
not listed keep running their current release. Deploy only what changed.
- `values` become helm parameters — keep them simple strings (no commas,
colons or braces).
- `secrets` entries reference k8s Secrets that already exist in the target
namespace; if one doesn't exist, that's a conversation with the user, not
something to work around.
- Service-to-service URLs use the dependency's `argocd_name` and port 80
(e.g. `http://<argocd_name>:80`).
- Venv deploys: set `virtual_environment_uuid`, give HTTP-reachable
services an `app_route`; the response's `hostname` is where they're
served (`https://<hostname><app_route>`).
## Values and variable scope — read before every redeploy
Goldline has three places env vars can live. Two are shared and persistent; the
one that is scoped to the user's app is **not** persistent. Getting this wrong
silently destroys a working service, and Goldline still reports `SUCCEEDED`.
| Where | Scope | Survives the next deploy? |
|---|---|---|
| `values.env` on the deploy request | that one service, that one deploy | **No** |
| `set_environment_variables` | **every deployment into the environment** | Yes |
| `set_tenant_variables` | **every deployment on the tenant** | Yes |
### A redeploy that omits `values` wipes `values`
There is no merge, no inheritance, and no "keep what's there" flag. The
`values` block you send **is** the service's entire config. Omit a variable and
it is gone from the running pod; omit the block and the service comes up with
nothing.
What lives in `values` and therefore gets wiped together: every `env` entry,
`containerPort`, `service.port` — and `app_route` alongside it on the same
`service_deployment`. The classic result is a service that deploys `SUCCEEDED`
and then serves **503**, because it has no port and no route.
**So before ANY redeploy of an existing service:**
1. `get_all_deployments(org_uuid, application_uuid=...)` and find the most
recent deployment that was actually healthy.
2. Read `service_deployments[n].values` and `.app_route` off that record.
3. Send those forward in full, plus whatever is genuinely changing.
Read the values from Goldline every time. Do not reconstruct them from memory,
from earlier in the conversation, or from a payload you sent before — that is
exactly how config gets dropped.
### "Update the env vars" means current vars PLUS the new one
When a user says *"redeploy with this new env var"*, *"update the env vars"*,
*"change LOG_LEVEL to debug"*, they mean the app should keep working. They are
describing a delta, not dictating the whole payload. Sending only the new
variable is never the right reading.
```
WRONG: values = {"env": {"NEW_VAR": "x"}}
RIGHT: values = {<every value from the last healthy deploy>, "env": {<all existing env>, "NEW_VAR": "x"}}
```
The same applies to removing one: send everything except the removed var. Never
respond to "add a variable" with a payload smaller than the current one.
### Never set tenant or environment variables without explicit confirmation
`set_environment_variables` and `set_tenant_variables` apply to **every pod and
every deployment** in that environment or tenant — including services owned by
other teams that the user has never heard of.
- **Do not reach for them to configure one app.** The app-scoped place for env
vars is `values.env` on the deploy request. Always.
- **Beware the name collision.** A user saying "set the environment variables"
or "update my env vars" means the variables their container reads. It does
**not** mean `set_environment_variables`. The tool name matching their phrase
is a trap, not a signal.
- If shared scope genuinely is what they want, **stop and ask first** — state
plainly that it hits every deployment in that environment or tenant, and get
a yes before calling it.
- **Both setters replace, they do not merge.** `get_environment_variables` /
`get_tenant_variables` first and carry every existing entry forward, or you
delete another team's config. Same for `delete_*`, which removes the whole
record rather than one variable.
- Treat `delete_environment_variables` / `delete_tenant_variables` as
destructive: confirm, and quote the exact record you are about to remove.
`containerPort`, `service.port` and `app_route` cannot be set at tenant or
environment scope at all — they are Helm values and routing, so they must be on
every deploy request regardless.
### Symptoms of a wiped deploy
If a service reports `SUCCEEDED` but is unreachable, compare the current
deployment's `values` against an earlier healthy one before anything else. Telltales:
- `app_route: null` and no `containerPort` where an earlier deploy had both
- an `env` block far smaller than the previous deploy's
- **503** on a URL that used to serve
- logs showing the process started fine and listening on its default path
(e.g. Grafana logging `subUrl=` empty when it should be `/my-app`)
That is a dropped `values` payload, not a code regression. Restore the values
from the last healthy deployment record.
## 7. Poll to terminal
Poll `get_deployment(org_uuid, uuid)` every ~5s. Lifecycle:
`PREFLIGHT → DEPLOYING → SUCCEEDED | FAILED | ROLLBACK`.
- `SUCCEEDED` — Goldline's word that the agent applied it and ArgoCD synced.
It does **not** mean the container runs: a crashlooping or unreachable
workload still reports `SUCCEEDED`. Confirm with `query_logs` before
calling a deploy good, and say which one you verified.
- `FAILED`/`ROLLBACK` — diagnose through Goldline: the deployment record's
`reason`, `get_job(job_uuid)` for the job the agent ran, and `query_logs`.
Report findings and propose fixes — don't auto-retry a failed deploy.
- `query_logs` lags by a minute or two. Empty results just after a deploy
mean "not indexed yet", not "nothing running" — wait and re-query before
concluding anything.
- If Goldline's surface can't explain it, stop and report. Do **not** escalate
to kubectl/helm/ArgoCD/istioctl — see "Never debug via cluster access".
Don't preflight the platform before deploying — if something is down, the
deployment status will say so, and that's when you diagnose.
## 8. Verify and report
- Final `get_deployment` shows `SUCCEEDED`.
- `query_logs` on the environment for fresh application logs if useful.
- For an HTTP-reachable service, `curl` its public URL
(`https://<hostname><app_route>`). This is **allowed and encouraged** — the
public URL is part of the product and any user can hit it, unlike cluster
access. It is the one check that distinguishes "synced" from "actually
serving". Mind that a route prefix without a trailing slash often 307s, so
follow redirects before reporting a failure.
- On a redeploy, sanity-check that the config survived: the returned
`service_deployments[n].values` should have **at least** as many `env` entries
as the deployment you carried them from, plus the same `app_route` and
`containerPort`. Fewer means you dropped something — fix it before reporting
success.
- Report concisely: what version went where, deployment status, and the
URL if the service is HTTP-reachable. No step recaps or manifest dumps —
detail only when asked.
Next: deploy your app.