SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsapifox-branch

apifox-branch

Coding & development

View repository

Updated 10-15 12:25

About this skill

Branch Collaboration and AI Writing

Prerequisites: first read ../apifox-cli/SKILL.md. If the old general entry point conflicts with this skill's domain rules, the current CLI help and this skill take precedence.

Specific command parameters are subject to the current CLI help. This skill only supplements the rules most easily misused in branch collaboration: branch context, AI branches, pick-to, write permissions, protected branches, and merge confirmation. After an Agent writes on a branch, it must use the same --branch to read back and verify; do not judge whether a resource exists across branches using the default perspective.

When to Use

  • The user specifies --branch or says to operate on a certain branch.
  • Create, view, update, archive, or delete branches.
  • Create an AI branch and modify source branch resources.
  • Pick-to source branch resources to an AI branch.
  • Merge branches or create/approve merge requests.
  • Encounter AI write permission restrictions.

Command Entry Points

  • Branch management:apifox branch --help
  • Merge requests:apifox merge-request --help
  • Resource commands usually all support --branch <branchName>. Keep the same branch context when querying, creating, updating, and running tests.

First Determine How to Modify

Before writing to a branch, first ask the user clearly which method they want:

  • Directly edit the target branch: suitable when the user explicitly allows direct modification and the target branch has no protection or permission restrictions.
  • Edit via an AI branch: suitable for AI making changes on behalf of the user to endpoints, test cases, test scenarios, or configurations; also suitable when the target branch is protected, external AI direct writing is not enabled, or the user wants to isolate and verify first before merging.

Before starting to write, you must confirm:

  • Project ID.
  • Source branch and target branch.
  • The scope of resources to modify.
  • Whether subsequent creation of a merge request or direct merge is allowed.

AI Branch Workflow

AI branches are used to isolate AI modifications and avoid directly polluting the source branch.

确认源分支和目标变更
  -> 创建 AI 分支
  -> pick-to 已有资源
  -> 在 AI 分支修改
  -> 验证 get/run/report
  -> preview merge-request
  -> 用户确认后 create merge-request 或 merge

Standard steps:

  1. Specify the source when creating an AI branch:--from <sourceBranchName>。
  2. Use the canonical name:ai/年月日-from-来源分支名-功能或模块名, for example ai/20260312-from-main-userRegister。
  3. Before modifying existing resources on the source branch, first use branch pick-to to import them into the AI branch; creating new resources does not require pick-to.
  4. When modifying, querying, and verifying on the AI branch, always include --branch <aiBranchName>。
  5. Verify results by resource type, for example get、run, local reports, or cloud report checks.
  6. Before merging, first merge-request preview, and have the user confirm the scope of impact.
  7. After the user confirms, then merge-request create or branch merge; when the target main branch is protected, prefer a merge request.

AI Branch Notes:

  • An AI branch is initially empty and will not automatically copy all resources from the source branch.
  • branch get may return type: SPRINT and isAiBranch: true; this does not mean --type sprintshould be used during operations. AI branch-related operations should still use --type ai。

Branch Parameter Rules

  • Prefer using the branch name:--branch <branchName>。
  • Pure numeric branchId is compatible, but the branch name is more intuitive and clearer in logs and troubleshooting.
  • Within the same task, querying, creating, updating, and running tests must carry the same branch context, to avoid being unable to find resources from the main/default perspective.

pick-to rules

  • Must carry --type ai。
  • Only supports importing from the main branch or regular iteration branches into an AI branch.
  • Cannot import into the main branch.
  • Cannot use an AI branch as the source branch.
  • Use --include-endpoint-cases to also import interface test cases when importing interfaces.

Write permission rules

  • The main branch, iteration branches, and common branches may require enabling "External AI edit permission".
  • Typical error messages include Automation caller branch required。
  • Creating an AI branch may succeed, but writing content to the AI branch may still fail because "Allow AI to modify AI branch content" is turned off.
  • When encountering write restrictions, do not automatically switch strategies; let the user choose to enable direct edit permission, or switch to using an AI branch.
  • When the target main branch is protected, prefer merge-request preview/create, do not directly branch merge。

Non-violable rules

  1. Do not create an AI branch without user confirmation.
  2. Do not modify existing resources of the source branch in an AI branch without pick-to first.
  3. Do not omit in branch tasks --branch <branchName>。
  4. Do not merge, create merge-request, or approve merge request without user confirmation.
  5. Do not delete or archive branches unless the user explicitly requests it.
  6. When encountering Automation caller branch required , you must stop and ask the user to choose a permission strategy; do not automatically create or switch AI branches.

Common recovery

Symptom Handling
get without branch cannot find resources Carry --branch <branchName> and retry
Cannot find source resources in the AI branch First branch pick-to import
projectBranchState has a count but the AI branch page is empty Do not mistakenly assume it has been imported; the AI branch still requires pick-to
run-config returns 404 under the branch After confirming case/endpoint/environment/branch all exist, switch to apifox-cli-checkup
merge blocked by protected branch Switch to merge-request