The following REST APIs are exposed by checks-out.
checks-out relies on Github’s OAuth2 support for authentication. To log in to the REST API, a user must go to /settings/tokens on their Github server (for public Github, this would be https://github.com/settings/tokens.) and create a Personal Access Token. The token should have the permissions admin:org_hook, read:org, repo:status. Store this token in a safe place; you cannot get it again from Github.
Endpoint: /login Method: POST Query parameters: access_token=PERSONAL_ACCESS_TOKEN Body: none
Success: returns an AuthToken JSON structure, status = 200 Failure: returns status 401 (unauthorized) Tokens are currently set to expire after 72 hours.
{
"access_token": "JWT_TOKEN",
"expires_in": SECONDS_UNTIL_EXPIRY
}
After calling the initial login, you will get back a JWT Token. This token must be supplied to all other authenticated requests using one of the following methods:
Authorization and value Bearer JWT_TOKENaccess_token and value JWT_TOKENuser_sess and value JWT_TOKENEndpoint: /api/user Method: GET
Success: returns a GetCurrentUser JSON structure
{
"id": ID,
"login": "USER_NAME",
"avatar": "GITHUB_AVATAR_URL_FOR_USER"
}
This call removes the currently logged-in user from checks-out. If you do this, you will need to recreate your account.
Endpoint: /api/user Method: DELETE
Success: returns a 204 (deleted) status code
Returns all orgs that the current user belongs to.
Endpoint: /api/user/orgs Method: GET
Success: returns a JSON list of GetOrg JSON structures
{
"login": "NAME_OF_ORG",
"avatar": "GITHUB_AVATAR_URL_FOR_ORG",
"enabled": true|false,
"admin": true|false
},
If the current user is an admin for the org, admin is set to true.
If the org has been enabled in checks-out, enabled is set to true.
Returns all repos in the user’s account (not repos in orgs that the user belongs to)
Endpoint: /api/user/repos Method: GET
Success: returns a 200 (ok) status code and a JSON list of GetRepo JSON structures
{
"id": ID_IN_checks-out,
"owner": "USER_NAME",
"name": "REPO_NAME",
"slug": "USER_NAME/REPO_NAME",
"link_url": URL_IN_GITHUB",
"private": true|false,
"org": true|false
},
If id is present, the repo is managed by checks-out.
If the repo is enabled because its org is managed by checks-out, org is set to true.
If the repo is private to the user, private is set to true.
Returns all repos in the specified org
:org is replaced with the name of the org whose repos are being requested.
Success: returns a JSON list of GetRepo JSON structures
Returns all orgs that have been enabled by the current user
Endpoint: /api/user/orgs/enabled Method: GET
Success: return a JSON list of GetOrg JSON structures
note: the avatar and admin fields will always be set to "" and false respectively. the enabled field will always be set to true.
Turns on checks-out monitoring for the specified repo.
a personal repo :repo is the name of the repo
Success: returns 200 (ok) and a GetRepo JSON structure Failure: returns 409 (Conflict) if the repo is already enabled Failure: returns 404 (not found) if the repo does not exist or is not available to the user
Turns off checks-out monitoring for the specified repo
po :repo is the name of the repo
Success: returns 200 (ok) Failure: returns 409 (Conflict) if the repo is already disabled Failure: returns 404 (not found) if the repo does not exist or is not available to the user
Returns information on the specified enabled repo
po :repo is the name of the repo
Success: returns 200 (ok) and a GetRepo JSON structure Failure: returns 404 (not found) if the repo does not exist or is not available to the user
Turns on checks-out monitoring for the specified org. All repos currently in the org are enabled and all repos added to the org in the future will be enabled on creation.
:owner is the name of the org
Success: returns 200 (ok) and an OrgInfo JSON structure Failure: returns 409 (Conflict) if the org is already enabled Failure: returns 404 (not found) if the org does not exist, is not available to the user, or if it is the user’s personal repos (owner == user name)
{
"id": ID_IN_checks-out,
"owner": "ORG_NAME",
"link_url": "GITHUB_URL",
"private": true|false
}
If the org is private, private is set to true.
Turns on checks-out monitoring for the specified org. All repos currently in the org are enabled and all repos added to the org in the future will be enabled on creation.
:owner is the name of the org
Success: returns 200 (ok) Failure: returns 409 (Conflict) if the org is already disabled Failure: returns 404 (not found) if the org does not exist, is not available to the user, or if it is the user’s personal repos (owner == user name)
Returns the .lgtm or .checks-out file for the repo
onal repo :repo is the name of the repo
Success: returns 200 (ok) and a .checks-out config file in JSON Failure: returns 404 (not found) if the file does not exist or is not available to the user
Returns the MAINTAINERS file for the repo
personal repo :repo is the name of the repo
Success: returns 200 (ok) and a MAINTAINERS config file Failure: returns 404 (not found) if the file does not exist or is not available to the user
Validates that the .lgtm/.checks-out and MAINTAINERS files are present and valid
rsonal repo :repo is the name of the repo
Success: returns 200 (ok) Failure: returns 404 (not found) if the file does not exist or is not available to the user Failure: returns 400 (bad request) if the .lgtm/.checks-out or MAINTAINERS file is not valid. Error messages returned as text in body of response.
Converts a .lgtm file in a repo into the equivalent .checks-out file
, for a personal repo :repo is the name of the repo
Success: returns 200 (ok) and a .checks-out config file in JSON Failure: returns 404 (not found) if the file does not exist or is not available to the user Failure: returns 400 (bad request) if the .lgtm file is not valid. Error messages returned as text in body of response.
Returns the teams defined in an org
:owner is the name of the org
Success: returns 200 (ok) and a JSON array of strings. Each string is the name of a team in the org Failure: returns 404 (not found) if the org does not exist, is not available to the user, or is the user’s personal repos (owner == user name)
Returns the status of a pull request and the configuration used to process it
is the id of the pull request in Github
Success: returns 200 (ok) and a Status JSON structure Failure: returns 404 (not found) if the org, repo, or id does not exist or is not available to the user
{
"approved": true|false,
"approvers": ["USER_NAMES_OF_APPROVERS"],
"disapprovers": ["USER_NAMES_OF_DISAPPROVERS"],
"policy": {
},
"settings": {
}
}
approved is true if the pull request has been approved by checks-out, false otherwise.
approvers is an array of user names of the people who have approved the pull request.
disapprovers is an array of user names of the people who have disapproved the pull request.
policy is the policy in the .checks-out configuration file that is used for this pull request.
settings is the .checks-out configuration file. All optional sections are filled in with their default values.
Registers a new Slack target for all repos managed by the current user. The slack target’s name is the hostname for the Slack instance. A User-Level Slack Target will override an Admin-Level Slack Target for the same hostname. It is not visible by any other users in checks-out.
:hostname is the hostname for the slack group
Success: returns a 201 (created) status code
json
{
"url":"_URL_FOR_INCOMING_NOTIFICATIONS_WEBHOOKS_"
}
Returns the URL for a User-Level Slack target for all repos managed by the current user.
:hostname is the hostname for the slack group
Success: returns a 200 (ok) status code and a URL JSON structure Failure: returns a 404 (not found) status code if no URL is registered by the current user for the specified slack target
Updates the specified Slack target for all repos managed by the current user.
:hostname is the hostname for the slack group
Success: returns a 200 (created) status code
Removes the specified Slack target for all repos managed by the current user. If there is an admin-level Slack target specified for the same hostname, it will be used instead.
:hostname is the hostname for the slack group
Success: returns a 204 (deleted) status code Failure: returns a 404 (not found) status code if no URL is registered by the current user for the specified slack target
Returns a list of all repos that have been enabled in checks-out across all users
Endpoint: /api/repos Method: GET
Success: returns a 200 (ok) status code and a JSON list of GetRepo JSON structures
Returns a count of all repos that have been enabled in checks-out across all users
Endpoint: /api/count Method: GET
Success: returns a 200 (ok) status code and a number as text
Registers a new Slack target for all repos. The slack target’s name is the hostname for the Slack instance. A User-Level Slack Target will override an Admin-Level Slack Target for the same hostname.
:hostname is the hostname for the slack group
Success: returns a 201 (created) status code
Returns the URL for an Admin-Level Slack target for all repos.
:hostname is the hostname for the slack group
Success: returns a 200 (ok) status code and a URL JSON structure Failure: returns a 404 (not found) status code if no URL is registered by the admin for the specified slack target
Updates the specified Slack target for all repos.
:hostname is the hostname for the slack group
Success: returns a 200 (created) status code
Removes the specified Slack target for all repos. If there are user-level Slack targets specified for the same hostname, they will be used instead for those users.
:hostname is the hostname for the slack group
Success: returns a 204 (deleted) status code Failure: returns a 404 (not found) status code if no URL is registered by the current user for the specified slack target