starflow-github v0.1.1
starflow-github
Prerequisites
In order to use this plugin, your project must have starflow as a dependency.
Install
$ npm install --save-dev starflow-github
Usage
Using a workflow:
var starflow = require('starflow');
var steps = [
{'github.getProject': ['user-name', 'project-name']}
];
var workflow = new starflow.Workflow(steps);
return workflow
.addPlugin(require('starflow-github'))
.run();
In an executable:
module.exports = function (starflow) {
var getProjectFactory = require('starflow-github')(starflow).factories.getProject;
function MyExecutable() {
starflow.BaseExecutable.call(this, 'myPlugin.myExecutable');
}
MyExecutable.prototype = Object.create(starflow.BaseExecutable.prototype);
MyExecutable.prototype.constructor = MyExecutable;
MyExecutable.prototype.exec = function exec() {
var getProjectExecutable = this.createExecutable(getProjectFactory);
return new starflow.Task(getProjectExecutable, ['user-name', 'project-name'])
.run()
.then(function () {
var projectResponse = this.storage.get('github.getProject/project');
starflow.logger.log('Got the following Github project: ' + projectResponse);
}.bind(this));
};
return function () {
return new MyExecutable();
};
};
Executables
Thereafter is the list of all the executable classes provided by this plugin.
Important The titles indicate the name that can be used when writing the steps of a workflow.
github.getProject
Given an user/organization name and a project name, gets all the data about the project.
Usage:
// for a workflow
var steps = [
{'github.getProject': ['Boulangerie', 'starflow-github']}
];
// in an executable
var getProjectFactory = require('starflow-github')(starflow).factories.getProject;
var getProjectExecutable = this.createExecutable(getProjectFactory);
var myTask = new starflow.Task(getProjectExecutable, ['Boulangerie', 'starflow-github']);
github.createPR
Given an user/organization name, a project name, source and target branches, and a title, creates a new pull-request.
Usage:
// for a workflow
var steps = [
{'github.createPR': ['Boulangerie', 'starflow-github', 'master', 'my-feature', 'This is the title']}
];
// in an executable
var createPRFactory = require('starflow-github')(starflow).factories.createPR;
var createPRExecutable = this.createExecutable(createPRFactory);
var myTask = new starflow.Task(createPRExecutable, ['Boulangerie', 'starflow-github', 'master', 'my-feature', 'This is the title']);
github.assignPR
Given an user/organization name, a project name, an assignee name and a pull-request ID, assigns someone to the PR.
Usage:
// for a workflow
var steps = [
{'github.assignPR': ['Boulangerie', 'starflow-github', 'bob', 42]}
];
// in an executable
var assignPRFactory = require('starflow-github')(starflow).factories.assignPR;
var assignPRExecutable = this.createExecutable(assignPRFactory);
var myTask = new starflow.Task(assignPRExecutable, ['Boulangerie', 'starflow-github', 'bob', 42]);
github.getPRBetween
Given an user/organization name, a project name, source and target branches, gets the pull-request (if it exists) that matches this pair of branches.
Usage:
// for a workflow
var steps = [
{'github.getPRBetween': ['Boulangerie', 'starflow-github', 'master', 'my-feature']}
];
// in an executable
var getPRBetweenFactory = require('starflow-github')(starflow).factories.getPRBetween;
var getPRBetweenExecutable = this.createExecutable(getPRBetweenFactory);
var myTask = new starflow.Task(getPRBetweenExecutable, ['Boulangerie', 'starflow-github', 'master', 'my-feature']);
Config
Some behaviors of this plugin depend on the values of config variables, here's the list of them and their effect.
- TOKEN (no default value, mandatory) Github token to access the API.
You can set these config variable from several ways:
Env variables on your machine.
Example (assuming
index.js
contains your workflow that uses the github executables):$ starflow_github__TOKEN=abc123 node index.js
.starflowrc
file at the root of your project (but you probably shouldn't choose this option as the credentials shouldn't be so easily accessible).Example:
{ "github": { "TOKEN": "abc123" } }
:bulb: Recommendation Store your Github token as a
starflow_github__TOKEN
variable in your~/.bash_profile
or~/.zshrc
file.
Internally, Starflow uses the rc module to handle the config values.
Storage
Some of the executables of this plugin store some values in their storage.
github.getProject
project Contains the project data (id, name, branches...) from Github.
Example:
var starflow = require('starflow'); var steps = [ {'github.getProject': ['user-name', 'project-name']}, {'custom.echo': '{{/github.getProject/project.name}}'} // displays "project-name" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-github')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
github.createPR
pr Contains the pull-request data (id, title, description...) from Github.
Example:
var starflow = require('starflow'); var steps = [ {'github.createPR': ['Boulangerie', 'starflow-github', 'master', 'my-feature', 'This is the title']}, {'custom.echo': '{{/github.createPR/pr.title}}'} // displays "This is the title" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-github')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
github.assignPR
pr Contains the pull-request data (id, title, description...) from Github.
Example:
var starflow = require('starflow'); var steps = [ {'github.assignPR': ['Boulangerie', 'starflow-github', 'bob', 42]}, {'custom.echo': '{{/github.assignPR/pr.title}}'} // e.g. displays "This is an awesome title!" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-github')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
github.getPRBetween
pr Contains the pull-request data (id, title, description...) from Github.
Example:
var starflow = require('starflow'); var steps = [ {'github.getPRBetween': ['Boulangerie', 'starflow-github', 'master', 'my-feature']}, {'custom.echo': '{{/github.getPRBetween/pr.title}}'} // e.g. displays "Title for my-feature dev" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-github')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
Note: learn more about storage paths on the Starflow documentation page.
If you want to contribute, please take the time to update this README file with the new executables/API brought by your contribution. Thank you! :heart: