Name: github-project-automation-with-openwhisk
Owner: International Business Machines
Description: null
Created: 2018-02-12 20:00:24.0
Updated: 2018-04-14 20:04:21.0
Pushed: 2018-03-09 16:54:13.0
Homepage: null
Size: 308
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
In this Code Pattern, we will automate a few of the administrative tasks asscociated with Github Projects using OpenWhisk, and by extension, Serverless technologies. We will set up some OpenWhisk actions and triggers and associate them with webhooks generated by the Github API. The Actions we set up will then send requests back to the Github API to manipulate our Github Project. Optionally, we will have some of our actions send alerts via Slack. This pattern builds upon an idea put forth by Anthony Amanse in his Cloudfunction-github repository.
When the reader has completed this Code Pattern, they will understand how to:
There are multiple actions/triggers you can set up using the code in the repository. You can select more than one:
Since we are using Github Projcects and interacting with them through the Github API, you will need a Github user account and a Personal access token. If you do not already have one, you sign up for an account here. Once you have logged in, select the dropdown menu on the far upper right on the Github website, and select 'Settings'. From your personal settings, towards the bottom on the left hand side you should see a link for 'Developer Settings'. Select this, and then from the following page select 'Personal access tokens'. Click the Generate a personal access token link and you will have an access token. Copy this down: we will need it to access the Github API:
port GIT_TOKEN=[your 40 digit hex code]
We will also need to create a Github Project, as the administration of such a Project is what we are trying to automate! From your Github repository in the web UI, select the Projects tab, and then click 'Create Project'. We will need the ID that the API associates with that project, so:
rl -u [yourGithubID]:[yourGithubToken] -H "Accept: application/vnd.github.inertia-preview+json" "https://api.github.com/repos/[yourGithubID]/[yourGithubRepo]/projects"
Scroll through this list to find the ID of the Project you just created. Make note of this.
Clone the Github-Project-Automation-with-OpenWhisk repository locally. In a terminal, run:
t clone https://github.com/IBM/Github-Project-Automation-with-OpenWhisk
and then go ahead and move into that directory:
Github-Project-Automation-with-OpenWhisk
Our first task is to automate adding a card to the project whenever a new issue is created. This does not happen automatically, and if you are looking to track every issue that comes in, dragging each one of them onto the project board can be a monotinous task. First, we will need to identify the column in which new cards should be created:
rl -u [yourGithubID]:[yourGithubToken] -H "Accept: application/vnd.github.inertia-preview+json" "https://api.github.com/projects/[yourProjectID]/columns"
Find your prefered column, and keep track of it:
port COLUMN_ID=[yourColumnId]
We will be using the IBM Cloud web UI to create our Trigger and Action. From the Cloud Functions section, select 'Triggers' from the menu on the left, and then click the 'Create' button. After selecting the 'Create Trigger' option, you should see this screen:
You can see the kinds of Triggers that IBM Cloud Functions can set up for you. We are, of course, interested in the Github type. Click it, and you will be promted for a Trigger name (e.g. myNewCardTrigger), your access token that we obtained in the first step, your Github username, and the repository in question. Alternately, you can click the 'Get Access Token' button, which will have you autentiate against Github and will then fill out you Username and prepopulate the 'Repository' field wiht a list of repositorities to which your Github account has access. Finally, the events we would like to watch for our tigger are issues.
Click 'create' and you are ready to connect an action to your Trigger. From the following page click 'Add' in the upper right corner. Then give your Action a name (e.g. myNewCardAction), and click 'Create & Add'
Now that we've connected and created our Action, we had better add some content to it! Click the name of your recently created Action from the list, and on the following page, copy and paste the contents of newCard.js.
Click 'Save'. Any issues now created in your repositry will show up on your project board.
Another thing that would be handy is to have an alert sent about an issue when certain criteria have been met. In this example, we will send anotification to a Slack channel when all the checkboxes in the pre populated description of an issue have been filled. You can specify the content in the description of a new issue by creating a 'docs/ISSUE_TEMPLATE' file in the base of your repository.
You will also need to set up the 'Incoming Webook' app in your instance of Slack. Once ready, the app page will show you where to send incoming notifications. Store this URL locally:
rt SLACK_WEBHOOK=https://hooks.slack.com/services/AAA/BBB/CCC
In the previous example we used the IBM Cloud web UI to create our triggers and actions. This time we will demonstrate how to do the same thing using the IBM Cloud Functions CLI. Installation instructions for the CLI can be found here You have seen that IBM Cloud Functions already has a package for using Github event streams to create Triggers. When using the CLI, though, we will first need to bind it:
wsk package bind /whisk.system/github myGit \
aram username [yourGithubID] \
aram repository [yourGithubRepo] \
aram accessToken $GIT_TOKEN
To create the Trigger, Action, and Rule using the Bluemix CLI:
wsk trigger create myUpdateIssueTrigger --feed myGit/webhook --param events issues
wsk action create myUpdateIssueAction updateIssue.js --param gitUsername [yourGithubID] --param gitPersonalToken $GIT_TOKEN --param slackWebhook $SLACK_WEBHOOK
wsk rule create myUpdateIssueRule myUpdateIssueTrigger myUpdateIssueAction
For our final example, we are going to create an action that creates a new repository in the same Github organization in which our Project exists. We will also set up several additional actions to populate the newly create repository with some files. For starters, if you are not already using one, you will need an organization in github. (This is different from using your personal directory. You can invite other users to an organization.) Our first action will be watching the event stream of a project, looking for properties of an issue that indicate a repo should be created. Its response will then be to create a repo with in the organizaion. Our second group of actions (that are in the addFiles directory) are watching on the organization level for newly created repos. Their response is to then create a set of files in that new repository. This is useful in project automation because there are often files, like a README.md or LICENSE file, that new repositories will always require.
We can use the same trigger for multiple actions:
wsk trigger create myAddFilesTrigger --feed myGit/webhook --param events issues
wsk action create myAddContribAction addFiles/addContrib.js --param gitUsername [yourGithubID] --param gitPersonalToken $GIT_TOKEN
wsk rule create myAddContribRule myAddFilesTrigger myAddContribAction
wsk action create myAddMaintainAction addFiles/addMaintain.js --param gitUsername [yourGithubID] --param gitPersonalToken $GIT_TOKEN
wsk rule create myAddMaintainRule myAddFilesTrigger myAddMaintainAction
wsk action create myAddReadmeAction addFiles/addReadme.js --param gitUsername [yourGithubID] --param gitPersonalToken $GIT_TOKEN
wsk rule create myAddReadmeRule myAddFilesTrigger myAddReadmeAction