Create an Algorithm Backed by an External SCM Provider Through the API

Updated November 19, 2021

When you create an algorithm through the API, Algorithmia’s internal SCM provider is used by default unless an external SCM configuration is specified explicitly. To use an external SCM provider as the source code repository host for your algorithms, a cluster admin must first set up the configuration. At a high level, the workflow looks like this:

On the cluster admin side:

Set up an external SCM configuration and enable it to back algorithms (this is a one-time setup step).
List the available SCM configurations to get the id of the configuration of interest.

On the user side:

Authorize the SCM configuration through the Settings tab on your account profile, under Source Code Management.
Create an algorithm, specifying the SCM provider’s id from above, as well as other required parameters, under the source parameter in the request payload.

On this page, we’ll walk through the flow on the user’s side only. For details on the steps that a cluster admin must take, see the links above.

1. Authorize an external SCM configuration

In the UI, go to your account profile and click the Settings tab. Scroll to the Source Code Management section, where you’ll see a list of SCM configurations. Click Authorize on the entry that you’d like to authorize; this will enable that SCM configuration to host source code for new algorithms that you create using this account. A popup window will appear, and you’ll need to confirm that you authorize the external service.

2. Create an algorithm backed by an external SCM

In order to create the algorithm, you’ll need the id of the SCM configuration, which references in the code below as SCM_CONFIG_ID. A cluster admin will need to provide this value, as described above. You’ll then follow the standard process for creating an algorithm, but you’ll specify some additional information to indicate that you’d like the algorithm to be backed by this specific external SCM, meaning that the source code will be hosted on the external platform and not in Algorithmia’s internal SCM server.

Checking your account’s SCM authorization status

Before attempting to create your algorithm, it’s a good idea to first ensure that the SCM configuration and authorization process has been completed successfully. If the request below returns {"authorization_status":"unauthorized"}, you’ll need to re-check in the UI to ensure that you authorized the correct configuration (there may be multiple configurations on your cluster for any given SCM provider).

REST request

$ curl -X POST https://CLUSTER_DOMAIN/v1/scms/SCM_CONFIG_ID/token/status \
    -H 'Authorization: Simple STD_API_KEY' \
    -H 'Content-type: application/json'

REST response

{
  "scm_username": "SCM_USERNAME",
  "authorization_status": "authorized",
  "scm_organizations": [
    {
      "scm_org_username": "SCM_ORG_USERNAME",
      "access_level": "MEMBER"
    }
  ]
}

To make sense of this response, suppose that the SCM_CONFIG_ID used in the request above was that of a GitHub configuration. The scm_username returned would be the GitHub username authorized through the Algorithmia account, and the scm_org_username would be the GitHub account of the organization in which the SCM configuration was created by the Algorithmia cluster admin. Also note that in the response, the string MEMBER is not a placeholder, but is actually the string that is returned, indicating that the user is a member of the given organization and has corresponding resource access privileges.

Creating an algorithm

The algorithm request payload shown below has several UPPERCASE placeholders that you’ll need to replace in your request. In particular, you’ll want to make sure that you:

Replace the SCM_CONFIG_ID value with the one used above, which you’ve ensured is authorized on the cluster.
Replace the SCM_USERNAME value (to specify repository_owner) with the value returned from the request above to get the SCM authorization status.
For repository_name, you can choose whatever name makes the most sense to you. Often, it will be clearest to name the repository with the same name as the algorithm (as shown in the code below), but you have the option to name it differently if you choose. Note that you’ll need to substitute ENV_ID with a valid id of an algorithm environment on your cluster. You can find an appropriate id value by listing available languages and environments.