Skip to content
faros Docs
Open console

Enter a topic to search documentation.

    Code API reference

    Resource operations, examples, and schema definitions.

    Prerequisites and scope

    Use the workspace where Code is enabled. Authenticate with a credential authorized for the requested resource and operation. Inspect your deployed API discovery for the exact schema in your hub.

    Interfaces

    The code.faros.sh API includes Connection, Repository, RepositoryCommit, RepositoryCheckout, DeployKey, Collaborator, Package, and RepositoryBuildStatus. Upstream GitHub authorization still applies.

    MCP tools

    After connecting an MCP client , the aggregate endpoint exposes these names with a code__ prefix. Discovery and execution depend on provider enablement, workspace permissions, and the connected GitHub account’s access.

    ToolUse it to
    list_connectionsDiscover configured GitHub connections and their validation status.
    create_connectionCreate a connection referencing an existing credential Secret; the tool does not accept the token itself.
    list_repositoriesList managed repositories, URLs, and readiness.
    create_repositoryRequest a repository on the connected GitHub account.
    delete_repositoryDelete the managed repository; the provider also removes it from GitHub.
    checkout_repositoryRead a repository’s text files at a ref; binary and oversized files are reported as skipped.
    commit_filesWrite or delete files through a RepositoryCommit request.
    add_deploy_keyInstall a deploy key; generated private keys are stored in a workspace Secret.
    add_collaboratorGrant repository access, potentially creating an invitation the recipient must accept.
    remove_collaboratorRevoke access and cancel a pending invitation.
    build_statusInspect the latest build workflow run, jobs, and failure log tails.
    rebuildDispatch the repository’s build workflow again.

    Check resource status after write operations and verify the result in GitHub. Build tools require a configured build workflow. For exact input schemas and behavior, see the MCP implementation .

    Resource schemas

    Resource fields and validation rules are generated from the checked-in schemas, with a downloadable JSON bundle.

    Inspect repositories safely

    Use an authenticated context for the workspace. These reads do not contact GitHub directly; the provider reports the managed resource and its controller status.

    Terminal
    kubectl faros use
kubectl api-resources --api-group=code.faros.sh
kubectl get connections.code.faros.sh,repositories.code.faros.sh,repositorybuildstatuses.code.faros.sh
kubectl explain repositories.code.faros.sh.spec --api-version=code.faros.sh/v1alpha1
kubectl describe repository.code.faros.sh/<repository-name>

    Before a write tool, confirm the Connection is ready and that the linked GitHub account can perform the requested operation. A provider Forbidden/Unauthorized response is not fixed by retrying; repair the workspace permission or GitHub authorization. Build status can remain pending while GitHub processes the workflow, so inspect the status resource and its failure log tail before requesting rebuild.

    Authoritative definitions

    API definitions contain fields and contracts. For Kubernetes-style resources, use kubectl api-resources and kubectl explain RESOURCE against the intended workspace to inspect the installed schema.

    Repository tasks . Return to Code for prerequisites and the provider’s quickstart.