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:

GitHub and GitHub Enterprise

GitLab and GitLab Enterprise

Azure DevOps

Bitbucket Data Center

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 and filter[environment]=null has to be specified.

If no environment or account 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 setup oauth2 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: GitHub and GitHub Enterprise GitLab and GitLab Enterprise Azure DevOps Bitbucket Data Center
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

201 Created –

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: GitHub and GitHub Enterprise GitLab and GitLab Enterprise Azure DevOps Bitbucket Data Center
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.