[Discussion] CICD Flow for AI-Workspace

[ShakyaPr]

Background

In standalone mode, AI Workspace and AI Gateway do not directly synchronize artifact state. Because of this, a CI/CD pipeline needs to deploy the runtime artifact to the Gateway and then publish the related design-time and deployment metadata to AI Workspace.

This flow is mainly required for the following AI Workspace artifacts:

• LLM Provider Tenplate
• LLm Provider
• LLM proxy
• MCP Proxy

Goal

• Provide a declarative CI/CD flow that keeps AI Gateway and AI Workspace consistent while treating them as independent components.
• Publishing an artifact to AI Workspace should not trigger a Gateway deployment. Gateway deployment and AI Workspace publishing should remain as separate steps so each operation can be executed, tracked, and validated independently.

Proposed Flow

1. Deploy the runtime artifact to the Gateway
2. Build the AI Workspace artifact using the Gateway deployment information
3. Publish the artifact to AI Workspace - For artifacts with dependencies, such as LLM Proxy, dependencies can be applied first:
ex: When publishing LLM proxy, if the provider & template haven't been created yet, those two will send as dependencies in the artifact which is published to AI workspace

Project Structure

• Project structure is similar to the API Project structure which is used for Devportal & Management portal [1], only difference is the content of artifact.yaml file which is mainly uses to create artifact in AI-workspace by upserting.

dev-llm-proxy/ 
├── .api-platform/ 
│ └── config.yaml 
├── build/ 
│ └── ai-workspace.zip 
├── gateway.yaml 
├── artifact.yaml 
├── definition.yaml 
├── dependencies/       # Uses to provide dependencies which needs to be available to create particular artifact, only applicable for llm provider & proxy artifact projects 
│ ├── provider-template.yaml 
│ └── provider.yaml 
├── docs/ 
└── tests/

• gateway.yaml contains the runtime deployment definition used by AI Gateway.
• artifact.yaml contains the AI Workspace artifact definition and the deployment metadata that should be shown in AI Workspace.
• build/ai-workspace.zip is the generated artifact uploaded to AI workspace.

AI Workspace Artifact Shape

• The same artifact skeleton will be used for other artifacts as well. For more details about artifacts & project structure:
  https://docs.google.com/document/d/1jvyoxzelOtIXQSyNrRjJa1Rqqi4nSQCJ8sXXsbdbj30/edit?usp=sharing

apiVersion: ai-workspace.api-platform.wso2.com/v1alpha1 
kind: LlmProxy 
metadata: 
      name: openai-dev-llm 
spec: 
     displayName: OpenAI Dev LLM 
     version: v1.0 
     organization: acme 
     provider: 
           ref: dev-llm-provider 
     policies:
           - id: basic-ratelimit-policy
              name: basic-ratelimit 
              version: v1.0 
              paths: 
                    - path: /chat/completions 
                       methods:
                              - POST
                       params: 
                              - limits:
                                   - requests: 300
                                     duration: 1m
                    - path: /assistant
                       methods: 
                              - GET
                       params:
                              - limits:
                                    - requests: 100
                                       duration: 1m  
deployments: 
     - gatewayName: dev-ai-gateway 
        status: DEPLOYED 
        configurations: 
               gatewayUrl: api.my-llm-provider.local 
               policyOverrides:                                     # The default policy values can be override for the deployments
                    - ref: basic-ratelimit-policy
                       pathOverrides:
                             - path: /chat/completions
                                methods: 
                                      - POST
                                params:
                                limits:
                                      - requests: 1000
                                        duration: 1m

Note

The deployments section represents the deployment state that was already applied to the Gateway. It should not be treated as an instruction for AI Workspace to deploy the artifact again.

Dependency Handling

• For LLM Proxy, the provider should normally be referenced explicitly. (The same applies for the provider, as it depends on the provider template)

provider: 
       ref: dev-llm-provider

• The proxy flow should not silently create a provider unless that provider is included as a dependency in the project. This avoids creating duplicate providers and keeps ownership clear.

Recommended Approach

• Provider templates are managed separately or included under dependencies/.
• Providers are managed separately or included under dependencies/.
• LLM Proxy and MCP Proxy projects reference existing dependencies.
• CI/CD applies dependencies before deploying the runtime artifact.

Deployment Handling in AI-Workspace

• Since different Gateways can have different endpoints, policies, guardrails, or resource-level configurations, the AI Workspace artifact should preserve deployment-specific configuration.
• This is especially important for future AI Workspace UI support where users need to see which policies and guardrails are applied to each Gateway deployment.

Discussion Points

1. This flow treats AI Workspace and AI Gateway as separate components. Therefore, publishing or updating an artifact in AI Workspace does not automatically propagate changes to the Gateway.

2. For this flow to work correctly, the required Gateway registration should already be configured. If the gateways mentioned in deployment section of artifact.yaml haven't been registered yet, artifact upserting will be failed.
   Automatic propagation from AI Workspace to Gateway can only be supported once proper connectivity between the two components is established.

3. Before executing this flow, the required organization and project should already be created in AI Workspace as AI Workspace artifacts are created/updated under a specific org & project. The CLI flow should validate their availability before publishing the artifact.

4. This approach follows the same folder structure used by the API artifact project for the Devportal/Management Portal CI/CD flows.
   The only additional change is the introduction of a dependencies folder, since some AI Workspace artifacts depend on other artifacts, such as provider templates or providers.

5. If a user needs to manage multiple components from a single project, .api-platform/config.yaml can be used to point to the relevant artifact files for each component. The CLI can then build the required artifacts and publish them to the respective components.

Reference

[1] #1791

[ShakyaPr]

Meeting Notes 15/06/2026

• The files are basically design related metadata & runtime configurations
• For the AI-workspace, file structure won't be changed
• All the runtime (gateway) changes are getting from gateway related yaml file & won't duplicate in the two places
• build command will generate a zip file containing all the required files for AI-workspace & it validates the .config file to find & check he existence of the required files for the artifact
• The CLI tool generates the payload supported by REST API for the AI-workspace
• in the api metadata file, there is a section for the deployments and in there name will be provided of the gws deployed of that artifact
• For the LLM proxies, LLM providers & LLM provider templates we can override the openapi spec definition by providing a new one
• Retieve the provider or provider temlates from runtime configuration file and does not define in metadata yaml file
• Org & project is not defined in the metadata file; project will be provided as argument
• When executes build comamnd, it should gcollect required files

Open Questions

• What would be the name of the project? apiproject/artifactproject or project
• Are we create two structures based on the --type argument or are we using the same project with different content?

TODO:

• Same logic should be applied to Devportal as well, so we dont provide any other details other than exisitng in the file & only extract the data from the two files (runtime & design metadata) in the backend

[ShakyaPr]

metadata.yaml file

• Contains the declarative config data which required for the design
• For the AI Workspace & Management Portal will have deployment section.
• Sample file:

apiVersion: ai-workspace.api-platform.wso2.com/v1alpha
kind: LlmProxy

metadata:
   name: openai-dev-llm

spec:
   displayName: OpenAI Dev LLM
   version: v1.0

deployments:    # Only the name & vhost
   - name: dev-ai-gateway
     configurations:
         vhost:
                   
   - name: prod-ai-gateway
     configurations: ai-workspace.local

[ShakyaPr]

Meeting Notes 15/06/2026

Attendees: Lasantha Samarakoon, Krishan Wijesena, Arshadh Ifthikar, Pubudu Gunathilake, Nuwan Dias, Shakya Rathnaweera, Piumal Rathnayake

• Artifact design related metadata will be included to the metadata.yaml file which is previously known as artifact.yaml
• gateway.yaml should be renamed to runtime.yaml as it contains the runtime related information. The same data won't be duplicate in several places.
• In the metadata.yaml, deployment section will be added to display about gateway related information & for now, no need to consider about adding policy related configs in the metadata.yaml file
• From the CLI ai-workspace publish command, CLI will pick both metadata.yaml & runtime.yaml file to generate the payload supported by AI-WOrkspace create artifact API endpoint
• organization, project fields needs to be removed from the metadata.yaml as they need to be seperate to support declarative flow using these files & since then project will be provided as argument in the publish command.
• ai-workspace build command will validate whether the file paths mentioned in .api-platform/config.yaml is actually available

Open Points

• Are we stick with ai-workspace build or switch to command like validate since what it does is validation before publishing

[ShakyaPr]

Update 17/06/2026

Devportal

• For the devportal, we publish all the details as single .zip file, and uses devportal directory metioned in the .api-platform/config.yaml to generate the zip file.
• There could be three commands: ap devportal rest-api
  • publish - it will publish whole artifact zip file containing docs, content everything
  • docs publish - publish only docs from build zip artifact
  • content publish - publish only content from zip artifact
• Therefore, inside project, there is seperate directory for devportal & it contains required files for Devportal artifacts such as devportal.yaml, definition.yaml, docs etc.
• User can generate initial default devportal artifact using command ap project generate --portal devportal & it uses initial metadata.yaml & runtime.yaml (if required) to generate a devportal artifact. Then user can do the necessary changes to those files & build devportal artifact before publish to portal.
• Depending on the type we provide when initializing the project, it creates either devportals or `mcp-hub' directories.
• Subscription plans should comes under metdata.yaml file & it will be duplicated in devportal.yaml comes under devportal directory as it could be different
• SImilar to subscription plans, other details such as name also duplicate in devportal.yaml as they are edittable in Devportal.

AI-Workspace

• For the AI-workspace we stick with exisitng metadata.yaml & runtime.yaml files & when using build command it validates whether they are actually exists and if yes it generates json payload inside the build directory to use in push command.
• metadata.yaml file is basically for the publisher & runtime.yaml for the gateway
• Subscription plans should comes under metdata.yaml file

Note

• From user perspective, he should be able to generate initial default project by providing a type
• Then do hcnages in metadata.yaml & runtime.yaml as required
• If needs to publish to Devportal or MCP Hub he should generate initial default artifacts from another command
• Do necessary changes of the generated artifact
• Build either publisher/AI-Workspace/MCP Hub/Devportal artifact
• Push or publish depending on the portal