XP-Dev.com Documentation

Repository Integrations API

This user guide only applies if your account and project is on our new platform, i.e. if your project's URL begins with https://<your-account>.xp-dev.com rather than https://xp-dev.com. If your account is on our old platform, you should be using this user guide instead.

Each RepositoryIntegration Object has the following attributes:

Attribute Description
id Unique repository integration ID
sourceControl The repository ID that the integration belongs to
name Type of the integration, such as Jenkins, JIRA, Basecamp Classic etc.
alias User defined alias for the integration
variables A list of RepositoryIntegrationVariable objects

Each RepositoryIntegrationVariable Object has the following attributes:

Attribute Description
id Unique repository integration variable ID
name Name of the variable
value Value of the variable

Create a New Repository Integration

POST call to https://<your-account>.xp-dev.com/api/v1/repositories-integration with the following attributes:

Mandatory:

  • name
  • sourceControl
  • variables
  • alias

Objects in the variables list need to have the following mandatory attributes:

  • name
  • value

Example request:

curl -X POST -H 'Content-Type: application/json' -d '{"name": "JIRA", "alias": "My JIRA integration", "sourceControl": {"id": 2}, "variables": [{"name": "JIRA Base URL","value": "https://myjira.atlassian.net"},{"name": "Username","value": "someuser"},{"name": "Password","value": "somepass"}]}' https://<your-account>.xp-dev.com/api/v1/repositories-integration

Responses will be a single RepositoryIntegration object.

For example:

{
    "id": 4,
    "name": "JIRA",
    "sourceControl": {
        "id": 2
    },
    "variables": [
        {
            "id": 11,
            "name": "JIRA Base URL",
            "value": "https://myjira.atlassian.net"
        },
        {
            "id": 12,
            "name": "Username",
            "value": "someuser"
        },
        {
            "id": 13,
            "name": "Password",
            "value": "somepass"
        }
    ],
    "alias": "My JIRA integration"
}

Please note that repository integrations that require OAuth (specificallly Basecamp, Slack, Trello and Flowdock) cannot be created using this API.

Update a Single Repository Integration

PUT call to https://<your-account>.xp-dev.com/api/v1/repositories-integration/<repository-integration-id>.

Mandatory:

  • variables
  • alias

Objects in the variables list need to have the following mandatory attributes:

  • name
  • value

Example request:

curl -X PUT -H 'Content-Type: application/json' -d '{"alias": "My updated JIRA integration", "variables": [{"name": "JIRA Base URL","value": "https://myjira.atlassian.net"},{"name": "Username","value": "someuser"},{"name": "Password","value": "anotherpass"}]}' https://<your-account>.xp-dev.com/api/v1/repositories-integration/4

Responses will be a single RepositoryIntegration Object

Please note that repository integrations that require OAuth (specificallly Basecamp, Slack, Trello and Flowdock) cannot be updated using this API.

Get a Single Repository Integration

GET call to https://<your-account>.xp-dev.com/api/v1/repositories-integration/<repository-integration-id>. For example:

curl https://<your-account>.xp-dev.com/api/v1/repositories-integration/4

Responses will be a single RepositoryIntegration Object

List all Integrations for a Repository

GET request to https://<your-account>.xp-dev.com/api/v1/repositories-integration/repository/<repository-id>:

curl https://<your-account>.xp-dev.com/api/v1/repositories-integration/repository/2

Responses will be a list of RepositoryIntegration objects

Delete a Repository Integration

DELETE request to https://<your-account>.xp-dev.com/api/v1/repositories-integration/<repository-integration-id>:

curl -X DELETE https://<your-account>.xp-dev.com/api/v1/repositories-integration/150

Get Repository Integration Types

GET request to https://<your-account>.xp-dev.com/api/v1/repositories-integration/types:

curl https://<your-account>.xp-dev.com/api/v1/repositories-integration/types

Responses will be an object containing a list of repository integration types.

For example:

{
    "types": [
        "Pivotal Tracker",
        "Trello",
        "Basecamp Classic",
        "Bug.ly",
        "Twitter",
        "Lighthouse",
        "Asana",
        "DoneDone",
        "JIRA",
        "Bugzilla",
        "FogBugz",
        "Axosoft",
        "Jenkins",
        "HipChat",
        "Slack",
        "Basecamp",
        "Flowdock",
        "Rally",
        "Teamwork",
        "Deployer.vc"
    ]
}

Get variables for a Repository Integration Type

GET request to https://<your-account>.xp-dev.com/api/v1/repositories-integration/info/<integration-type>:

curl https://<your-account>.xp-dev.com/api/v1/repositories-integration/info/Jenkins

Responses will be an object containing variables for the integration type.

For example:

{
    "name": "Jenkins",
    "description": "Repository integration with Jenkins.",
    "variables": [
        {
            "name": "Jenkins URL",
            "type": "URL",
            "schemes": [
                "https",
                "http"
            ],
            "helpText": "URL for your Jenkins server, such as http://jenkins.<yourdomain>.com/ or http://<yourdomain.com>/jenkins"
        },
        {
            "name": "Project Name",
            "type": "TEXT",
            "helpText": "A build will be triggered for the project with this name whenever a commit/push occurs"
        },
        {
            "name": "Authentication Token",
            "type": "TEXT",
            "helpText": "Authentication token for a user which has the permission to trigger a build (may be left empty if no security is configured for the Jenkins instance)"
        },
        {
            "name": "Basic Authentication Username",
            "type": "TEXT",
            "helpText": "Basic authentication username for the server on which Jenkins is installed (may be left empty if the server does not require basic authentication)"
        },
        {
            "name": "Basic Authentication Password",
            "type": "PASSWORD",
            "helpText": "Basic authentication password for the server on which Jenkins is installed (may be left empty if the server does not require basic authentication)"
        },
        {
            "name": "Branch Filter",
            "type": "CSV_REGEX",
            "helpText": "A comma separated list of regular expressions for branch names to trigger execution of the integration on. For e.g. 'test.*' will match 'test' as well as 'test-branch'. Leaving it blank will disable filtering entirely."
        },
        {
            "name": "Skip Changeset Details",
            "type": "BOOLEAN",
            "helpText": "This will omit the list of files affected on each changeset. Only the commit log message will be posted."
        }
    ]
}

Repository Integration Variable Types

value field of an integration variable always needs to be a string. Type of the variable specifies what kind of value that the string will contain and it might be one of the following:

  • TEXT: Free form text. Example: "myusername"
  • URL: A URL value. URL typed variables also specify what kind of schemes they accept, such as http or https. Example: "https://mysite.deployer.vc"
  • PASSWORD: Password text. Example: "mypass"
  • BOOLEAN: "true" or "false"
  • CSV_REGEX: Comma separated list of regular expressions. Example: "master,test.*"
  • NUMERIC: Any numeric value. Example: "23177"

Feel free to contact us if you need any assistance.