Skip to content

Automate browser based workflows with AI

feat(tagging): add ?tags= filter to GET /workflows (SKY-10103) (#6334)

Trevor Cheung32e3febfdc52
diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.py
index 171a8f9b3..11cf653a3 100644
--- a/skyvern/forge/sdk/db/repositories/workflows.py
+++ b/skyvern/forge/sdk/db/repositories/workflows.py
@@ -27,12 +27,14 @@ from skyvern.forge.sdk.db.models import (
WorkflowParameterModel,
WorkflowRunModel,
WorkflowScheduleModel,
+ WorkflowTagEventModel,
WorkflowTemplateModel,
)
from skyvern.forge.sdk.db.repositories.workflow_parameters import WorkflowParametersRepository
from skyvern.forge.sdk.db.utils import convert_to_workflow, nullable_column_equals, serialize_proxy_location
from skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock, WhileLoopBlock
from skyvern.forge.sdk.workflow.models.parameter import OutputParameter
+from skyvern.forge.sdk.workflow.models.tags import TagEventType
from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinition
from skyvern.schemas.runs import ProxyLocationInput
from skyvern.schemas.workflows import WorkflowStatus
@@ -411,6 +413,7 @@ class WorkflowsRepository(BaseRepository):
search_key: str | None = None,
folder_id: str | None = None,
statuses: list[WorkflowStatus] | None = None,
+ workflow_tags: list[tuple[str, str]] | None = None,
) -> list[Workflow]:
"""
Get all workflows with the latest version for the organization.
@@ -421,6 +424,14 @@ class WorkflowsRepository(BaseRepository):
workflow parameter metadata (key, description, and default_value).
- If `search_key` is not provided, no search filtering is applied.
- Parameter metadata search excludes soft-deleted parameter rows across parameter tables.
+
+ Tag filtering (`workflow_tags`):
+ - A list of (key, value) pairs. Pairs are grouped by key; the filter is AND
+ across distinct keys and OR within a key's values. One semi-join subquery is
+ emitted per distinct key — normalized event rows can't satisfy two `key=`
+ predicates at once, so a single conjunctive subquery would match nothing.
+ - Matches only the current value of each tag: superseded and soft-deleted
+ event rows are excluded, mirroring the active-tag read path.
"""
if page < 1:
raise ValueError(f"Page must be greater than 0, got {page}")
@@ -469,6 +480,22 @@ class WorkflowsRepository(BaseRepository):
main_query = main_query.where(WorkflowModel.status.in_(statuses))
if folder_id:
main_query = main_query.where(WorkflowModel.folder_id == folder_id)
+ if workflow_tags:
+ values_by_key: dict[str, list[str]] = {}
+ for key, value in workflow_tags:
+ values_by_key.setdefault(key, []).append(value)
+ for key, values in values_by_key.items():
+ main_query = main_query.where(
+ WorkflowModel.workflow_permanent_id.in_(
+ select(WorkflowTagEventModel.workflow_permanent_id)
+ .where(WorkflowTagEventModel.organization_id == organization_id)
+ .where(WorkflowTagEventModel.deleted_at.is_(None))
+ .where(WorkflowTagEventModel.superseded_at.is_(None))
+ .where(WorkflowTagEventModel.event_type == TagEventType.SET.value)
+ .where(WorkflowTagEventModel.key == key)
+ .where(WorkflowTagEventModel.value.in_(values))
+ )
+ )
if search_key:
search_like = f"%{search_key}%"
title_like = WorkflowModel.title.ilike(search_like)
diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py
index 6fbaa803d..0f3cbe52d 100644
--- a/skyvern/forge/sdk/routes/agent_protocol.py
+++ b/skyvern/forge/sdk/routes/agent_protocol.py
@@ -3791,6 +3791,19 @@ async def get_workflows(
),
folder_id: str | None = Query(None, description="Filter workflows by folder ID"),
status: Annotated[list[WorkflowStatus] | None, Query()] = None,
+ tags: Annotated[
+ list[str] | None,
+ Query(
+ max_length=20,
+ description=(
+ "Filter by tags as `key:value` pairs. Repeat the param or comma-separate "
+ "(`?tags=env:prod,env:staging`). AND across distinct keys, OR within a key "
+ "(`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). "
+ "Matches current tag values only. Not supported with `template=true`."
+ ),
+ examples=["env:prod", "customer:acme,env:prod"],
+ ),
+ ] = None,
current_org: Organization = Depends(org_auth_service.get_current_org),
template: bool = Query(False),
) -> list[Workflow]:
@@ -3812,6 +3825,32 @@ async def get_workflows(
# Default to published and draft if no status filter provided
effective_statuses = status if status else [WorkflowStatus.published, WorkflowStatus.draft]
+ # A lone empty value (?tags= with nothing else) is a no-op for backward
+ # compat; any blank segment alongside real ones — comma (env:prod,) or
+ # repeated (tags=env:prod&tags=) — is malformed, so both encodings 400 alike.
+ tag_groups = tags or []
+ if tag_groups == [""]:
+ tag_groups = []
+ workflow_tags: list[tuple[str, str]] = []
+ for raw_group in tag_groups:
+ for raw_pair in raw_group.split(","):
+ pair = raw_pair.strip()
+ tag_key, sep, tag_value = pair.partition(":")
+ tag_key, tag_value = tag_key.strip(), tag_value.strip()
+ if not sep or not tag_key or not tag_value:
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail=f"Invalid tag filter '{pair}'; expected 'key:value'.",
+ )
+ workflow_tags.append((tag_key, tag_value))
+
+ if template and workflow_tags:
+ # Templates are global; tags are org-scoped, so the two can't combine.
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail="tags filter is not supported with template=true",
+ )
+
if template:
global_workflows_permanent_ids = await app.STORAGE.retrieve_global_workflows()
if not global_workflows_permanent_ids:
@@ -3841,6 +3880,7 @@ async def get_workflows(
search_key=effective_search,
folder_id=folder_id,
statuses=effective_statuses,
+ workflow_tags=workflow_tags or None,
)
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 02a848b4b..6468a4664 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -4083,6 +4083,7 @@ class WorkflowService:
search_key: str | None = None,
folder_id: str | None = None,
statuses: list[WorkflowStatus] | None = None,
+ workflow_tags: list[tuple[str, str]] | None = None,
) -> list[Workflow]:
"""
Get all workflows with the latest version for the organization.
@@ -4090,6 +4091,7 @@ class WorkflowService:
Args:
search_key: Unified search term for title, folder name, and parameter metadata.
folder_id: Filter workflows by folder ID.
+ workflow_tags: (key, value) tag filters; AND across keys, OR within a key.
"""
return await app.DATABASE.workflows.get_workflows_by_organization_id(
organization_id=organization_id,
@@ -4101,6 +4103,7 @@ class WorkflowService:
search_key=search_key,
folder_id=folder_id,
statuses=statuses,
+ workflow_tags=workflow_tags,
)
async def update_workflow_definition(
diff --git a/tests/unit/test_workflows_list_tag_filter.py b/tests/unit/test_workflows_list_tag_filter.py
new file mode 100644
index 000000000..dac303e47
--- /dev/null
+++ b/tests/unit/test_workflows_list_tag_filter.py
@@ -0,0 +1,307 @@
+"""Tag-filter tests for the GET /workflows ?tags= filter.
+
+Two layers:
+- Repository tests run against in-memory SQLite so the per-key semi-join SQL
+ executes against real rows — the only way to verify superseded/soft-delete
+ exclusion and the AND-across-keys / OR-within-key semantics.
+- Route tests mount the real FastAPI router with a mocked WORKFLOW_SERVICE so
+ the ?tags= query param registration and key:value parsing (incl. 400s) are
+ exercised — repo-only tests can't catch route-registration or parser bugs.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import AsyncGenerator
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+import pytest_asyncio
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from skyvern.forge.sdk.db.base_alchemy_db import BaseAlchemyDB
+from skyvern.forge.sdk.db.models import Base, WorkflowModel, WorkflowTagEventModel
+from skyvern.forge.sdk.db.repositories.workflows import WorkflowsRepository
+from skyvern.forge.sdk.schemas.organizations import Organization
+from skyvern.forge.sdk.services import org_auth_service
+from skyvern.forge.sdk.workflow.models.tags import TagEventType, TagSource
+
+ORG_ID = "o_test"
+OTHER_ORG_ID = "o_other"
+
+
+@pytest_asyncio.fixture
+async def engine() -> AsyncGenerator[AsyncEngine]:
+ eng = create_async_engine("sqlite+aiosqlite:///:memory:")
+ async with eng.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all)
+ yield eng
+ await eng.dispose()
+
+
+@pytest_asyncio.fixture
+async def repo(engine: AsyncEngine) -> WorkflowsRepository:
+ db = BaseAlchemyDB(engine)
+ return WorkflowsRepository(db.Session, debug_enabled=False)
+
+
+async def _create_workflow(
+ repo: WorkflowsRepository,
+ *,
+ wpid: str,
+ title: str,
+ organization_id: str = ORG_ID,
+) -> None:
+ async with repo.Session() as session:
+ session.add(
+ WorkflowModel(
+ workflow_id=f"wid_{wpid}",
+ workflow_permanent_id=wpid,
+ organization_id=organization_id,
+ title=title,
+ workflow_definition={"blocks": [], "parameters": []},
+ status="published",
+ version=1,
+ )
+ )
+ await session.commit()
+
+
+async def _set_tag(
+ repo: WorkflowsRepository,
+ *,
+ wpid: str,
+ key: str,
+ value: str,
+ organization_id: str = ORG_ID,
+ superseded_at: datetime | None = None,
+ deleted_at: datetime | None = None,
+ event_type: TagEventType = TagEventType.SET,
+) -> None:
+ async with repo.Session() as session:
+ session.add(
+ WorkflowTagEventModel(
+ workflow_permanent_id=wpid,
+ organization_id=organization_id,
+ key=key,
+ value=value if event_type == TagEventType.SET else None,
+ event_type=event_type.value,
+ set_at=datetime.now(timezone.utc),
+ set_by="user_test",
+ source=TagSource.MANUAL.value,
+ superseded_at=superseded_at,
+ deleted_at=deleted_at,
+ )
+ )
+ await session.commit()
+
+
+async def _wpids(repo: WorkflowsRepository, **kwargs) -> set[str]:
+ workflows = await repo.get_workflows_by_organization_id(organization_id=ORG_ID, **kwargs)
+ return {w.workflow_permanent_id for w in workflows}
+
+
+async def test_no_tags_param_returns_all(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _create_workflow(repo, wpid="wpid_b", title="B")
+
+ assert await _wpids(repo) == {"wpid_a", "wpid_b"}
+ assert await _wpids(repo, workflow_tags=None) == {"wpid_a", "wpid_b"}
+ assert await _wpids(repo, workflow_tags=[]) == {"wpid_a", "wpid_b"}
+
+
+async def test_single_key_single_value(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _create_workflow(repo, wpid="wpid_b", title="B")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_b", key="env", value="staging")
+
+ assert await _wpids(repo, workflow_tags=[("env", "prod")]) == {"wpid_a"}
+
+
+async def test_or_within_key(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _create_workflow(repo, wpid="wpid_b", title="B")
+ await _create_workflow(repo, wpid="wpid_c", title="C")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_b", key="env", value="staging")
+ await _set_tag(repo, wpid="wpid_c", key="env", value="dev")
+
+ result = await _wpids(repo, workflow_tags=[("env", "prod"), ("env", "staging")])
+ assert result == {"wpid_a", "wpid_b"}
+
+
+async def test_and_across_keys(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_both", title="Both")
+ await _create_workflow(repo, wpid="wpid_env_only", title="EnvOnly")
+ await _create_workflow(repo, wpid="wpid_cust_only", title="CustOnly")
+ await _set_tag(repo, wpid="wpid_both", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_both", key="customer", value="acme")
+ await _set_tag(repo, wpid="wpid_env_only", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_cust_only", key="customer", value="acme")
+
+ result = await _wpids(repo, workflow_tags=[("customer", "acme"), ("env", "prod")])
+ assert result == {"wpid_both"}
+
+
+async def test_superseded_value_excluded(repo: WorkflowsRepository) -> None:
+ """Re-tagged env:prod -> env:staging must not match the stale prod value."""
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod", superseded_at=datetime.now(timezone.utc))
+ await _set_tag(repo, wpid="wpid_a", key="env", value="staging")
+
+ assert await _wpids(repo, workflow_tags=[("env", "prod")]) == set()
+ assert await _wpids(repo, workflow_tags=[("env", "staging")]) == {"wpid_a"}
+
+
+async def test_deleted_tag_excluded(repo: WorkflowsRepository) -> None:
+ """A soft-deleted (deleted_at set) tag event row must not match."""
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod", deleted_at=datetime.now(timezone.utc))
+
+ assert await _wpids(repo, workflow_tags=[("env", "prod")]) == set()
+
+
+async def test_delete_event_excluded(repo: WorkflowsRepository) -> None:
+ """A DELETE event row (value NULL, event_type='delete') must not match."""
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod", superseded_at=datetime.now(timezone.utc))
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod", event_type=TagEventType.DELETE)
+
+ assert await _wpids(repo, workflow_tags=[("env", "prod")]) == set()
+
+
+async def test_cross_org_isolation(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_mine", title="Mine", organization_id=ORG_ID)
+ await _set_tag(repo, wpid="wpid_mine", key="env", value="prod", organization_id=ORG_ID)
+ # Different org, same tag — must not leak into ORG_ID's results.
+ await _create_workflow(repo, wpid="wpid_theirs", title="Theirs", organization_id=OTHER_ORG_ID)
+ await _set_tag(repo, wpid="wpid_theirs", key="env", value="prod", organization_id=OTHER_ORG_ID)
+
+ assert await _wpids(repo, workflow_tags=[("env", "prod")]) == {"wpid_mine"}
+
+
+async def test_tag_filter_composes_with_search_key(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="alpha")
+ await _create_workflow(repo, wpid="wpid_b", title="beta")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_b", key="env", value="prod")
+
+ result = await _wpids(repo, workflow_tags=[("env", "prod")], search_key="alpha")
+ assert result == {"wpid_a"}
+
+
+def _make_org(org_id: str = ORG_ID) -> Organization:
+ now = datetime.now(timezone.utc)
+ return Organization(
+ organization_id=org_id,
+ organization_name="Test Org",
+ created_at=now,
+ modified_at=now,
+ )
+
+
+def route_client(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+ """Mount the real GET /workflows route with a mocked WORKFLOW_SERVICE.
+
+ Captures the workflow_tags value the route passes to the service so the
+ ?tags= registration + key:value parsing (including 400s) are tested end to
+ end. Importing the router module also guards against the route-registration
+ failure caught in debate round 1 — a bad param declaration raises at import.
+ """
+ from skyvern.forge.sdk.routes import agent_protocol as ap
+ from skyvern.forge.sdk.routes.routers import base_router
+
+ captured: dict[str, object] = {}
+
+ async def _get_workflows_by_organization_id(**kwargs: object) -> list:
+ captured["workflow_tags"] = kwargs.get("workflow_tags")
+ return []
+
+ service_mock = MagicMock()
+ service_mock.get_workflows_by_organization_id = AsyncMock(side_effect=_get_workflows_by_organization_id)
+
+ app_mock = MagicMock()
+ app_mock.WORKFLOW_SERVICE = service_mock
+ # template=true path: empty global list short-circuits to [] before any service call.
+ app_mock.STORAGE.retrieve_global_workflows = AsyncMock(return_value=[])
+ monkeypatch.setattr(ap, "app", app_mock)
+
+ test_app = FastAPI()
+ test_app.include_router(base_router, prefix="/v1")
+ test_app.dependency_overrides[org_auth_service.get_current_org] = lambda: _make_org(ORG_ID)
+
+ client = TestClient(test_app)
+ client.captured = captured # type: ignore[attr-defined]
+ return client
+
+
+def test_route_no_tags_param_passes_none(route_client: TestClient) -> None:
+ resp = route_client.get("/v1/workflows")
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] is None # type: ignore[attr-defined]
+
+
+def test_route_empty_tags_is_noop(route_client: TestClient) -> None:
+ resp = route_client.get("/v1/workflows", params=[("tags", "")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] is None # type: ignore[attr-defined]
+
+
+def test_route_comma_and_repeated_parse_identically(route_client: TestClient) -> None:
+ comma = route_client.get("/v1/workflows", params=[("tags", "customer:acme,env:prod")])
+ assert comma.status_code == 200, comma.text
+ comma_tags = route_client.captured["workflow_tags"] # type: ignore[attr-defined]
+
+ repeated = route_client.get("/v1/workflows", params=[("tags", "customer:acme"), ("tags", "env:prod")])
+ assert repeated.status_code == 200, repeated.text
+ repeated_tags = route_client.captured["workflow_tags"] # type: ignore[attr-defined]
+
+ assert comma_tags == [("customer", "acme"), ("env", "prod")]
+ assert repeated_tags == comma_tags
+
+
+def test_route_value_keeps_later_colons(route_client: TestClient) -> None:
+ resp = route_client.get("/v1/workflows", params=[("tags", "url:http://x:8000")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] == [("url", "http://x:8000")] # type: ignore[attr-defined]
+
+
+ "tags_params",
+ [
+ [("tags", "envprod")], # no colon
+ [("tags", ":prod")], # empty key
+ [("tags", "env:")], # empty value
+ [("tags", "env:prod,")], # trailing blank segment (comma form)
+ [("tags", "env:prod,,customer:acme")], # interior blank segment
+ [("tags", "env:prod"), ("tags", "")], # blank repeated param (must match comma form -> CORR-3)
+ ],
+)
+def test_route_malformed_tags_400(route_client: TestClient, tags_params: list[tuple[str, str]]) -> None:
+ resp = route_client.get("/v1/workflows", params=tags_params)
+ assert resp.status_code == 400, resp.text
+
+
+def test_route_tags_with_template_rejected(route_client: TestClient) -> None:
+ # Templates are global; tags are org-scoped, so combining them is a 400.
+ resp = route_client.get("/v1/workflows", params=[("tags", "env:prod"), ("template", "true")])
+ assert resp.status_code == 400, resp.text
+
+
+def test_route_template_without_tags_allowed(route_client: TestClient) -> None:
+ # template=true alone must still work (no tags filter applied).
+ resp = route_client.get("/v1/workflows", params=[("template", "true")])
+ assert resp.status_code == 200, resp.text