Base class for defining the behavior between screwdriver and source control management systems
npm install screwdriver-scm-base> Base class for defining the behavior between Screwdriver and source control management (SCM) systems
``bash`
npm install screwdriver-scm-base
function takes in an object and resets the configuration values$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmUri | String | SCM URI to add the webhook to (e.g., "github.com:8888:branchName" |
| config.token | String | Access token for SCM |
| config.webhookUrl | String | The URL to use for webhook notifications |
| config.scmContext | String | (optional) The name of scm context |
#### Expected Outcome
Update the repository with the desired webhook configuration.
#### Expected Promise response
1. Resolves when the webhook is correctly attached to the repository
1. Rejects when the repository was unable to be updated with the webhook configuration
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.checkoutUrl | String | Checkout url for a repo to parse |
| config.token | String | Access token for SCM |
| config.scmContext | String | (optional) The name of scm context |
#### Expected Outcome
Add deploy public key counterpart to the repository.
#### Expected Promise response
1. Resolves when the deploy key is successfully generated and added
1. Rejects when the deploy key fails to generate or add
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmContext | String | (optional) The name of scm context |
#### Expected Outcome
Returns whether auto deploy key generation is enabled or not.
#### Expected Promise response
1. Resolves to true/false corresponding to the flag status
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.checkoutUrl | String | Checkout url for a repo to parse |
| config.rootDir | String | (optional) Root directory where source code lives (ex: src/app/component) |
| config.scmContext | String | (optional) The name of scm context |
| config.token | String | Access token for scm |
#### Expected Outcome
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.#### Expected Promise response
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
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| headers | Object | The request headers associated with the webhook payload |
| payload | Object | The webhook payload received from the SCM service |
#### Expected Outcome
A key-map of data related to the received payload in the form of:
`js
{
action: 'opened', // can be 'opened', 'reopened', 'closed', or 'synchronized' for type 'pr'; 'push' for type 'repo'
branch: 'mynewbranch',
checkoutUrl: 'https://batman@bitbucket.org/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)
}
`#### Expected Promise response
1. Resolve with a parsed hook object
2. Reject if not able to parse hook
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Yes | Configuration Object |
| config.type | String | The type of action from Git (can be 'pr' or 'repo') |
| config.payload | Object | The webhook payload received from the SCM service |
| config.token | String | Access token for scm |
#### Expected Outcome
An array of file paths that were changed:
js
['README.md', 'folder/screwdriver.yaml'] // array of changed files
`#### Expected Promise response
1. Resolve with an array of files
2. Reject if not able to parse hook
$3
Required parameters:| Parameter | Type | Required | Description |
| :------------- | :---- | :--------| :---- |
| config | Object | Yes | Configuration Object |
| config.branch | String | Yes | Pipeline branch |
| config.host | String | Yes | Scm host (ex: github.com) |
| config.manifest | String | No | Repo Manifest URL |
| config.org | String | Yes | Scm org (ex: screwdriver-cd) |
| config.prRef | String | No | PR branch or reference |
| config.repo | String | Yes | Scm repo (ex: guide) |
| config.rootDir | String | No | Root directory where source code lives (ex: src/app/component) |
| config.sha | String | Yes | Scm sha |
| config.scmContext | String | No | The name of scm context |
#### Expected Outcome
Checkout command in the form of:
js
{
name: 'sd-checkout-code', // must be 'sd-checkout-code' exactly
command: 'git clone https://github.com/screwdriver-cd/guide'
}
`#### Expected Promise response
1. Resolve with a checkout command object for the repository
2. Reject if not able to get checkout command
$3
Internally calls getCheckoutCommand to get just the checkout command for a build, given a pipeline model and build configuration.Required Parameters:
| Parameter | Type | Required | Description |
| :------------- | :---- | :--------| :---- |
| config | Object | Yes | Configuration Object |
| config.pipeline | PipelineModel | Yes | Pipeline model |
| config.job | Object | Yes |Job config with repoManifest annotation
| config.build | Object | Yes | Build config with sha and possibly prRef |
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmUri | String | Scm uri (ex:
) |
| config.token | String | Access token for scm |
| config.scmContext | String | (optional) The name of scm context |#### Expected Outcome
Decorated url in the form of:
`js
{
url: 'https://github.com/screwdriver-cd/scm-base',
name: 'screwdriver-cd/scm-base',
branch: 'branchName'
}
`#### Expected Promise response
1. Resolve with a decorated url object for the repository
2. Reject if not able to get decorate url
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmUri | String | Scm uri (ex:
) |
| config.sha | String | Commit sha to decorate |
| config.token | String | Access token for scm |
| config.scmContext | String | (optional) The name of scm context |#### Expected Outcome
Decorated commit in the form of:
`js
{
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'
}
}
`#### Expected Promise response
1. Resolve with a decorate commit object for the repository
2. Reject if not able to decorate commit
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.token | String | Access token for scm |
| config.username | String | Author to decorate |
| config.scmContext | String | (optional) The name of scm context |
#### Expected Outcome
Decorated author in the form of:
js
{
url: 'https://github.com/d2lam',
name: 'Dao Lam',
username: 'd2lam',
avatar: 'https://avatars3.githubusercontent.com/u/3401924?v=3&s=400'
}
`#### Expected Promise response
1. Resolve with a decorate author object for the repository
2. Reject if not able to decorate author
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmUri | String | The scm uri to get permissions on (ex:
) |
| config.token | String | Access token for scm |
| config.scmContext | String | (optional) The name of scm context |#### Expected Outcome
Permissions for a given token on a repository in the form of:
`js
{
admin: true,
push: true,
pull: true
}
`#### Expected Promise response
1. Resolve with a permissions object for the repository
2. Reject if not able to get permissions
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.organization | String | The scm organization to get permissions on (ex:
) |
| config.username | String | The user to get permissions on (ex: foo) |
| config.token | String | Access token for scm |
| config.scmContext | String | (optional) The name of scm context |#### Expected Outcome
Permissions for a given user on a organization in the form of:
`js
{
admin: false,
member: true
}
`#### Expected Promise response
1. Resolve with a permissions object for the organization
2. Reject if not able to get permissions
$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.scmUri | String | The scm uri (ex:
) |
| config.token | String | Access token for scm |
| config.scmContext | String | (optional) The name of scm context |#### Expected Outcome
The commit sha for a given branch on a repository.
#### Expected Promise response
1. Resolve with a commit sha string for the given
scmUri
2. Reject if not able to get a sha$3
Required parameters:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | Configuration Object |
| config.token | String | Access token for scm |
| config.owner | String | Owner of target repository |
| config.repo | String | Target repository |
| config.ref | String | Reference of the commit |
| config.scmContext | String | (optional) The name of scm context |
#### Expected Outcome
The commit sha for a ref on a repository.
#### Expected Promise response
1. Resolve with a commit sha string for the given
, repo and ref
2. Reject if not able to get a sha$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.buildStatus | String | Yes | The screwdriver build status to translate into scm commit status |
| config.context | String | No | The status context |
| config.description | String | No | The status description |
| config.jobName | String | No | Optional name of the job that finished |
| config.pipelineId | Number | No | The pipeline id |
| config.scmContext | String | No | The name of scm context |
| config.scmUri | String | Yes | The scm uri (ex:
) |
| config.sha | String | Yes | The scm sha to update a status for |
| config.token | String | Yes | Access token for scm |
| config.url | String | No | The target url for setting up details |#### Expected Outcome
Update the commit status for a given repository and sha.
#### Expected Promise Response
1. Resolve when the commit status was updated
2. Reject if the commit status fails to update
$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.path | String | Yes | The path to the file on scm to read |
| config.ref | String | No | The reference to the scm repo, could be a branch or sha |
| config.scmUri | String | Yes | The scm uri (ex:
github.com:1234:branchName) |
| config.token | String | Yes | Access token for scm |
| config.scmContext | String | No | The name of scm context |#### Expected Outcome
The contents of the file at
path in the repository#### Expected Promise Response
1. Resolve with the contents of
path
2. Reject if the cannot be downloaded, decoded, or is not a file$3
#### Expected Outcome
A configuration that can be passed to the [bell][bell] OAuth module to authenticate users.
#### Expected Promise Response
1. Resolve with a valid [bell][bell] configuration
$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.scmUri | String | Yes | The scm uri (ex:
github.com:1234:branchName) |
| config.token | String | Yes | Access token for scm |
| config.scmContext | String | No | The name of scm context |#### Expected Outcome
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'
}]
#### Expected Promise Response
1. Resolve with the list of objects consists of PR names and refs
2. Reject if the input or output is not valid$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.scmUri | String | Yes | The scm uri (ex:
) |
| config.token | String | Yes | Access token for scm |
| config.prNum | Integer | Yes | The PR number used to fetch the PR |
| config.scmContext | String | No | The name of scm context |#### Expected Outcome
The object consists of PR name, sha, ref, and url for the pipeline.
#### Expected Promise Response
1. Resolve with the object consists of PR name, sha, ref, and url
2. Reject if the input or output is not valid
$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.scmUri | String | Yes | The scm uri (ex:
github.com:1234:branchName) |
| config.token | String | Yes | Access token for scm |
| config.prNum | Integer | Yes | The PR number used to fetch the PR |
| config.comment | String | Yes | The PR comment |
| config.scmContext | String | No | The name of scm context |#### Expected Outcome
The object consisting of PR comment ID, create time, and username.
#### Expected Promise Response
1. Resolve with the object consists of PR comment ID, create time, and username
2. Reject if the input or output is not valid
$3
No parameters are required.#### Expected Outcome
The array of scm context names (e.g. [github:github.com, gitlab:my-gitlab])
#### Expected Response
1. The array of scm context names
$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.hostname | String | Yes | The scm host name (ex:
github.com) |#### Expected Outcome
The matching scm context name string (e.g. github:github.com)
#### Expected Response
1. The matching scm context name
$3
The parameters required are:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| headers | Object | The request headers associated with the webhook payload |
| payload | Object | The webhook payload received from the SCM service |
#### Expected Outcome
The received webhook is available or not as boolean.
#### Expected Promise Response
1. Resolve with the received webhook is available or not.
2. Reject if the input or output is not valid
$3
The parameters required are:| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.scmUri | String | Yes | The scm uri (ex:
github.com:1234:branchName) |
| config.token | String | Yes | Access token for scm |#### Expected Outcome
The array of objects consisting of branch names.
#### Expected Promise Response
1. Resolve with an array of objects consisting of branch names.
$3
The parameters required are:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| scmContext | String | The name of scm context |
#### Expected Outcome
The display name of scm context
#### Expected Response
1. The display name of scm context
$3
The parameters required are:| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| scmContext | String | The name of scm context |
#### Expected Outcome
Read-only SCM config
#### Expected Response
1. Read-only SCM config
$3
| Parameter | Type | Required | Description |
| :------------- | :---- | :------- | :-------------|
| config | Object | Yes | Configuration Object |
| config.checkoutUrl | String | Yes | Checkout url for a repo|
| config.token | String | Yes | Access token for scm |
| config.title | String | Yes | Pull request title |
| config.message | String | Yes | Pull request message |#### Expected Outcome
An object containing information of new pull request
#### Expected Response
1. Pull request object
#### isEnterpriseUser
Required parameters:
| Parameter | Type | Description |
| :------------- | :---- | :-------------|
| config | Object | The config object |
| config.token | String | The github token to interact with the graphql api |
| config.slug | String | The github enterprise slug |
| config.login | String | The github user's login name |
#### Expected Outcome
1. Returns True or False
Extending
To make use of the validation functions, the functions to override are:1.
_addWebhook
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1. _getScmContexts
1.
1.
1. _getBranchList
1.
1. (overriding needs only the case of scm-router)
1. getReadOnlyInfo (overriding needs only the case of scm-router)
1. _isEnterpriseUser
js
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...
});
`Testing
bash
npm test
``Code licensed under the BSD 3-Clause license. See LICENSE file for terms.
[npm-image]: https://img.shields.io/npm/v/screwdriver-scm-base.svg
[npm-url]: https://npmjs.org/package/screwdriver-scm-base
[downloads-image]: https://img.shields.io/npm/dt/screwdriver-scm-base.svg
[license-image]: https://img.shields.io/npm/l/screwdriver-scm-base.svg
[issues-image]: https://img.shields.io/github/issues/screwdriver-cd/screwdriver.svg
[issues-url]: https://github.com/screwdriver-cd/screwdriver/issues
[status-image]: https://cd.screwdriver.cd/pipelines/10/badge
[status-url]: https://cd.screwdriver.cd/pipelines/10
[bell]: https://www.npmjs.com/package/bell