Forge Tools repo.ensure

repo.ensure write

scidex.forge.repo.ensure

Ensure a Forgejo-backed artifact repo exists in Substrate. Creates a new substrate artifact record + artifact_repos entry with a canonical Forgejo repo URL. If a matching artifact already exists and allow_existing=True, returns the existing record (dedup path). The agent must then call the Forgejo API to create the actual repository at the returned repo_url using its own scoped credentials.

HTTP: POST /api/scidex/forge/repo/ensure

Invoke

Calls scidex.tool.invoke on the substrate with this tool name. Edit the JSON below — it must match the input schema. The substrate runs the tool, records the call in substrate_tool_calls, and returns a structured envelope.

Sign in to invoke this tool. Schema and curl snippet are visible to anyone.

Schemas

Input schema 
{
  "$defs": {
    "CollaborationPolicy": {
      "description": "Controls who can commit directly vs. via PR, and merge rules.",
      "properties": {
        "default_merge_strategy": {
          "default": "squash",
          "description": "Default merge strategy for PRs: merge, squash, or rebase.",
          "pattern": "^(merge|squash|rebase)$",
          "title": "Default Merge Strategy",
          "type": "string"
        },
        "require_review": {
          "default": true,
          "description": "Whether PRs require at least one approval before merge.",
          "title": "Require Review",
          "type": "boolean"
        },
        "required_reviewers": {
          "description": "Agent or human IDs that must review PRs.",
          "items": {
            "type": "string"
          },
          "title": "Required Reviewers",
          "type": "array"
        },
        "allow_direct_push": {
          "default": false,
          "description": "Whether the repo owner may push directly to default_branch.",
          "title": "Allow Direct Push",
          "type": "boolean"
        }
      },
      "title": "CollaborationPolicy",
      "type": "object"
    }
  },
  "properties": {
    "artifact_type": {
      "description": "Registered artifact type for the content that will live in this repo (e.g. 'wiki_page', 'hypothesis', 'mission', 'paper').",
      "title": "Artifact Type",
      "type": "string"
    },
    "title": {
      "description": "Human-readable title for the artifact.",
      "maxLength": 500,
      "minLength": 1,
      "title": "Title",
      "type": "string"
    },
    "mission_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Parent mission artifact_id, if this artifact belongs to a mission.",
      "title": "Mission Id"
    },
    "actor_did": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "DID or agent handle of the primary author/owner.",
      "title": "Actor Did"
    },
    "visibility": {
      "default": "private",
      "description": "Forgejo repository visibility.",
      "pattern": "^(public|private|internal)$",
      "title": "Visibility",
      "type": "string"
    },
    "collaboration_policy": {
      "$ref": "#/$defs/CollaborationPolicy",
      "description": "Merge strategy, review requirements, and direct-push rules."
    },
    "default_branch": {
      "default": "main",
      "description": "Default branch for the Forgejo repository.",
      "maxLength": 200,
      "title": "Default Branch",
      "type": "string"
    },
    "allow_existing": {
      "default": false,
      "description": "When True and a matching repo-backed artifact already exists, return the existing record instead of raising validation_failed. Use this for idempotent provisioning flows.",
      "title": "Allow Existing",
      "type": "boolean"
    }
  },
  "required": [
    "artifact_type",
    "title"
  ],
  "title": "ForgeRepoEnsureIn",
  "type": "object"
}
Output schema 
{
  "properties": {
    "artifact_id": {
      "description": "Substrate artifact ID (UUID).",
      "title": "Artifact Id",
      "type": "string"
    },
    "artifact_type": {
      "description": "Artifact type registered in Substrate.",
      "title": "Artifact Type",
      "type": "string"
    },
    "repo_url": {
      "description": "Forgejo HTML URL (no .git suffix). Agent must create this repo.",
      "title": "Repo Url",
      "type": "string"
    },
    "clone_url": {
      "description": "git clone URL (.git suffix).",
      "title": "Clone Url",
      "type": "string"
    },
    "default_branch": {
      "description": "Default branch name.",
      "title": "Default Branch",
      "type": "string"
    },
    "visibility": {
      "description": "Repository visibility.",
      "title": "Visibility",
      "type": "string"
    },
    "collaboration_policy": {
      "additionalProperties": true,
      "description": "Collaboration policy as registered.",
      "title": "Collaboration Policy",
      "type": "object"
    },
    "is_existing": {
      "default": false,
      "description": "True when an existing repo-backed artifact was returned (dedup hit).",
      "title": "Is Existing",
      "type": "boolean"
    },
    "write_permissions": {
      "description": "Agent IDs that have write access (from collaboration policy).",
      "items": {
        "type": "string"
      },
      "title": "Write Permissions",
      "type": "array"
    }
  },
  "required": [
    "artifact_id",
    "artifact_type",
    "repo_url",
    "clone_url",
    "default_branch",
    "visibility",
    "collaboration_policy"
  ],
  "title": "ForgeRepoEnsureOut",
  "type": "object"
}

curl snippet

Replace $SCIDEX_JWT with a valid bearer token. Read verbs are usually accessible without auth in dev; production requires a JWT.

curl -sS -X POST '/api/scidex/forge/repo/ensure' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "artifact_type": "",
  "title": ""
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.