Skip to main content
POST
启动代码扫描

权限

需要服务用户或个人访问令牌,并在组织级别拥有 UseCodeScans 权限。

行为

将组织中指定代码仓库 (repo_name) 或多个代码仓库 (repos) 的新代码扫描加入队列。扫描调度程序会异步启动扫描;响应将返回扫描记录,其初始 status 为 waiting 或 pending。轮询列出代码扫描以跟踪进度,并在扫描状态变为 completed 后,通过列出代码扫描发现项 (按 scan_id 过滤) 查看结果。 该扫描归属于调用主体 (即发出请求的服务用户或 PAT) 。Enterprise 作用域内的等效操作为启动代码扫描 (Enterprise)。

请求字段

repo_name 和 repos 必须且只能提供其中一个。
  • repo_name:完整的代码仓库名称,例如 owner/repo。该代码仓库必须已通过组织的 Git 集成获得访问权限。
  • host:代码仓库所在的 Git 主机 (如果无法自动推断) 。
  • repos:单次多仓库扫描所涵盖的代码仓库,格式为对象列表,每个对象包含 repo_name 和可选的 host (最多 200 个) 。第一个条目即为该扫描的主代码仓库。
  • profile_id:要应用的扫描 Profile。对于 ingest 模式的 Profile,请使用启动摄取扫描。
  • scan_type:要运行的扫描类型。指定 profile_id 时,必须与该 Profile 的扫描类型一致。默认使用 Profile 的类型;未指定 Profile 的扫描则默认使用 security。非安全扫描类型必须指定 Profile。
  • commit_sha:扫描前要检出的提交。默认使用代码仓库默认分支的最新提交。
  • effort:normal (默认) 采用较低的模型推理强度,并使用更大的调查批次;deep 则运行完整流水线。
  • interactive:设为 true 时,扫描会在威胁建模与调查之间暂停,进入 awaiting_user_input 状态,等待用户审查。默认为 false。仅安全扫描支持交互式审查;其他扫描类型均以无人值守方式运行。
  • platform:扫描会话的运行位置,可以是为组织配置的平台标签 (例如 linux、windows 或 macos) ,也可以是 outpost 池的名称,不区分大小写。若某个名称同时匹配两者,则优先匹配平台。默认使用组织的默认设置。

错误

  • 当 scan_type 与 Profile 不匹配、未提供 Profile 却指定了非安全类 scan_type,或 platform 与任何已配置的平台标签或 outpost 池均不匹配时 (错误响应体中会列出可用值) ,返回 400。
  • 当组织仅允许摄取模式扫描,且未提供 ingest 模式的 Profile 时,返回 403。
  • 当代码仓库或 Profile 对组织不可见时,返回 404。
  • 当组织的扫描待办列表已满时,返回 409。请稍后重试。
  • 当 repo_name 和 repos 同时提供或均未提供,或 repos 为空时,返回 422。

授权

Authorization
string
header
必填

服务用户凭据(前缀:cog_)

路径参数

org_id
string
必填

组织 ID(前缀:org-)

示例:

"org-abc123def456"

请求体

application/json

用于启动新代码扫描的请求体。

commit_sha
string | null

扫描前要检出的 commit。

effort
enum<string> | null

扫描强度:'normal'(默认)使用较低的模型推理强度,并采用较大的调查批次;'deep' 运行完整流水线。

可用选项:
normal,
deep
host
string | null

代码仓库的 Git 托管平台(如已知)。

interactive
boolean
默认值:false

为 true 时,扫描会在威胁建模完成后、调查开始前暂停,供用户审核。

new_budget
NewScanBudget · object | null

为扫描分配独立的 ACU 预算。需要 ManageAccountServiceUsers 和 ManageAcuLimits 权限。

platform
string | null

扫描会话的运行位置:为组织配置的平台标签(例如 'linux'、'windows'、'macos')或 outpost(BYOB)资源池的名称,不区分大小写;当名称同时匹配两者时,平台优先。省略时使用组织默认设置。无法识别的值会被拒绝,并返回 400,错误响应体中会列出可用的平台标签和 outpost 资源池名称。

Maximum string length: 128
profile_id
string | null

应用于此次扫描的扫描 Profile。

repo_name
string | null

要扫描的代码仓库的完整名称。repo_name 和 repos 必须且只能提供一个。

repos
ScanRepoRequest · object[] | null

一次扫描涵盖的仓库;第一项为此次扫描的主代码仓库。repo_name 和 repos 必须且只能提供一个。

Maximum array length: 200
scan_type
enum<string> | null

要运行的 scan type。提供 Profile 时,必须与其 scan type 一致,默认使用 Profile 的类型;未提供 Profile 时,默认为 'security'。非安全类型的扫描必须提供 Profile,否则请求会被拒绝。

可用选项:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
cleanup,
telemetry,
accessibility,
compliance,
general,
migration-docs

响应

成功响应

一次代码扫描。

created_at
integer
必填

扫描的创建时间(Unix 秒)。

effort
enum<string>
必填

扫描强度:'normal' 使用较低的模型推理强度,并以较大的批次进行调查;'deep' 运行完整流水线。

可用选项:
normal,
deep
host
string | null
必填

代码仓库的 Git 托管平台(如已知)。

org_id
string
必填

该扫描所属的组织。

profile
CodeScanProfileResponse · object | null
必填

扫描所使用的 Profile(如有)。

repo_name
string
必填

扫描的主代码仓库。多代码仓库扫描还会涵盖此处未列出的其他代码仓库。

scan_id
string
必填

扫描的唯一标识符。

scan_type
enum<string>
必填

扫描类型,在创建时确定。

可用选项:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
cleanup,
telemetry,
accessibility,
compliance,
general,
migration-docs
status
enum<string>
必填

扫描状态:waiting、pending、running、awaiting_user_input、completed、failed 或 cancelled。

可用选项:
waiting,
pending,
running,
awaiting_user_input,
completed,
failed,
cancelled
url
string
必填

Devin webapp 中扫描页面的 URL。

outpost_pool_id
string | null

运行扫描会话的 outpost 资源池(若已设置)。

platform
string | null

运行扫描会话的托管平台标签。扫描在 outpost 资源池或组织默认环境中运行时为 Null。

repo_full_name
string | null

包含主机名的主要代码仓库标识(例如 github.com/org/repo)。Perforce depot 没有 Git 主机,因此为 Null。