ScriptRunner Connect(SR Connect、SRC)是 Adaptavist 提供的通用、代码优先的集成平台即服务(iPaaS)。其核心方式是编写在托管运行时中执行的 TypeScript 脚本,将脚本连接到外部应用的事件或定时调度,并通过类型化客户端调用其他应用。平台对 Atlassian 及周边业务工具覆盖最深,但不限于此。代码优先意味着集成所需的一切都是脚本、配置记录或 CLI 命令,因此适合智能体操作。
【能否集成某应用】需要两个前提:应用可从互联网访问(SRC 是 SaaS,出站调用来自每个实例的静态 IP,EU 34.251.34.27、US 35.163.23.171,防火墙可加入允许列表;也可通过 DMZ 反向代理;无法开放路径的客户可使用私有云托管,在专用 AWS 账户或客户自有 VPC 内运行);应用提供 HTTP API。非 HTTP 协议需要客户端在前面加一层 HTTP 层(如 SQL 数据库)。入站流量(Webhook)经云网关,没有静态 IP;受限网络发送 Webhook 需要出站互联网访问。OAuth 授权需要浏览器能同时访问应用和 SRC。
【构建块】五个构造:事件监听器接收应用事件并调用脚本;脚本导入 API 连接与应用通信;API 连接替换基础 URL 和认证头,使用连接器(已授权账户);一切位于工作区中。脚本也可手动运行、按计划运行或由另一脚本触发。术语对照包括 workspace、connector、API connection、Managed API、event listener、test event payload、parameters、scheduled trigger、event queue、HEAD、release/deployment、environment、workspace-lock、Egress Firewall 等。
【工作区、HEAD、发布与环境】工作区最多属于一个团队,可见性为私有或公开;语言可为 js、ts 或 ts-strict,应始终使用 ts-strict。HEAD 是工作版本,始终可编辑。发布是 HEAD 的快照,包含脚本、README 及监听器、API 连接、触发器的发布级配置,之后不可更改。版本为 semver 且必须递增。release create -e <env> 一次调用完成发布并部署到环境;environment target-release 仅将环境指向已有发布或回到 HEAD。环境指向 HEAD 或单个发布,并持有自己的环境级配置(各 API 连接的连接器、各事件监听器的连接器与设置状态、通用监听器的 URL 路径、各定时触发器的 CRON 与启用状态、各队列的启用状态、参数值)。在已发布环境中该配置仍可编辑,其余只读;发布后创建的资源在包含它的发布部署前不在范围内。每个工作区初始有一个名为 Default 的环境,位于 HEAD;CLI 以 environment list 报告的 ID 寻址。应保持恰好一个环境位于 HEAD 并在那里开发;通过新发布修复而非编辑旧发布。回滚意味着将环境指向较旧发布或回到 HEAD。脚本可读取 context.environment.name;HEAD 上 context.deployment 为 undefined。
【参数】类型化的按环境值,脚本从 context.environment.vars 读取,允许一层文件夹。共十一种类型(TEXT、NUMBER、LIST、MAP、FOLDER 等),类型之后不可更改。默认值用于初始化新环境和工作区副本,但值本身不复制,运行时也不读取默认值。必需参数在 Web 应用中阻止保存,但 CLI 不强制,因此必需参数仍可能未设置;ev-params.ts 将所有参数声明为可选,脚本在使用前检查值是否存在,必需参数在 JSDoc 中标记 Required: yes。PASSWORD 永不进入脚本:代码和日志看到占位符,真实值仅替换到出站 HTTP 调用中,因此密码无法在代码中哈希、签名或 base64 编码;需要运行时处理的内容应使用以 --masked 创建的 TEXT 参数。未经用户明确许可,不得读取参数值;environment-parameter list 会返回它们,TEXT、MULTILINE_TEXT 和 MAP 参数可能包含非 PASSWORD 类型的机密。查看存在哪些参数可克隆工作区并读取 ev-params.ts(含描述、类型、必需性,不含值)。
【API 连接与 Managed API】API 连接是出站侧:工作区内唯一路径、供应商 API 包、每环境一个连接器。脚本导入它,如 import JiraCloud from './api/jira/cloud'。三层抽象,可用的最高层优先:Managed API(与供应商 API 一一对应的类型化客户端,如 JiraCloud.Issue.getIssue({ issueIdOrKey }));连接上的 managed fetch(提供基础 URL 和认证,自行编写 HTTP);原始全局 fetch(不提供任何内容)。所有连接器应用都有 Managed API;没有公开的逐应用参考,工作区中的类型定义即参考。monday.com 的 Managed API 为 GraphQL 形态,接受 args 和 fields。各产品 API、Managed API 和事件类型在类型定义之外的行为(如返回 410 的弃用方法、事件类型遗漏的字段)记录在 references/product-gotchas/ 下每产品一个文件中;仅当脚本调用该产品或处理其事件时加载。
【事件监听器】事件监听器将应用事件类型绑定到脚本,可选通过连接器和事件队列。事件类型、脚本和队列为工作区级并由发布捕获;连接器、URL 路径和启用状态为环境级。从监听器创建脚本会获得正确的类型化事件。设置由人工在应用中注册 Webhook 完成;CLI 返回 webhookUrl(要注册的回调)和 setupUrl(说明)。多数应用无法以编程方式注册 Webhook。新环境需要重新关联连接器并重做设置:监听器存在且报告 disabled: false,但 URL 路径按环境划分,新环境没有路径,因此 event-listener get -e <env> 显示 urlPath 和 webhookUrl 为 null,监听器已启用但不可达。该环境中第一次 event-listener update 会分配路径(通用监听器用 --url-path,其余用 --disabled false 等无操作更新),生成的 webhookUrl 与 HEAD 不同,需重新注册 Webhook。多数监听器类型根本不需要连接器;event-listener get 报告哪些需要 connectionRequired。但若团队已有该应用的已授权连接器,应附加:设置说明会改进,因为应用基础 URL 来自连接器,Webhook 深链基于它构建。没有时则不加连接器;绝不要仅为给监听器配连接器而创建连接器。测试事件负载用存储的样本运行监听器;新监听器会获得其事件类型的种子 Default 负载。各应用的注册步骤、应用侧可过滤内容及 Webhook 安全方式记录在 references/event-listener-setup/ 下每应用一个文件中;仅在将注册交给用户时加载。
【通用事件监听器】Generic 应用的 HTTP_ENDPOINT 监听器类型,接受全局唯一 URL 路径上的任意 HTTP 请求。
【限制与稳定性】文档中的连接器表、限制、计划和包列表日期为 2026-09-12,并附来源 URL;当答案依赖数字时应重新获取来源。平台出站每实例一个静态 IP,入站 Webhook 无静态 IP;OAuth 需浏览器可访问两端。Managed API 无公开逐应用参考,类型定义即参考。PASSWORD 参数无法在代码中处理。CLI 不强制必需参数。新环境监听器需重新关联连接器并重做设置。