---
title: "Update a site's repository"
url: https://docs.corefinity.com/api/reference/deployments/update-site-deployment-repository
type: endpoint
last_updated: 2026-11-13
feature: deployments
related:
  - https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md
  - https://docs.corefinity.com/mcp/tools/corestack_deployments_repository_set.md
---
# Update a site's repository

Sets the repository and branch the site deploys, through one of the connections the settings list, and
whether a push to the branch deploys. The site must deploy from git. Your role needs the Manage Deployment
Repositories permission, Manage Deployment Source to change `auto_deploy`, and Create Deployments to turn it
on or to change the repository while it is on.

```http
PUT /api/corestack/sites/{site}/deployments/repository
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 10 a minute
- Try it in the console: off. It has not been cleared for the console. Copy the request and run it yourself when you are sure.

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Body

- `auto_deploy` (boolean, required): True to deploy every push to the branch.
- `branch` (string, required): The branch to deploy. No spaces, no `..`, and no `-` at the start.
- `connection_id` (integer, required): A connection from the settings' `connections`.
- `contents` (string or null): `whole_site` or `site_content` (WordPress only). Left out, the repository keeps what it has. One of `whole_site`, `site_content`, `null`.
- `repo` (string, required): The repository as `owner/name`, or `group/subgroup/name` on GitLab: two or more parts of letters, digits, `.`, `_` and `-`, each starting with a letter or a digit, at most 200 characters in all. Spaces around it are dropped and it is stored in lower case.
- `root_directory` (string or null): The folder of the repository that holds the site, relative to the repository's root, such as `web` or `apps/site`: letters, digits, `_`, `.`, `-` and `/`, starting with a letter or a digit, at most 121 characters, with no leading `/`, no empty part and no `.` or `..` part. Spaces around it and a closing `/` are dropped, and it is stored in lower case. Null, empty or left out for the repository's root. A repository of site content always uses its root.
- `target_path` (string or null): Where a repository of site content goes, relative to the site's root, such as `wp-content/themes`. Null for the default. Left out, the repository keeps what it has.

## Request

### curl

```bash
curl -X PUT https://manage.corefinity.com/api/corestack/sites/1042/deployments/repository \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_deploy": false,
    "branch": "main",
    "connection_id": 4217,
    "contents": "site_content",
    "repo": "northwind-digital/harbourandfinch",
    "target_path": "wp-content/themes"
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->put('https://manage.corefinity.com/api/corestack/sites/1042/deployments/repository', [
        'auto_deploy' => false,
        'branch' => 'main',
        'connection_id' => 4217,
        'contents' => 'site_content',
        'repo' => 'northwind-digital/harbourandfinch',
        'target_path' => 'wp-content/themes',
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/deployments/repository', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    auto_deploy: false,
    branch: 'main',
    connection_id: 4217,
    contents: 'site_content',
    repo: 'northwind-digital/harbourandfinch',
    target_path: 'wp-content/themes',
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.put(
    "https://manage.corefinity.com/api/corestack/sites/1042/deployments/repository",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "auto_deploy": False,
        "branch": "main",
        "connection_id": 4217,
        "contents": "site_content",
        "repo": "northwind-digital/harbourandfinch",
        "target_path": "wp-content/themes",
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The settings as they are now.

```json
{
  "settings": {
    "can_change_mode": {
      "available": true,
      "reason": null
    },
    "can_change_repository": {
      "available": true,
      "reason": null
    },
    "can_deploy": {
      "available": true,
      "reason": null
    },
    "can_retry_deployments": {
      "available": true,
      "reason": null
    },
    "can_rollback": {
      "available": true,
      "reason": null
    },
    "can_stop_deployments": {
      "available": true,
      "reason": null
    },
    "can_switch_to_git": {
      "available": true,
      "reason": null
    },
    "can_turn_off_auto_deploy": {
      "available": true,
      "reason": null
    },
    "can_turn_on_auto_deploy": {
      "available": true,
      "reason": null
    },
    "connections": [
      {
        "id": 4217,
        "label": "GitLab (self-hosted) · daniel-reyes",
        "needs_reauth": false,
        "provider": "gitlab_self_hosted",
        "provider_label": "GitLab (self-hosted)"
      }
    ],
    "conversion": null,
    "deployments": [
      {
        "attempt_id": 8035,
        "binding": {
          "id": 2211,
          "label": "Default pipeline"
        },
        "can_retry": false,
        "can_rollback": false,
        "can_stop": false,
        "crons_paused": null,
        "duration_seconds": 131,
        "error": null,
        "finished_at": "2026-11-09T09:18:55Z",
        "git_author": {
          "avatar_url": null,
          "name": "Daniel Reyes"
        },
        "git_commit_url": "https://gitlab.example.com/northwind-digital/harbourandfinch/-/commit/9730595c6ec7aa59b77674ada74e30d961b1817c",
        "git_merge_request": null,
        "href": "/resources/deployments/5127",
        "id": 5127,
        "is_current": true,
        "maintenance_lift": null,
        "queued_at": "2026-11-09T09:16:40Z",
        "ref": {
          "branch": "main",
          "message": "Fix the basket count in the mobile header",
          "sha": "9730595c6ec7aa59b77674ada74e30d961b1817c",
          "short_sha": "9730595"
        },
        "release_id": "10f3c268-99c9-4c4e-9e8c-d467a321b123",
        "requested_by": null,
        "retry_warning": null,
        "stage": null,
        "stage_label": null,
        "started_at": "2026-11-09T09:16:44Z",
        "status": "succeeded",
        "status_label": "Succeeded",
        "stop_termination": null,
        "task": null,
        "trigger": "webhook"
      },
      {
        "attempt_id": 7990,
        "binding": {
          "id": 2211,
          "label": "Default pipeline"
        },
        "can_retry": false,
        "can_rollback": true,
        "can_stop": false,
        "crons_paused": null,
        "duration_seconds": 136,
        "error": null,
        "finished_at": "2026-11-02T14:07:31Z",
        "git_author": null,
        "git_commit_url": null,
        "git_merge_request": null,
        "href": "/resources/deployments/5098",
        "id": 5098,
        "is_current": false,
        "maintenance_lift": null,
        "queued_at": "2026-11-02T14:05:12Z",
        "ref": {
          "branch": "main",
          "message": "Update the header",
          "sha": "f7ba9cd79a612311f0487855eb0d96839161550e",
          "short_sha": "f7ba9cd"
        },
        "release_id": "2245ae09-7793-49fa-850b-225c62855fce",
        "requested_by": {
          "id": 3301,
          "name": "Daniel Reyes"
        },
        "retry_warning": null,
        "stage": null,
        "stage_label": null,
        "started_at": "2026-11-02T14:05:15Z",
        "status": "succeeded",
        "status_label": "Succeeded",
        "stop_termination": null,
        "task": null,
        "trigger": "manual"
      }
    ],
    "layout": "releases",
    "manual": {
      "note": "Files you change over SFTP or in the terminal are live on refresh",
      "sftp_command": "sftp -P 20001 web@ssh-northwind.example.net"
    },
    "mode": "git",
    "mode_label": "Git",
    "node": {
      "adopted": false,
      "major": null
    },
    "pipeline": {
      "bindings": [
        {
          "id": 2211,
          "is_default": true,
          "label": "Default pipeline",
          "tag": null
        }
      ],
      "version": 3
    },
    "releases": {
      "count": 2,
      "current": {
        "deployed_at": "2026-11-09T09:18:55Z",
        "id": "10f3c268-99c9-4c4e-9e8c-d467a321b123",
        "ref": {
          "branch": "main",
          "message": "Fix the basket count in the mobile header",
          "sha": "9730595c6ec7aa59b77674ada74e30d961b1817c",
          "short_sha": "9730595"
        }
      },
      "keep": 5,
      "previous": {
        "deployed_at": "2026-11-02T14:07:31Z",
        "id": "2245ae09-7793-49fa-850b-225c62855fce"
      }
    },
    "repository": {
      "auto_deploy": true,
      "branch": "main",
      "connection": {
        "id": 4217,
        "label": "GitLab (self-hosted) · daniel-reyes",
        "needs_reauth": false,
        "provider": "gitlab_self_hosted",
        "provider_label": "GitLab (self-hosted)"
      },
      "contents": "whole_site",
      "effective_target_path": null,
      "repo": "northwind-digital/harbourandfinch",
      "root_directory": "",
      "target_path": null,
      "url": "https://gitlab.example.com/northwind-digital/harbourandfinch",
      "webhook": {
        "error": null,
        "last_received_at": "2026-11-09T09:16:38Z",
        "state": "active"
      }
    },
    "repository_options": {
      "default_contents": "whole_site",
      "default_target_path": null,
      "layout_target_path": "wp-content",
      "release_root": "",
      "site_content": true
    }
  }
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the `write` scope (`scope_required`; to deploy, stop, retry or roll back it also needs the `deploy` ability, and `scope` names which is missing), your company requires two-factor authentication and you have not set it up, or your role lacks the permission the action needs (`forbidden`, with the `permission`): Create Deployments to deploy, and Deploy Deployments as well to start a deployment that waits. A waiting deployment you may not start answers a message only.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The site does not exist or is one you cannot deploy, `connection_id` is not a connection you may use on this site, or deployments are not on for your company (`feature_off`).

```json
{
  "message": "Not found."
}
```

### 409 The repository cannot be set now. `reason` says why: `mode` (switch the site to git deployments first), `needs_reauth` (the connection needs re-authorising), `managed_elsewhere` or `removed`.

```json
{
  "code": "mode",
  "message": "Switch this site to git deployments first",
  "reason": "mode"
}
```

### 422 A field is missing or wrong (`invalid`): for example `repo` is not `owner/name` or is longer than 200 characters, `root_directory` is not a folder inside the repository or is longer than 121 characters, the repository or branch was not found with this connection, the connected account cannot manage webhooks on the repository, or `target_path` is not a folder inside the site. `contents` `site_content` on a site that is not WordPress is `wrong_platform`, and while repositories of site content are paused by Corefinity it is `feature_off`; both name the field. A git provider whose address cannot be reached answers a message only.

```json
{
  "code": "invalid",
  "errors": {
    "repo": [
      "Enter the repository as owner/name",
      "or group/subgroup/name on GitLab"
    ]
  },
  "field": "repo",
  "message": "Enter the repository as owner/name, or group/subgroup/name on GitLab",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 A provider the request depends on did not answer. Nothing was changed; try again.

```json
{
  "message": "GitLab did not answer. Try again."
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `forbidden` | The person is not allowed to do this. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 |  | Check the id. You see only what your account can reach. |
| 409 | `mode` | The site deploys another way than this needs, by upload where Git is needed or the reverse, or its files are not in the releases layout yet. Switch its deployment mode first. |
| 409 | `needs_reauth` | The repository's connection is gone or needs authorising again. Reconnect the repository. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `wrong_platform` | This is not available for the site's platform. Use it on a site of the platform it is for. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Connect a repository](https://docs.corefinity.com/guides/sites/code-and-deployments/connect-a-repository.md)
- MCP tool: [`corestack_deployments_repository_set`](https://docs.corefinity.com/mcp/tools/corestack_deployments_repository_set.md)
