Skip to content
KataraKatara documentation

Attach a repository the GitHub App installation reaches

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/repositories
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/repositories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "provider": "github", "owner": "example", "name": "example", "store_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Needs a person’s signed-in session: attaching approves the repository’s default branch for 30 days, and while that lasts a push is read automatically. GitHub is asked first whether the organization’s installation reaches it. The first read is a separate step: syncRepository.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

Idempotency-Key
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Attach a repository the organization’s GitHub App installation reaches, naming the content store its documents go to. Attaching the same one twice attaches it once.

object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
provider
required
string
Allowed values: github
owner
required
string
/^[A-Za-z0-9._-]{1,100}$/
name
required
string
/^[A-Za-z0-9._-]{1,100}$/
store_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json

A repository an organization has attached so an agent may answer from it, the installation of the Katara GitHub App it reads through, the content store its documents go to, how far it has been read and the approval it is read under. Attaching approves the default branch for 30 days and renewing approves it again; while the approval lasts a push is read automatically. No permission is recorded: whether somebody may read what it points at is asked of GitHub when they ask, because a permission kept in a record goes on being true after it stops being true.

object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
provider
required
string
Allowed values: github
owner
required
string
/^[A-Za-z0-9._-]{1,100}$/
name
required
string
/^[A-Za-z0-9._-]{1,100}$/
attached_by
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
attached_at
required
string format: date-time
detached_at
required
One of:
string format: date-time
installation_id
required
One of:
integer
>= 1 <= 9007199254740991
repository_id
required
One of:
integer
>= 1 <= 9007199254740991
store_id
required
One of:
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
default_branch
required
One of:
string
/^[A-Za-z0-9._/-]{1,255}$/
synced_commit
required
One of:
string
/^[a-f0-9]{40}$/
synced_at
required
One of:
string format: date-time
head_commit
required
One of:
string
/^[a-f0-9]{40}$/
failure
required
One of:
string
Allowed values: truncated too_many_files repository_unavailable
sync_state
required

Pending: never read; syncing: a sync holds the repository now; behind: GitHub reported a newer commit on the default branch, or a sync stopped part way; failed: the last sync could not finish, see failure; unconnected: attached before the GitHub App, with nothing to read through.

string
Allowed values: unconnected pending syncing synced behind failed detached
approval_id
required
One of:
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
approval_given_by
required
One of:
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
approval_given_at
required
One of:
string format: date-time
approval_expires_at
required
One of:
string format: date-time
approval_state
required
One of:
string
Allowed values: active expired
Example
{
  "provider": "github",
  "failure": "truncated",
  "sync_state": "unconnected",
  "approval_state": "active"
}

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}