Base class for defining the behavior between Screwdriver and source control management (SCM) systems

npm install screwdriver-scm-base

This is a promise based interface for interacting with a source control management system

The configure function takes in an object and resets the configuration values

Required parameters:

Update the repository with the desired webhook configuration.

1. Resolves when the webhook is correctly attached to the repository
2. Rejects when the repository was unable to be updated with the webhook configuration

Required parameters:

Add deploy public key counterpart to the repository.

1. Resolves when the deploy key is successfully generated and added
2. Rejects when the deploy key fails to generate or add

Required parameters:

Returns whether auto deploy key generation is enabled or not.

1. Resolves to true/false corresponding to the flag status

Required parameters:

An scmUri (ex: github.com:1234:branchName, where 1234 is a repo ID number), which will be a unique identifier for the repo and branch in Screwdriver.

1. Resolve with an scm uri for the repository (e.g.: github.com:12345:master or github.com:12345:master:src/app/component)
2. Reject if not able to parse url

Required parameters:

A key-map of data related to the received payload in the form of:

{
    action: 'opened',   // can be 'opened', 'reopened', 'closed', or 'synchronized' for type 'pr'; 'push' for type 'repo'
    branch: 'mynewbranch',
    checkoutUrl: 'https://[email protected]/batman/test.git',
    hookId: '81e6bd80-9a2c-11e6-939d-beaa5d9adaf3', // webhook event uuid
    lastCommitMessage: 'This is the last commit message', // get a message of the last one from commits object
    prNum: 3,
    prRef: 'pull/3/merge',
    prSource: 'fork', // If type is 'pr', prSource is 'fork' or 'branch'
    scmContext: 'github:github.com',
    sha: '9ff49b2d1437567cad2b5fed7a0706472131e927',
    type: 'pr',         // can be 'pr' or 'repo'
    username: 'robin'  // should be the actor/creator of the webhook event (not necessarily the author)
}

1. Resolve with a parsed hook object
2. Reject if not able to parse hook

Required parameters:

An array of file paths that were changed:

['README.md', 'folder/screwdriver.yaml'] // array of changed files

1. Resolve with an array of files
2. Reject if not able to parse hook

Required parameters:

Checkout command in the form of:

{
    name: 'sd-checkout-code', // must be 'sd-checkout-code' exactly
    command: 'git clone https://github.com/screwdriver-cd/guide'
}

1. Resolve with a checkout command object for the repository
2. Reject if not able to get checkout command

Internally calls getCheckoutCommand to get just the checkout command for a build, given a pipeline model and build configuration.

Required Parameters:

Required parameters:

Decorated url in the form of:

{
    url: 'https://github.com/screwdriver-cd/scm-base',
    name: 'screwdriver-cd/scm-base',
    branch: 'branchName'
}

1. Resolve with a decorated url object for the repository
2. Reject if not able to get decorate url

Required parameters:

Decorated commit in the form of:

{
    url: 'https://github.com/screwdriver-cd/scm-base/commit/5c3b2cc64ee4bdab73e44c394ad1f92208441411',
    message: 'Use screwdriver to publish',
    author: {
        url: 'https://github.com/d2lam',
        name: 'Dao Lam',
        username: 'd2lam',
        avatar: 'https://avatars3.githubusercontent.com/u/3401924?v=3&s=400'
    }
}

1. Resolve with a decorate commit object for the repository
2. Reject if not able to decorate commit

Required parameters:

Decorated author in the form of:

{
    url: 'https://github.com/d2lam',
    name: 'Dao Lam',
    username: 'd2lam',
    avatar: 'https://avatars3.githubusercontent.com/u/3401924?v=3&s=400'
}

1. Resolve with a decorate author object for the repository
2. Reject if not able to decorate author

Required parameters:

Permissions for a given token on a repository in the form of:

{
    admin: true,
    push: true,
    pull: true
}

1. Resolve with a permissions object for the repository
2. Reject if not able to get permissions

Required parameters:

Permissions for a given user on a organization in the form of:

{
    admin: false,
    member: true
}

1. Resolve with a permissions object for the organization
2. Reject if not able to get permissions

Required parameters:

The commit sha for a given branch on a repository.

1. Resolve with a commit sha string for the given scmUri
2. Reject if not able to get a sha

Required parameters:

The commit sha for a ref on a repository.

1. Resolve with a commit sha string for the given owner, repo and ref
2. Reject if not able to get a sha

The parameters required are:

Update the commit status for a given repository and sha.

1. Resolve when the commit status was updated
2. Reject if the commit status fails to update

The parameters required are:

The contents of the file at path in the repository

1. Resolve with the contents of path
2. Reject if the path cannot be downloaded, decoded, or is not a file

A configuration that can be passed to the bell OAuth module to authenticate users.

1. Resolve with a valid bell configuration

The parameters required are:

The list of objects consist of PR names and refs (either a branch or a sha) for the pipeline. For example:

[{
  name: 'PR-5',
  ref: '73675432e1288f67332af3ecd0155cf455af1492'
}, {
  name: 'PR-6',
  ref: 'dfbbc032fa331a95ee5107d1f16e9ff5f7c9d2fa'
}]

1. Resolve with the list of objects consists of PR names and refs
2. Reject if the input or output is not valid

The parameters required are:

The object consists of PR name, sha, ref, and url for the pipeline.

1. Resolve with the object consists of PR name, sha, ref, and url
2. Reject if the input or output is not valid

The parameters required are:

The object consisting of PR comment ID, create time, and username.

1. Resolve with the object consists of PR comment ID, create time, and username
2. Reject if the input or output is not valid

No parameters are required.

The array of scm context names (e.g. [github:github.com, gitlab:my-gitlab])

1. The array of scm context names

The parameters required are:

The matching scm context name string (e.g. github:github.com)

1. The matching scm context name

The parameters required are:

The received webhook is available or not as boolean.

1. Resolve with the received webhook is available or not.
2. Reject if the input or output is not valid

The parameters required are:

The array of objects consisting of branch names.

1. Resolve with an array of objects consisting of branch names.

The parameters required are:

The display name of scm context

1. The display name of scm context

The parameters required are:

Read-only SCM config

1. Read-only SCM config

An object containing information of new pull request

1. Pull request object

Required parameters:

1. Returns True or False

To make use of the validation functions, the functions to override are:

1. _addWebhook
2. _addDeployKey
3. _autoDeployKeyGenerationEnabled
4. _parseUrl
5. _parseHook
6. _getChangedFiles
7. _getCheckoutCommand
8. _decorateUrl
9. _decorateCommit
10. _decorateAuthor
11. _getPermissions
12. _getOrgPermissions
13. _getCommitSha
14. _addPrComment
15. _updateCommitStatus
16. _getFile
17. _getOpenedPRs
18. _getBellConfiguration
19. _getPrInfo
20. stats 
21. _getScmContexts
22. _getScmContext
23. _canHandleWebhook 
24. _getBranchList
25. _openPr
26. getDisplayName (overriding needs only the case of scm-router)
27. getReadOnlyInfo (overriding needs only the case of scm-router)
28. _isEnterpriseUser

class MyScm extends ScmBase {
    // Implement the interface
    _getFile(config) {
        // do stuff here to lookup scmUri
        return Promise.resolve('these are contents that are gotten')
    }
}

const scm = new MyScm({});
scm.getFile({
    scmUri: 'github.com:12345:master',
    path: 'screwdriver.yaml',
    token: 'abcdefg'
}).then(data => {
    // do something...
});

npm test

Code licensed under the BSD 3-Clause license. See LICENSE file for terms.