Git Configuration

This API lets you read and change the organization-wide Git settings, and the Git scope of a team. Settings of a single repository are managed with Git Repositories.

Settings sections

The organization default covers eleven setting sections. A repository follows the default for each section unless it overrides it. Four sections are organization-wide only and cannot be set per repository: include_file_extensions, active_branches_duration, issue_start_time and bot_pr_attribution.

Changing excluded branches, excluded base branches, excluded file extensions, included file extensions, release detection or coding time strategy recomputes history asynchronously. For release detection and coding time strategy, backfill_days controls how far back history is recomputed: 90 (the default) recomputes the last 90 days and 1 skips the recompute.

A field marked required is required whenever its section is sent.

releases_detection

How releases are detected. Changing this setting recomputes history asynchronously.

draft_pull_requests

How draft pull requests are recognized; a pull request matching either rule is a draft.

default_branch

The branch every merge comparison is based on.

exclude_branches

A list of regular expressions. Changing this setting recomputes history asynchronously.

exclude_base_branches

A list of regular expressions. Changing this setting recomputes history asynchronously.

exclude_file_extensions

A list of regular expressions. Changing this setting recomputes history asynchronously.

include_file_extensions

The files scanned: only files matching one of the patterns, out of those left after the excluded file extensions. Changing this setting recomputes history asynchronously. Organization-wide only: it cannot be set per repository.

active_branches_duration

How long a branch stays active after its last update before it becomes stale. Organization-wide only: it cannot be set per repository.

coding_time_strategy

When coding time starts. Changing this setting recomputes history asynchronously.

issue_start_time

Which transition to the in progress state is the issue start time; it affects coding time and MTTR. Organization-wide only: it cannot be set per repository.

bot_pr_attribution

Who a pull request opened by a bot is attributed to. Organization-wide only: it cannot be set per repository.

When you read the configuration, releases_detection.method can also be deployment, which is read-only.

Team Git scope

A team's Git scope is the set of repositories and services assigned to it. The team Git scope endpoints below read and change the team's own scope: scope assigned to descendant teams is not included, and a group (a team that has child teams) is addressed by its own team ID like any other team. Only monitored repositories are listed.

Get Git Configuration

Reads the organization-wide default of every repository setting section, and the organization-wide only sections (bot-authored pull request attribution, included file extensions, active branches duration, issue start time). A repository without an override of a section follows this default

HTTP request

GET  https://public-api.linearb.io/api/v1/git/config

Responses

200 - Successful Response

{
  "settings": {
    "releases_detection": {
      "method": "tags",
      "pattern": ".*"
    },
    "draft_pull_requests": {
      "labels": [
        "wip",
        "do not merge"
      ],
      "title_pattern": "^.*wip.*$"
    },
    "default_branch": {
      "branch_name": "main"
    },
    "exclude_branches": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "exclude_base_branches": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "exclude_file_extensions": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "coding_time_strategy": {
      "method": "first_commit"
    },
    "bot_pr_attribution": {
      "method": "merge_actor"
    },
    "include_file_extensions": {
      "patterns": [
        "\\.js$",
        "\\.ts$"
      ]
    },
    "active_branches_duration": {
      "days": 7
    },
    "issue_start_time": {
      "method": "last_transition"
    }
  }
}

400 - Bad Request - an unknown section, an invalid value or regular expression

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Update Git Configuration

Writes the organization-wide default of each section sent; sections not sent are left as they are. Repositories that override a section are unaffected. Changing excluded branches, excluded base branches, excluded file extensions, release detection or coding time strategy recomputes history asynchronously, and so does changing included file extensions

HTTP request

PATCH  https://public-api.linearb.io/api/v1/git/config

Body parameters

Nested fields marked required are required whenever their parent is sent.

Example

{
  "exclude_branches": {
    "patterns": [
      "^main$",
      "^master$",
      "^release/.*"
    ]
  },
  "releases_detection": {
    "method": "tags",
    "pattern": ".*",
    "backfill_days": 90
  }
}

Responses

200 - Successful Response

{
  "settings": {
    "releases_detection": {
      "method": "tags",
      "pattern": ".*"
    },
    "draft_pull_requests": {
      "labels": [
        "wip",
        "do not merge"
      ],
      "title_pattern": "^.*wip.*$"
    },
    "default_branch": {
      "branch_name": "main"
    },
    "exclude_branches": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "exclude_base_branches": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "exclude_file_extensions": {
      "patterns": [
        "^main$",
        "^release/.*"
      ]
    },
    "coding_time_strategy": {
      "method": "first_commit"
    },
    "bot_pr_attribution": {
      "method": "merge_actor"
    },
    "include_file_extensions": {
      "patterns": [
        "\\.js$",
        "\\.ts$"
      ]
    },
    "active_branches_duration": {
      "days": 7
    },
    "issue_start_time": {
      "method": "last_transition"
    }
  }
}

400 - Bad Request - an unknown section, an invalid value or regular expression

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Get Team Git Scope

Reads the repositories and services assigned to the team itself. Scope assigned to descendant teams is not included; a group is addressed by its own team id

HTTP request

GET  https://public-api.linearb.io/api/v1/git/config/teams/{team_id}/scope

Path parameters

Responses

200 - Successful Response

{
  "team_id": 123,
  "team_name": "Payments",
  "repositories": [
    {
      "id": 101,
      "name": "api",
      "url": "https://github.com/acme/api"
    }
  ],
  "services": [
    {
      "id": 201,
      "name": "checkout"
    }
  ]
}

400 - Bad Request, or an id was refused - repositories not found or not monitored, services not found. A refused write changes nothing

401 - Unauthorized

403 - Forbidden

404 - The team was not found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Replace Team Git Scope

Replaces the team's whole Git scope: each key sent becomes exactly that list, and a key not sent is cleared. At least one key is required; clearing the whole scope is a DELETE

HTTP request

PUT  https://public-api.linearb.io/api/v1/git/config/teams/{team_id}/scope

Path parameters

Body parameters

Example

{
  "repository_ids": [
    101,
    102
  ],
  "service_ids": [
    201
  ]
}

Responses

200 - Successful Response

{
  "team_id": 123,
  "team_name": "Payments",
  "repositories": [
    {
      "id": 101,
      "name": "api",
      "url": "https://github.com/acme/api"
    }
  ],
  "services": [
    {
      "id": 201,
      "name": "checkout"
    }
  ]
}

400 - Bad Request, or an id was refused - repositories not found or not monitored, services not found. A refused write changes nothing

401 - Unauthorized

403 - Forbidden

404 - The team was not found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Update Team Git Scope Keys

Writes each key sent; keys not sent are left as they are. mode=merge (default) replaces each key's whole list; mode=add adds the ids sent to it and removes none

HTTP request

PATCH  https://public-api.linearb.io/api/v1/git/config/teams/{team_id}/scope

Path parameters

Query parameter

Body parameters

Example

{
  "repository_ids": [
    101,
    102
  ],
  "service_ids": [
    201
  ]
}

Add a repository without removing any (mode=add)

{
  "repository_ids": [
    103
  ]
}

Responses

200 - Successful Response

{
  "team_id": 123,
  "team_name": "Payments",
  "repositories": [
    {
      "id": 101,
      "name": "api",
      "url": "https://github.com/acme/api"
    }
  ],
  "services": [
    {
      "id": 201,
      "name": "checkout"
    }
  ]
}

400 - Bad Request, or an id was refused - repositories not found or not monitored, services not found. A refused write changes nothing

401 - Unauthorized

403 - Forbidden

404 - The team was not found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Clear Team Git Scope

Clears the team's whole Git scope - both repositories and services

HTTP request

DELETE  https://public-api.linearb.io/api/v1/git/config/teams/{team_id}/scope

Path parameters

Responses

200 - Successful Response

{
  "team_id": 123,
  "team_name": "Payments",
  "repositories": [
    {
      "id": 101,
      "name": "api",
      "url": "https://github.com/acme/api"
    }
  ],
  "services": [
    {
      "id": 201,
      "name": "checkout"
    }
  ]
}

400 - Bad Request, or an id was refused - repositories not found or not monitored, services not found. A refused write changes nothing

401 - Unauthorized

403 - Forbidden

404 - The team was not found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Clear a Team Git Scope Key

Clears one key of the team's Git scope - the same write as a PATCH sending it as an empty list

HTTP request

DELETE  https://public-api.linearb.io/api/v1/git/config/teams/{team_id}/scope/{scope_key}

Path parameters

Responses

200 - Successful Response

{
  "team_id": 123,
  "team_name": "Payments",
  "repositories": [
    {
      "id": 101,
      "name": "api",
      "url": "https://github.com/acme/api"
    }
  ],
  "services": [
    {
      "id": 201,
      "name": "checkout"
    }
  ]
}

400 - Bad Request, or an id was refused - repositories not found or not monitored, services not found. A refused write changes nothing

401 - Unauthorized

403 - Forbidden

404 - The team was not found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout