Skip to content

CI/CD Build

In the VS Code with CI/CD deployment option, your CI builds and deploys each project. Talisman provides pipeline templates for GitHub Actions and Azure Pipelines. They build with the talisman-builder image and deploy to Kubernetes with kubectl.

What the pipeline does

Each project has its own pipeline file. It runs on a push to main that changes the project's folder. The files the push changed decide what runs:

Changed in the project The pipeline
Any file except the deployment files below Builds, commits kubernetes.yaml, deploys the first environment
patch.yaml Deploys the first environment, no build
test.kubernetes.yaml or test.patch.yaml Deploys test, no build
prod.kubernetes.yaml or prod.patch.yaml Deploys prod, no build

A manual run, or a push the CI can't compare with an earlier commit (a new branch, a force push, no earlier successful run), builds and deploys the first environment. dev.kubernetes.yaml and dev.patch.yaml are ignored with a warning: the first environment's files have no prefix.

graph LR
    M[Merge to main] --> C{What changed?}
    C -->|source| B[talisman-builder: build and push image]
    B --> K[Commit kubernetes.yaml]
    K --> D1[Deploy first environment]
    C -->|patch.yaml| D1
    C -->|test.*| DT[Deploy test]
    C -->|prod.*| DP[Deploy prod]

Build

  1. talisman-builder compiles the project and pushes the image as <IMAGE_REGISTRY>/<IMAGE_GROUP>/<project>:main-<commit>, where <commit> is the first 7 characters of the commit.
  2. It generates the Kubernetes resources, with the image pinned by digest (tag@digest): every environment that deploys this manifest runs exactly this image.
  3. The pipeline commits them as the project's kubernetes.yaml and pushes to main. The commit message ends with [skip ci], and kubernetes.yaml doesn't trigger the pipeline.

Deploy

Each environment is deployed from its own files on main:

Environment Manifest Patch (optional)
First environment (deploy job dev) kubernetes.yaml patch.yaml
test test.kubernetes.yaml test.patch.yaml
prod prod.kubernetes.yaml prod.patch.yaml

Without a patch, the pipeline runs kubectl apply -f on the manifest. With a patch, it applies both through kustomize (kubectl apply -k) with configuration/kustomization.yaml from your repository, so the patch is merged into the manifest. A patch holds partial resources: replicas, resources, environment variables, ConfigMap and Secret references. See Deployer Engine.

The pipeline writes only kubernetes.yaml. How test.kubernetes.yaml and prod.kubernetes.yaml reach main, and who approves them, is your process.

Set up the pipeline

  1. In Studio for VS Code, generate the project's pipeline file. It's written from the repository's template: templates/github.workflow.yaml to .github/workflows/<project>.yaml, or templates/azure.pipeline.yaml to .azure-pipelines/<project>.yaml.
  2. Set the pipeline's variables and secrets, listed below and in the file's header comment.
  3. Let the pipeline push to main: it commits kubernetes.yaml. If main is protected, allow the pipeline's identity to bypass it, or change that step to open a pull request.
  4. Commit the pipeline file with the project and merge to main.

In Settings → Secrets and variables → Actions:

Name Kind Value
IMAGE_REGISTRY Variable The registry host, for example ghcr.io (required)
IMAGE_GROUP Variable The group or namespace in it, lowercase (required)
TALISMAN_BUILDER_IMAGE Variable Optional: the talisman-builder image to use
KUBERNETES_NAMESPACE Variable Optional: the namespace to apply to (default: the kubeconfig's)
IMAGE_REGISTRY_USERNAME Secret The registry user; not needed for ghcr.io
IMAGE_REGISTRY_PASSWORD Secret Its password or token; not needed for ghcr.io
KUBECONFIG Secret The kubeconfig of the cluster to deploy to; without it, the deploy is skipped with a warning

Each deploy job runs in the GitHub environment of its name: dev for the first environment, then test and prod (Settings → Environments). An environment's own KUBECONFIG and KUBERNETES_NAMESPACE replace the repository's, and its protection rules apply, for example required reviewers for prod. Workflow permissions must allow the token to write.

  1. Register the pipeline: Pipelines → New pipeline → your repository → Existing Azure Pipelines YAML file → .azure-pipelines/<project>.yaml.
  2. In Pipelines → Library, create a variable group named talisman with IMAGE_REGISTRY, IMAGE_GROUP, IMAGE_REGISTRY_USERNAME and IMAGE_REGISTRY_PASSWORD (a secret variable), and allow the pipeline to use it.
  3. In Project settings → Service connections, create a Kubernetes service connection named talisman-kubernetes: the cluster and namespace to deploy to.
  4. In Project settings → Repositories → your repository → Security, give the project's Build Service Contribute.

Note

The template uses one service connection for every environment. To deploy test and prod to other clusters, edit the deploy job.

Customise the pipeline

  • Every project: edit the template in templates/ and generate the pipeline files again.
  • One project: edit its pipeline file. Generating it again overwrites your changes.

Add your own steps, such as image scanning and signing, around the build and deploy steps. To change the base image, see Base Image. The image's platform is linux/amd64 (JIB_FROM_PLATFORMS in the pipeline file).

Self-hosted GitHub runners need Linux with Docker and kubectl; self-hosted Azure agents need jq and kubectl.

Talisman Servers

The pipeline deploys every environment, so a Talisman Server installed beside it runs Control Plane only, to operate and observe. Deploy each environment either from the pipeline or from a Talisman Server, never both.