Skip to content
Staircase

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

Branch

POST /branches

Retrieve List of Branches per Repository

getBranch

List the name of branches in a repository

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.

Request
application/json
{
  "repository_name": "code",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
Response
application/json

List the branches of a given repository

{
  "branches": [
    "master",
    "developer",
    "qa"
  ],
  "default_branch": "master"
}
Request bodyapplication/json
3 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. settings/Personal access token/New/Enable SSO.
Response 202application/json
2 fields

List the branches of a given repository

FieldTypeDescription
branchesstring[]List of branches of repository
default_branchstringDefault branch of repository
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or account not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Clone

POST /clone

Clone Repository

cloneRepository

Clone code

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.

Request
application/json
{
  "repository_name": "code",
  "branch": "master",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
Response
application/json

Clone job started

{
  "bundle_id": "979a6aa8-4f2-400d-9451-80ee1e127485"
}
Request bodyapplication/json
6 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository to be cloned
branchstringName of GitHub branch
commit_shastringCommit SHA
github_accountstringGitHub account name
github_tokenrequiredstringGitHub token. Go to settings/Personal access token/New/Enable SSO.
callback_urlstring (uri)Callback URL where are you waiting for code status
Response 202application/json
1 fields

Clone job started

FieldTypeDescription
bundle_idstring (uuid)Bundle id of the cloned project
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or branch is not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

GET /clone/{bundle_id}

Retrieve Clone Status

cloneBundle

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.

Response
application/json

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"
    }
  }
}
Parameters
1
ParameterTypeExampleDescription
bundle_id required string path 979a6aa8-4f2-400d-9451-80ee1e127485 bundle id of the cloned project
Response 200application/json
5 fields

Clone status

FieldTypeDescription
bundle_idstring (uuid)ID returned by **Clone Code**
clone_statusstringIN_PROGRESS, FAILED, or SUCCEEDEDFAILEDIN_PROGRESSSUCCEEDED
commit_hashstring (uuid)The branch last commit hash when clone was completed.
metadataobjectMetadata included in presigned URL with the clone status information
source_urlstring (uri)Presigned URL for the new cloned code package and metadata with information about the clone.
Response 400application/json
1 fields

Bad syntax

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Clone job not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Repository

POST /repos

Create repository

createRepository

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.

Request
application/json
{
  "repository_name": "code",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
  "private": true,
  "visibility": "private",
  "gitignore_template": "Python",
  "description": "Repository description"
}
Response
application/json

Repository created

{
  "status": "Succeeded",
  "repo_url": "https://<redacted>"
}
Request bodyapplication/json
7 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. settings/Personal access token/New/Enable SSO.
privatestringWhether the GitHub repository is private
visibilitystringVisibility level of the GitHub repository
descriptionstringDescription of the GitHub Repository
gitignore_templatestringTemplate name for git ignore file. For more information please visit GitHub git ignore collection pageExample Python
Response 202application/json
2 fields

Repository created

FieldTypeDescription
statusstringStatus of the pull request creation
repo_urlstringCreated repository URL
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or account not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Secret

POST /secret

Create or Update Repository Secret

updateSecret

Create or update a secret

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.

Request
application/json
{
  "repository_name": "code",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
  "secret_name": "newsecret",
  "secret_value": "0d1357"
}
Response
application/json

The secret was updated or created

{
  "message": "Succeeded"
}
Request bodyapplication/json
5 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
github_accountstringGitHub account name
github_tokenrequiredstringGitHub token. Go to settings/Personal access token/New/Enable SSO.
secret_namestringThe name of the secret
secret_valuestringThe value of the secret
Response 202application/json
1 fields

The secret was updated or created

FieldTypeDescription
messagestringstatus
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or account not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

POST /remove-secret

Delete Repository Secret

removeSecret

Delete a secret

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.

Request
application/json
{
  "repository_name": "code",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
  "secret_name": "newsecret"
}
Response
application/json

The secret was deleted

{
  "message": "Succeeded"
}
Request bodyapplication/json
4 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository to be cloned
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. settings/Personal access token/New/Enable SSO.
secret_namerequiredstringThe name of the secret
Response 202application/json
1 fields

The secret was deleted

FieldTypeDescription
messagestringstatus
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or account not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Commit

POST /commits

Retrieve List of Commits per Branch

getCommit

List of a branch commit history

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.

Request
application/json
{
  "repository_name": "code",
  "branch": "master",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
  "start_date": "2021-01-05",
  "end_date": "2021-01-15",
  "next_token": 1
}
Response
application/json

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
}
Request bodyapplication/json
7 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
branchstringName of GitHub branch
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. Go to settings/Personal access token/New/Enable SSO.
start_datestringMinimum date in time that will be returned in this format "YYYY-MM-DD"
end_datestringMaximum date in time that will be returned in this format "YYYY-MM-DD"
next_tokenintegerThe 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.)
Response 202application/json
3 fields

Clone job started

FieldTypeDescription
commitsobject[]List of commits of branch.
commentstringComment
authorstringAuthor name
datestringDate
paginationintegerPagination number
totalSizeintegerTotal number of commits in the branch
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name, branch or commits are not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

POST /commits/change

Commit changes to new branch

commitChange

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.

Request
application/json
{
  "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>"
}
Response
application/json

Commit operation job started

{
  "operation_id": "704db6f3-c534-4c4b-b7dd-d4fa52d60e71"
}
Request bodyapplication/json
9 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. Go to settings/Personal access token/New/Enable SSO.
new_branchrequiredstringName of branch that will be created
commit_messagestringCommit message for changes
user_emailrequiredstringGit user email. The email address used in the author identity when creating commit.
user_namerequiredstringGit username. The human-readable name used in the author identity when creating commit.
zip_urlrequiredstringPre-signed URL that will be used for getting repository zip file.
callback_urlstring (uri)Callback URL where are you waiting for commit status
Response 202application/json
1 fields

Commit operation job started

FieldTypeDescription
operation_idstringOperation ID of started asynchronous job.
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name, branch or commits are not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

GET /commits/change/{operation_id}

Retrieve Commit Changes Status

getCommitChangeStatus

Retrieve Commit Change Status

This service retrieves the status of a Commit Change request for a given operation_id. Status = REQUEST_MADE, IN_PROGRESS, SUCCEEDED, or FAILED.

Response
application/json

Clone status

{
  "status": "SUCCEEDED"
}
Parameters
1
ParameterTypeExampleDescription
operation_id required string path 979a6aa8-4f2-400d-9451-80ee1e127485 operation id of the started commit change job
Response 200application/json
1 fields

Clone status

FieldTypeDescription
statusstringREQUEST_MADE, IN_PROGRESS, FAILED, or SUCCEEDEDFAILEDIN_PROGRESSREQUEST_MADESUCCEEDED
Response 400application/json
1 fields

Bad syntax

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Commit change operation not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Pull Request

POST /pull-request

Create Pull Request

pullRequest

Create pull request

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.

Request
application/json
{
  "repository_name": "code",
  "github_account": "staircaseapi",
  "github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
  "head": "head",
  "base": "base",
  "title": "title",
  "body": "body"
}
Response
application/json

Pull request created

{
  "message": "Succeeded"
}
Request bodyapplication/json
8 fields
FieldTypeDescription
repository_namerequiredstringName of the GitHub repository
github_accountrequiredstringGitHub account name
github_tokenrequiredstringGitHub token. settings/Personal access token/New/Enable SSO.
headrequiredstringThe name of the branch where your changes are implemented.
baserequiredstringThe name of the branch you want the changes pulled into.
titlerequiredstringThe title of the new pull request
bodystringThe contents of the pull request
reviewersstring[]List of reviewers for pull request
Response 202application/json
2 fields

Pull request created

FieldTypeDescription
statusstringStatus of the pull request creation
pr_urlstringCreated pull request URL
Response 400application/json
1 fields

Bad request syntax or missed a required field

FieldTypeDescription
messagestringError message
Response 401application/json
1 fields

Unauthorized, Bad credentials.

FieldTypeDescription
messagestringError message
Response 403application/json
1 fields

Bad request syntax or forbidden request

FieldTypeDescription
messagestringError message
Response 404application/json
1 fields

Not found. Either repository_name or account not found.

FieldTypeDescription
messagestringError message
Response 405application/json
1 fields

Method not allowed.

FieldTypeDescription
messagestringError message
Other responses

422

Operations

POST /

Post operation

post-operation

Description

Request
application/json
{
  "test": "test"
}
Response
application/json

200 response

{
  "assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7df"
}
Parameters
3
ParameterTypeExampleDescription
test1 required string header Test1 Authorization key
x-api-key required string header Test1 Authorization key
test string header Test test key
Request bodyapplication/json
2 fields
FieldTypeDescription
testobject[]Errors array
messagestringError message
pathstringDescription
errorsobjectContains errors on failed assessment
errorsobjectErrors1
errors2stringErrors2
Response 200application/json
1 fields

200 response

FieldTypeDescription
assessment_idstringAssessment id, used for get assessment status
Other responses

204400

Errors

400401403404405422

Type to search.