Detect a repository's build settings

POST

/api/v1/projects/detect

curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/projects/detect \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "main", "provider": "github", "repo_url": "https://codeberg.org/acme/site", "root_directory": "apps/site", "token": "example" }'

Reads a repository from its https URL and proposes the branch, root directory, framework, package manager, build command and output folder, each with the evidence behind it (source) and whether it was read from the repository or is our default (kind). checks lists what will stop the site from building or running as a static site. Only what detection needs is read: the refs, one shallow blobless fetch of the trees, and a few small files. The host must be public (private, link-local, metadata and reserved addresses are refused at connect time), redirects must stay on the same host, and the whole read is limited in size and time. Limited per team. 422 GIT_VALIDATION_FAILED carries details.git_error_code: auth_required (private or missing, no token sent), auth_failed (the token was refused), repo_not_found, host_not_found, host_not_allowed, timeout, too_large, connection_failed, unknown.

Authorizations

• BearerAuth

Request Body

Repository to read

Media type application/json

object

branch

Branch to read. Omit to read the repository’s default branch.

string

<= 255 characters

Example

main

provider

Provider picks the username the token is sent with (e.g. oauth2 for GitLab).

string

Allowed values: github gitlab bitbucket codeberg

repo_url

required

RepoURL is the repository’s https clone URL.

string

<= 2048 characters

Example

https://codeberg.org/acme/site

root_directory

RootDirectory is the folder to detect in. Omit to let detection find it.

string

<= 255 characters

Example

apps/site

token

Token for a private repository. Used for this request only, never stored or logged.

string

<= 500 characters

Responses

200

OK

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

checks

Array<object>

object

code

string

fix

object

file

string

setting

string

snippet

string

value

string

message

string

severity

string

Allowed values: blocking warning

title

Title is the check’s own heading, when it has one; the setup page otherwise heads it by its severity.

string

duration_ms

integer

repo

object

branches

Array<string>

branches_truncated

boolean

commit

Commit is the full id of the commit detection read, on the chosen branch.

string

default_branch

string

reachable

boolean

visibility

string

Allowed values: public private unknown

settings

object

branch

Branch is only set when detection knew the repository’s branches (the Git URL path).

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

build_command

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

framework

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

output_dir

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

package_manager

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

root_directory

object

candidates

Candidates lists the folders to choose from when a repository holds several apps. Only on root_directory.

Array<string>

kind

Kind is detected, default or requested.

string

Allowed values: detected default requested

label

Label is a human name for Value, e.g. “Astro 5”. Only on the framework.

string

source

Source says where Value came from, in words: “found astro.config.mjs”.

string

value

Value is the setting. null means there is nothing to set (no framework we know, no package manager because there is no package.json). An empty string is a real value: no build command, or the top of the repository.

string

Example

{
  "data": {
    "checks": [
      {
        "severity": "blocking"
      }
    ],
    "repo": {
      "visibility": "public"
    },
    "settings": {
      "branch": {
        "kind": "detected"
      },
      "build_command": {
        "kind": "detected"
      },
      "framework": {
        "kind": "detected"
      },
      "output_dir": {
        "kind": "detected"
      },
      "package_manager": {
        "kind": "detected"
      },
      "root_directory": {
        "kind": "detected"
      }
    }
  }
}

400

Invalid input; details.field names the field

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

403

Forbidden

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

422

GIT_VALIDATION_FAILED with details.git_error_code

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

429

RATE_LIMIT_EXCEEDED: too many detections for this team

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}