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.

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.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.

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.

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.