Vcs Providers¶
The VcsProvider resource¶
The VCS Provider resource represents a connection between a Scalr account and a VCS, such as Github, Gitlab, Bitbucket, and Azure DevOps.
Key path
Description
type* (string)
Available values:vcs-providers
id (string)
attributes.auth-type* (string)
Available values:oauth2
,personal_token
Authentication type, the VCS API client is using to establish connection with the VCS.
oauth2
- private OAuth App, user or organization creates in their VCS account. Setup through this method requires a user to complete a web flow through a browser, where the user should authorize Scalr to connect to their OAuth App.
personal_token
- a pre-generated authentication token. This method works better if you need to fully automate the VCS provider creation.How to generate access tokens for different VCS providers:
attributes.error-message (string)
Contains error message, if the connection to VCS provider is broken.
attributes.name* (string)
VCS provider name, which must be unique within the account.
attributes.token (string)
Access token for an API client for using to connect to the VCS Provider.
attributes.url (string)
The URL to the VCS provider installation. Required for GitHub Enterprise, GitLab Enterprise and Bitbucket Data Center.
attributes.username (string)
Username for personal_token auth type. This field is required for bitbucket_enterprise provider.
attributes.vcs-type* (string)
Available values:github
,gitlab
,bitbucket
,bitbucket_enterprise
,gitlab_enterprise
,github_enterprise
,azure_dev_ops_services
VCS provider type.
relationships.account (object)
The account that owns this VCS integration.
relationships.account.data.type* (string)
Available values:accounts
relationships.account.data.id* (string)
relationships.environments (object)
The list of environments this VCS integration is linked to.
relationships.environments.data* (array)
links.self (string)
List VCS Providers¶
-
GET
/api/iacp/v3/vcs-providers
¶ This endpoint returns a list of VCS providers by various filters.
To list VCS providers accessible from a specific environment -
filter[environment]
, or when from a specific account -filter[account]
has to be specified.For self-hosted Scalr there’s also an option to list all VCS providers created globally
both
filter[account]=null
andfilter[environment]=null
has to be specified.
If no
environment
oraccount
filters were specified, all VCS providers to which a current user has read access will be returned.- Query Parameters
query (string) – Full text search based on a VCS provider’s
name
page[number] (string) – Page number
page[size] (string) – Page size
filter[vcs-provider] (string) – The ID of the VCS provider. Multiple values are allowed through COMMA
,
filter[vcs-type] (string) – Filter by VCS type
filter[environment] (string) – The environment filter
filter[account] (string) – The account filter
sort (array) – The comma-separated list of attributes. (Available values:
name
,vcs-type
)
Example Request:
GET /api/iacp/v3/vcs-providers HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK –
Success.
Example Respone:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": [ { "attributes": { "auth-type": "personal_token", "name": "account_scope_provider", "oauth": null, "url": "https://github.com", "vcs-type": "github" }, "id": "vcs-tk8dllqje1mav53", "links": { "self": "https://my.scalr.io/api/iacp/v3/vcs-providers/vcs-tk8dllqje1mav53" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "environment": null }, "type": "vcs-providers" }, { "attributes": { "auth-type": "personal_token", "name": "env_scope_provider", "oauth": null, "url": "https://github.com", "vcs-type": "github" }, "id": "vcs-tk8dllqje1mrv43", "links": { "self": "https://my.scalr.io/api/iacp/v3/vcs-providers/vcs-tk8dllqje1mrv43" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "environment": { "data": { "id": "env-svrcnchebt61e30", "type": "environments" } } }, "type": "vcs-providers" }, { "attributes": { "auth-type": "personal_token", "name": "global_scope_provider", "oauth": null, "url": "https://github.com", "vcs-type": "github" }, "id": "vcs-tk8dllqje1rav31", "links": { "self": "https://my.scalr.io/api/iacp/v3/vcs-providers/vcs-tk8dllqje1rav31" }, "relationships": { "account": null, "environment": null }, "type": "vcs-providers" } ], "included": null, "links": { "first": "https://my.scalr.iom/api/iacp/v3/vcs-providers?page%5Bnumber%5D=1&page%5Bsize%5D=20", "last": "https://my.scalr.io/api/iacp/v3/vcs-providers?page%5Bnumber%5D=1&page%5Bsize%5D=20", "next": null, "prev": null, "self": "https://my.scalr.io/api/iacp/v3/vcs-providers?page%5Bnumber%5D=1&page%5Bsize%5D=20" }, "meta": { "pagination": { "current-page": 1, "next-page": null, "prev-page": null, "total-count": 3, "total-pages": 1 } } }
403 Forbidden – User unauthorized to perform action.
404 Not Found – Account or environment not found.
4XX – Client error.
5XX – Server error.
Create a VCS Provider¶
-
POST
/api/iacp/v3/vcs-providers
¶ Create a new VCS connection between Scalr and a VCS provider.
VCS providers can be created at the Scalr account. Self-hosted Scalr also supports the creation of global VCS providers. If a VCS provider is created globally, all accounts within the self-hosted installation will have access to use the VCS provider.
Only VCS providers with
personal_token
auth type, can be created through the API. If you need to setupoauth2
provider, you should use Scalr web interface to do this.Request body:
Key path
Description
data.type* (string)
Available values:vcs-providers
data.id (string)
data.attributes.auth-type* (string)
Available values:oauth2
,personal_token
Authentication type, the VCS API client is using to establish connection with the VCS.
oauth2
- private OAuth App, user or organization creates in their VCS account. Setup through this method requires a user to complete a web flow through a browser, where the user should authorize Scalr to connect to their OAuth App.personal_token
- a pre-generated authentication token. This method works better if you need to fully automate the VCS provider creation.How to generate access tokens for different VCS providers:
data.attributes.name* (string)
VCS provider name, which must be unique within the account.
data.attributes.token (string)
Access token for an API client for using to connect to the VCS Provider.
data.attributes.url (string)
The URL to the VCS provider installation. Required for GitHub Enterprise, GitLab Enterprise and Bitbucket Data Center.
data.attributes.vcs-type* (string)
Available values:github
,gitlab
,bitbucket
,bitbucket_enterprise
,gitlab_enterprise
,github_enterprise
,azure_dev_ops_services
VCS provider type.
data.relationships.account (object)
The account that owns this VCS integration.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environments (object)
The list of environments this VCS integration is linked to.
data.relationships.environments.data* (array)
Example Request:
POST /api/iacp/v3/vcs-providers HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "vcs-providers", "attributes": { "name": "main", "vcs-type": "github", "auth-type": "personal_token", "token": "ghp_lp5NyEkU....." }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } } } } }
- Status Codes
Created.
Example Respone:
HTTP/1.1 201 Created Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "type": "vcs-providers", "id": "vcs-tk8dllqje1mav43", "attributes": { "auth-type": "personal_token", "name": "main", "url": "https://github.com", "vcs-type": "github" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } } } } }
403 Forbidden – User unauthorized to perform action.
404 Not Found – Relationship resource not found, or user unauthorized to perform action.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Delete a VCS Provider¶
-
DELETE
/api/iacp/v3/vcs-providers/{vcs_provider}
¶ The endpoint deletes a VCS provider by ID.
- Parameters
vcs_provider (string) –
- Status Codes
204 No Content – Deleted.
404 Not Found – VCS provider not found or user unauthorized.
4XX – Client error.
5XX – Server error.
Get a VCS Provider¶
-
GET
/api/iacp/v3/vcs-providers/{vcs_provider}
¶ Show details of a specific VCS provider.
- Parameters
vcs_provider (string) – The ID of the VCS provider.
Example Request:
GET /api/iacp/v3/vcs-providers/{vcs_provider} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK –
Success.
Example Respone:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "attributes": { "auth-type": "personal_token", "name": "default", "url": "https://github.com", "vcs-type": "github" }, "id": "vcs-tk8dllqje1rav31", "links": { "self": "https://my.scalr.io/api/iacp/v3/vcs-providers/vcs-tk8dllqje1rav31" }, "relationships": { "account": null, "environment": null }, "type": "vcs-providers" }, "included": null, "meta": null }
404 Not Found – VCS provider not found or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Update a VCS Provider¶
-
PATCH
/api/iacp/v3/vcs-providers/{vcs_provider}
¶ This endpoint allows updates to attributes of an existing VCS provider.
- Parameters
vcs_provider (string) – The ID of the VCS provider to update.
Request body:
Key path
Description
data.type* (string)
Available values:vcs-providers
data.id (string)
data.attributes.auth-type* (string)
Available values:oauth2
,personal_token
Authentication type, the VCS API client is using to establish connection with the VCS.
oauth2
- private OAuth App, user or organization creates in their VCS account. Setup through this method requires a user to complete a web flow through a browser, where the user should authorize Scalr to connect to their OAuth App.personal_token
- a pre-generated authentication token. This method works better if you need to fully automate the VCS provider creation.How to generate access tokens for different VCS providers:
data.attributes.name* (string)
VCS provider name, which must be unique within the account.
data.attributes.token (string)
Access token for an API client for using to connect to the VCS Provider.
data.attributes.url (string)
The URL to the VCS provider installation. Required for GitHub Enterprise, GitLab Enterprise and Bitbucket Data Center.
data.attributes.vcs-type* (string)
Available values:github
,gitlab
,bitbucket
,bitbucket_enterprise
,gitlab_enterprise
,github_enterprise
,azure_dev_ops_services
VCS provider type.
data.relationships.account (object)
The account that owns this VCS integration.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environments (object)
The list of environments this VCS integration is linked to.
data.relationships.environments.data* (array)
Example Request:
PATCH /api/iacp/v3/vcs-providers/{vcs_provider} HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "vcs-providers", "id": "vcs-tk8dllqje1mav43", "attributes": { "token": "ghp_k4Nl8iQn4..." } } }
- Status Codes
200 OK – Updated.
403 Forbidden – User unauthorized to perform action.
404 Not Found – Relationship resource not found, or user unauthorized to perform action.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.