# Connect continuous GitHub source sync

Source: <https://everruns.com/docs/api/operations/connect_agent_source/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Agents & authoring](https://everruns.com/docs/api/groups/agents-authoring/)/Connect continuous GitHub source sync

# Connect continuous GitHub source sync

Preview

Apply a reviewed GitHub package and enable continuous sync. Pull mode is read-only; two_way also publishes local edits using conditional commits.

Public APIEverruns Cloud and self-hosted Platform

PUT`/v1/agents/{agent_id}/source`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Parameters

### Path Parameters

**agent_id**

required

string

Prefixed public identifier

## Request Bodyrequired

Media typeapplication/json

Reviewed package location and concurrency tokens required to enable source sync.

object

**branch**

required

Branch whose future commits the Agent follows.

string

### Example

```plaintext
main
```

**path**

Repository-relative package folder or manifest; empty selects the repository root.

string

### Example

```plaintext
agents/support
```

**repository**

required

GitHub repository in owner/name form.

string

### Example

```plaintext
acme/agents
```

**agent_digest**

required

Agent package digest returned by preview, protecting concurrent local edits.

string

### Example

```plaintext
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

**commit**

required

Exact source commit returned by preview; a changed branch requires another preview.

string

### Example

```plaintext
0123456789abcdef0123456789abcdef01234567
```

**expected_generation**

Current binding generation when replacing a source; omit for an unbound Agent.

string | null format: uuid

### Example

```plaintext
018f30c8-c970-7cb5-a8c9-9348aa71ba8c
```

**github_account**

One of:

* string

  Development GitHub account the source reads and writes through; omitted prefers the caller’s own GitHub, then the organization’s link.

  string

  Allowed values: personal organization

* null

  null

**mode**

Synchronization direction; two_way requires repository Contents write access.

string

Allowed values: pull two_way

## Responses

200Success

### 200

Success

Media typeapplication/json

Continuous GitHub source binding, applied revision and reconciliation status.

object

**applied_commit**

Last successfully applied commit; retained when a later revision fails.

string | null

**branch**

required

Branch monitored for source updates.

string

**error**

Safe diagnostic for the latest failed check, without upstream credentials.

string | null

**generation**

required

Binding generation used to detect a concurrent reconnect or disconnect.

string format: uuid

**github_account**

required

GitHub account the source reads through: personal, organization, or agent for a binding made before sync stopped using the Agent’s identity.

string

**last_checked_at**

UTC time when the source was last checked.

string | null format: date-time

**last_synced_at**

UTC time when a source revision was last applied successfully.

string | null format: date-time

**local_dirty**

required

Local edits are waiting for GitHub synchronization.

boolean

**managed_channels**

required

Package channel names whose configuration is managed by the source.

Array\<string>

**mode**

required

Direction of synchronization: pull or two_way.

string

**path**

required

Repository-relative package folder or manifest; empty means the root.

string

**repository**

required

Selected GitHub repository in owner/name form.

string

**status**

required

Current reconciliation state, including conflict when both sides changed.

string

### Example

```json
{
  "applied_commit": "0123456789abcdef0123456789abcdef01234567",
  "branch": "main",
  "error": "Source package validation failed: missing capability",
  "generation": "018f30c8-c970-7cb5-a8c9-9348aa71ba8c",
  "github_account": "organization",
  "last_checked_at": "2026-10-23T12:00:00Z",
  "last_synced_at": "2026-10-23T12:00:00Z",
  "local_dirty": false,
  "managed_channels": [
    "chat"
  ],
  "mode": "two_way",
  "path": "agents/support",
  "repository": "acme/agents",
  "status": "synced"
}
```

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/agents/example/source';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: '{"branch":"main","path":"agents/support","repository":"acme/agents","agent_digest":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","commit":"0123456789abcdef0123456789abcdef01234567","expected_generation":"018f30c8-c970-7cb5-a8c9-9348aa71ba8c","github_account":"personal","mode":"pull"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request PUT \
  --url https://app.everruns.com/api/v1/agents/example/source \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "main", "path": "agents/support", "repository": "acme/agents", "agent_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "commit": "0123456789abcdef0123456789abcdef01234567", "expected_generation": "018f30c8-c970-7cb5-a8c9-9348aa71ba8c", "github_account": "personal", "mode": "pull" }'
```

Additional language examples require JavaScript. The default request example is available above.

200

200 · Success

```json
{
  "applied_commit": "0123456789abcdef0123456789abcdef01234567",
  "branch": "main",
  "error": "Source package validation failed: missing capability",
  "generation": "018f30c8-c970-7cb5-a8c9-9348aa71ba8c",
  "github_account": "organization",
  "last_checked_at": "2026-10-23T12:00:00Z",
  "last_synced_at": "2026-10-23T12:00:00Z",
  "local_dirty": false,
  "managed_channels": [
    "chat"
  ],
  "mode": "two_way",
  "path": "agents/support",
  "repository": "acme/agents",
  "status": "synced"
}
```

## Matching endpoints