<!-- https://staircase.co/delivery/shipping/code -->
# Code

# Code

Repository operations as an API: clone, branch, commit, pull request and secret handling, as the first pipeline stage.

The pipeline starts by acting on the repository, and it does that through an API rather than through shell steps embedded in a build definition. Cloning at a pinned commit, opening a branch, committing generated output and raising a pull request are all calls.

That is what makes generation practical. A configuration bundle produced by a generator can be committed and proposed by the same pipeline that will build it.

## Operations

<!--source:api-specifications-->

### Branch
<!--/source-->

`POST` `/branches`

<!--source:api-specifications-->

#### Retrieve List of Branches per Repository
<!--/source-->

`getBranch`

<!--source:api-specifications-->
List the name of branches in a repository
<!--/source-->

<!--source:api-specifications-->
This service retrieves a list of names of branches in a given repository and project.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy List the branches of a given repository

```
{
 "branches": [
 "master",
 "developer",
 "qa"
 ],
 "default_branch": "master"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or account not found.

```
{
 "message": "Not found. Either repository_name, branch or commits are not found"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. settings/Personal access token/New/Enable SSO.<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
List the branches of a given repository
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `branches` | `string[]` | <!--source:api-specifications-->List of branches of repository<!--/source--> |
| `default_branch` | `string` | <!--source:api-specifications-->Default branch of repository<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or account not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Clone
<!--/source-->

`POST` `/clone`

<!--source:api-specifications-->

#### Clone Repository
<!--/source-->

`cloneRepository`

<!--source:api-specifications-->
Clone code
<!--/source-->

<!--source:api-specifications-->
This service clones code for a given repository and branch. The service returns a bundle_id that can be used to check the status and result of the request.

The cloned code is persisted as a .zip file in the Staircase persistence layer.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "branch": "master",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Clone job started

```
{
 "bundle_id": "979a6aa8-4f2-400d-9451-80ee1e127485"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or branch is not found.

```
{
 "message": "Not found. Either repository_name or branch is not found."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
6 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository to be cloned<!--/source--> |
| `branch` | `string` | <!--source:api-specifications-->Name of GitHub branch<!--/source--> |
| `commit_sha` | `string` | <!--source:api-specifications-->Commit SHA<!--/source--> |
| `github_account` | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. Go to settings/Personal access token/New/Enable SSO.<!--/source--> |
| `callback_url` | `string (uri)` | <!--source:api-specifications-->Callback URL where are you waiting for code status<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Clone job started
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | <!--source:api-specifications-->Bundle id of the cloned project<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or branch is not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

`GET` `/clone/{bundle_id}`

<!--source:api-specifications-->

#### Retrieve Clone Status
<!--/source-->

`cloneBundle`

<!--source:api-specifications-->
This service retrieves the status of a Clone Code request for a given bundle_id. Status = IN_PROGRESS, SUCCEEDED, or FAILED. Continue to ping this service until you receive a status = SUCCEEDED.

Retrieve Clone Status returns a source URL.

The source URL is a presigned URL for the new cloned code package. Provide the source URL as a parameter to the Build Bundle service.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Clone status

```
{
 "bundle_id": "979a6aa8-4f2-400d-9451-80ee1e127485",
 "clone_status": "SUCCEEDED",
 "commit_hash": "80a6e06179b267f0f4da68a2e1707d17b8f77fb2",
 "source_url": "https://code-dev-025.s3.amazonaws.com/service-builder-api/979a6aa8/source.zip",
 "metadata": {
 "service-code": {
 "commit_hash": "979a6aa8-4f2-400d-9451-80ee1e127485",
 "id": "d898b987-eda3-4b75-b7e7-bea8ae39674c",
 "issuer": "https://api.staircaseapi.com/code",
 "status": "SUCCEEDED",
 "timestamp": 1611603369.1289215,
 "version": 1.1,
 "repository_name": "StaircaseAPI/code"
 }
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad syntax

```
{
 "message": "Bad syntax"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Clone job not found.

```
{
 "message": "Clone job not found."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `bundle_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | <!--source:api-specifications-->bundle id of the cloned project<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
5 fields
<!--/source-->
<!--source:api-specifications-->
Clone status
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | <!--source:api-specifications-->ID returned by **Clone Code**<!--/source--> |
| `clone_status` | `string` | <!--source:api-specifications-->IN_PROGRESS, FAILED, or SUCCEEDED<!--/source-->`FAILED``IN_PROGRESS``SUCCEEDED` |
| `commit_hash` | `string (uuid)` | <!--source:api-specifications-->The branch last commit hash when clone was completed.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->Metadata included in presigned URL with the clone status information<!--/source--> |
| `source_url` | `string (uri)` | <!--source:api-specifications-->Presigned URL for the new cloned code package and metadata with information about the clone.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad syntax
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Clone job not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Repository
<!--/source-->

`POST` `/repos`

<!--source:api-specifications-->

#### Create repository
<!--/source-->

`createRepository`

<!--source:api-specifications-->
This service creates repository in given organization.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "private": true,
 "visibility": "private",
 "gitignore_template": "Python",
 "description": "Repository description"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Repository created

```
{
 "status": "Succeeded",
 "repo_url": "https://<redacted>"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or account not found.

```
{
 "message": "Not found. Either repository_name, branches or secret"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
7 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. settings/Personal access token/New/Enable SSO.<!--/source--> |
| `private` | `string` | <!--source:api-specifications-->Whether the GitHub repository is private<!--/source--> |
| `visibility` | `string` | <!--source:api-specifications-->Visibility level of the GitHub repository<!--/source--> |
| `description` | `string` | <!--source:api-specifications-->Description of the GitHub Repository<!--/source--> |
| `gitignore_template` | `string` | <!--source:api-specifications-->Template name for git ignore file. For more information please visit GitHub git ignore collection page<!--/source-->Example `Python` |

##### Response `202``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Repository created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->Status of the pull request creation<!--/source--> |
| `repo_url` | `string` | <!--source:api-specifications-->Created repository URL<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or account not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Secret
<!--/source-->

`POST` `/secret`

<!--source:api-specifications-->

#### Create or Update Repository Secret
<!--/source-->

`updateSecret`

<!--source:api-specifications-->
Create or update a secret
<!--/source-->

<!--source:api-specifications-->
This service create or update a secret in a given repository

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "secret_name": "newsecret",
 "secret_value": "0d1357"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy The secret was updated or created

```
{
 "message": "Succeeded"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or account not found.

```
{
 "message": "Not found. Either repository_name, branches or secret"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
5 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `github_account` | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. Go to settings/Personal access token/New/Enable SSO.<!--/source--> |
| `secret_name` | `string` | <!--source:api-specifications-->The name of the secret<!--/source--> |
| `secret_value` | `string` | <!--source:api-specifications-->The value of the secret<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The secret was updated or created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->status<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or account not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

`POST` `/remove-secret`

<!--source:api-specifications-->

#### Delete Repository Secret
<!--/source-->

`removeSecret`

<!--source:api-specifications-->
Delete a secret
<!--/source-->

<!--source:api-specifications-->
This service deletes a secret in a given repository

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "secret_name": "newsecret"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy The secret was deleted

```
{
 "message": "Succeeded"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or account not found.

```
{
 "message": "Not found. Either repository_name, branches or secret"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository to be cloned<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. settings/Personal access token/New/Enable SSO.<!--/source--> |
| `secret_name`required | `string` | <!--source:api-specifications-->The name of the secret<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The secret was deleted
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->status<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or account not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Commit
<!--/source-->

`POST` `/commits`

<!--source:api-specifications-->

#### Retrieve List of Commits per Branch
<!--/source-->

`getCommit`

<!--source:api-specifications-->
List of a branch commit history
<!--/source-->

<!--source:api-specifications-->
This service retrieves a list of the last of 14 days commits history from a given repository and branch, start date and end date can be given, the difference between the two cannot surpass 14 days. The service returns a list of commits objects with a maximum of 30 . By default, it will return a list of the last 14 days of commits with a maximum response of 30. Next_token can be used to retrieve the next 30 commits until is null.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "branch": "master",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "start_date": "2021-01-05",
 "end_date": "2021-01-15",
 "next_token": 1
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Clone job started

```
{
 "commits": [
 {
 "comments": "First commit",
 "author": "bezos",
 "date": "2021-01-29T16:55:51Z"
 },
 {
 "comments": "Second commit",
 "author": "jeff",
 "date": "2021-01-29T16:25:51Z"
 }
 ],
 "next_token": 0
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name, branch or commits are not found.

```
{
 "message": "Not found. Either repository_name, branch or commits are not found."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
7 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `branch` | `string` | <!--source:api-specifications-->Name of GitHub branch<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. Go to settings/Personal access token/New/Enable SSO.<!--/source--> |
| `start_date` | `string` | <!--source:api-specifications-->Minimum date in time that will be returned in this format "YYYY-MM-DD"<!--/source--> |
| `end_date` | `string` | <!--source:api-specifications-->Maximum date in time that will be returned in this format "YYYY-MM-DD"<!--/source--> |
| `next_token` | `integer` | <!--source:api-specifications-->The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Clone job started
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `commits` | `object[]` | <!--source:api-specifications-->List of commits of branch.<!--/source--> |
| `comment` | `string` | <!--source:api-specifications-->Comment<!--/source--> |
| `author` | `string` | <!--source:api-specifications-->Author name<!--/source--> |
| `date` | `string` | <!--source:api-specifications-->Date<!--/source--> |
| `pagination` | `integer` | <!--source:api-specifications-->Pagination number<!--/source--> |
| `totalSize` | `integer` | <!--source:api-specifications-->Total number of commits in the branch<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name, branch or commits are not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

`POST` `/commits/change`

<!--source:api-specifications-->

#### Commit changes to new branch
<!--/source-->

`commitChange`

<!--source:api-specifications-->
This service commits changes provided in zip file by creating new branch from main branch. Zip file should contain git ignore file.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "new_branch": "feature-branch",
 "user_email": "user@email.com",
 "user_name": "User Name",
 "zip_url": "https://bucket.s3.amazonaws.com/repo.zip?AWSAccessKeyId=<redacted>&Signature=<redacted>"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Commit operation job started

```
{
 "operation_id": "704db6f3-c534-4c4b-b7dd-d4fa52d60e71"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name, branch or commits are not found.

```
{
 "message": "Not found. Either repository_name, branch or commits are not found."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
9 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. Go to settings/Personal access token/New/Enable SSO.<!--/source--> |
| `new_branch`required | `string` | <!--source:api-specifications-->Name of branch that will be created<!--/source--> |
| `commit_message` | `string` | <!--source:api-specifications-->Commit message for changes<!--/source--> |
| `user_email`required | `string` | <!--source:api-specifications-->Git user email. The email address used in the author identity when creating commit.<!--/source--> |
| `user_name`required | `string` | <!--source:api-specifications-->Git username. The human-readable name used in the author identity when creating commit.<!--/source--> |
| `zip_url`required | `string` | <!--source:api-specifications-->Pre-signed URL that will be used for getting repository zip file.<!--/source--> |
| `callback_url` | `string (uri)` | <!--source:api-specifications-->Callback URL where are you waiting for commit status<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Commit operation job started
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `operation_id` | `string` | <!--source:api-specifications-->Operation ID of started asynchronous job.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name, branch or commits are not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

`GET` `/commits/change/{operation_id}`

<!--source:api-specifications-->

#### Retrieve Commit Changes Status
<!--/source-->

`getCommitChangeStatus`

<!--source:api-specifications-->
Retrieve Commit Change Status
<!--/source-->

<!--source:api-specifications-->
This service retrieves the status of a Commit Change request for a given operation_id. Status = REQUEST_MADE, IN_PROGRESS, SUCCEEDED, or FAILED.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Clone status

```
{
 "status": "SUCCEEDED"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad syntax

```
{
 "message": "Bad syntax"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Commit change operation not found.

```
{
 "message": "Commit change operation not found."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `operation_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | <!--source:api-specifications-->operation id of the started commit change job<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Clone status
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->REQUEST_MADE, IN_PROGRESS, FAILED, or SUCCEEDED<!--/source-->`FAILED``IN_PROGRESS``REQUEST_MADE``SUCCEEDED` |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad syntax
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Commit change operation not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Pull Request
<!--/source-->

`POST` `/pull-request`

<!--source:api-specifications-->

#### Create Pull Request
<!--/source-->

`pullRequest`

<!--source:api-specifications-->
Create pull request
<!--/source-->

<!--source:api-specifications-->
This service creates pull request. Reviewers field is optional for adding reviewer to pull request. Author of the pull request can not be added as a reviewer.

#### Warning

`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "repository_name": "code",
 "github_account": "staircaseapi",
 "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
 "head": "head",
 "base": "base",
 "title": "title",
 "body": "body"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400401403404405
<!--/source-->

<!--source:api-specifications-->
application/json Copy Pull request created

```
{
 "message": "Succeeded"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or missed a required field

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unauthorized, Bad credentials.

```
{
 "message": "Unauthorized, Bad credentials."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad request syntax or forbidden request

```
{
 "message": "Bad request syntax or missed a required field"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Not found. Either repository_name or account not found.

```
{
 "message": "Not found. Either repository_name, branches or secret"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Method not allowed.

```
{
 "message": "The method is not allowed for the requested URL"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
8 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | <!--source:api-specifications-->Name of the GitHub repository<!--/source--> |
| `github_account`required | `string` | <!--source:api-specifications-->GitHub account name<!--/source--> |
| `github_token`required | `string` | <!--source:api-specifications-->GitHub token. settings/Personal access token/New/Enable SSO.<!--/source--> |
| `head`required | `string` | <!--source:api-specifications-->The name of the branch where your changes are implemented.<!--/source--> |
| `base`required | `string` | <!--source:api-specifications-->The name of the branch you want the changes pulled into.<!--/source--> |
| `title`required | `string` | <!--source:api-specifications-->The title of the new pull request<!--/source--> |
| `body` | `string` | <!--source:api-specifications-->The contents of the pull request<!--/source--> |
| `reviewers` | `string[]` | <!--source:api-specifications-->List of reviewers for pull request<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Pull request created
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->Status of the pull request creation<!--/source--> |
| `pr_url` | `string` | <!--source:api-specifications-->Created pull request URL<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or missed a required field
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `401``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unauthorized, Bad credentials.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad request syntax or forbidden request
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Not found. Either repository_name or account not found.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `405``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Method not allowed.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Operations
<!--/source-->

`POST` `/`

<!--source:api-specifications-->

#### Post operation
<!--/source-->

`post-operation`

<!--source:api-specifications-->
Description

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "test": "test"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy 200 response

```
{
 "assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7df"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
3
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `test1` required | `string` header | `Test1` | <!--source:api-specifications-->Authorization key<!--/source--> |
| `x-api-key` required | `string` header | `Test1` | <!--source:api-specifications-->Authorization key<!--/source--> |
| `test` | `string` header | `Test` | <!--source:api-specifications-->test key<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `test` | `object[]` | <!--source:api-specifications-->Errors array<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Description<!--/source--> |
| `errors` | `object` | <!--source:api-specifications-->Contains errors on failed assessment<!--/source--> |
| `errors` | `object` | <!--source:api-specifications-->Errors1<!--/source--> |
| `errors2` | `string` | <!--source:api-specifications-->Errors2<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
200 response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `assessment_id` | `string` | <!--source:api-specifications-->Assessment id, used for get assessment status<!--/source--> |

##### Other responses

`204``400`

## Errors

`400``401``403``404``405``422`

## More in Shipping

- Previous product: Build
- Next product: Comply