st2 content pack containing github integrations
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci CircleCI 2.0 May 14, 2018
actions chore(list_pulls) update action metadata to display a more accurate p… Dec 11, 2018
aliases Transfer from st2contrib. Nov 29, 2016
rules Transfer from st2contrib. Nov 29, 2016
sensors Minor log message typo Aug 1, 2017
tests Supply correct num params. Oct 18, 2017
.gitignore Transfer from st2contrib. Nov 29, 2016
CHANGES.md
README.md doc(README) add a description of the new PR related actions Dec 11, 2018
config.schema.yaml Make 'repository_sensor' config section optional Sep 11, 2017
github.yaml.example Added example config Jul 30, 2017
icon.png
pack.yaml chore(pack) bump version to 0.8.3 Dec 11, 2018
requirements.txt Transfer from st2contrib. Nov 29, 2016

README.md

Github Integration Pack

Pack which allows integration with Github.

Configuration

Copy the example configuration in github.yaml.example to /opt/stackstorm/configs/github.yaml and edit as required.

It must contain:

  • token - Authentication token. Note: token only needs to be specified for actions such as add_comment and add_status which require authentication. If you use get_issue action only with public repositories, then token doesn't need to be specified.
  • repository_sensor.repositories - A list of repositories to monitor. Each item needs to contain the following keys: user - user or organization the repository you want to monitor belongs to and name - name of the repository you want to monitor.
  • repository_sensor.event_type_whitelist - List of whitelisted events to listen for.
  • user - GitHub Username (only for use with get_traffic_stats and get_clone_stats actions).
  • password - GitHub Password (only for use with get_traffic_stats and get_clone_stats actions).

Keep in mind that even though actions which operate on public repositories don't require an authentication token, you are still encouraged to supply one because unauthenticated requests have a very low rate limit.

Note : When modifying the configuration in /opt/stackstorm/configs/ please remember to tell StackStorm to load these new values by running st2ctl reload --register-configs

Obtaining an Authentication Token

To obtain an authentication token, follow the instructions on the Creating an access token for command-line use page.

Sensors

GithubRepositorySensor

This sensor monitors Github repository for activity and dispatches a trigger for each repository event.

Note that current default poll interval requires authentication because of GitHub rate-limiting for unauthenticated requests.

Currently supported event types:

  • IssuesEvent - Triggered when an issue is assigned, unassigned, labeled, unlabeled, closed, or reopened.
  • IssueCommentEvent - Triggered when an issue comment is created.
  • ForkEvent - Triggered when a user forks a repository.
  • WatchEvent - Triggered when a user stars a repository.
  • ReleaseEvent - Triggered when new release is available.
  • PushEvent - Triggered when a repository branch is pushed to. In addition to branch pushes, webhook push events are also triggered when repository tags are pushed.

github.repository_event trigger

Example trigger payload:

{
    "repository": "st2",
    "id": "2482918921",
    "type": "WatchEvent",
    "created_at": "2014-12-25T11:47:27.000000Z",
    "actor": {
        "bio": null,
        "name": null,
        "url": "https://api.github.com/users/odyss009",
        "id": 483157,
        "loaction": null,
        "email": "redacted"
    },
    "payload": {
        "action": "started"
    }
}

All the events contain repository, id, created_at, actor and payload attribute.

Value of the payload attribute depends on the event type. You can see a list of the available event types and their attributes on the Event Types & Payloads page.

Note: Similar thing can be achieved using Github webhooks in combination with StackStorm webhook handler.

Actions

  • add_comment - Add comment to the provided issue / pull request.
  • add_status - Add commit status to the provided commit.
  • create_issue - Create a new issue.
  • list_issues - List all the issues for a particular repo (includes pull requests since pull requests are just a special type of issues).
  • get_issue - Retrieve information about a particular issue. Note: You only need to specify authentication token in the config if you use this action with a private repository.
  • list_pulls - List all pull requests for a particular repo.
  • review_pull - Create a review for the provided pull request.
  • merge_pull - Merge the provided pull request.

Rules

github.deployment_event_webhook

To enable this rule, run the following on the CLI (with a valid ST2 auth token):

st2 rule enable github.deploy_pack_on_deployment_event

Then you should add a web hook in github sending deployment events to the following URL:

https://<st2-server>/api/v1/webhooks/github_deployment_event?st2-api-key=<ST2-API-KEY>

By default the enviroment is set to production, you can change this in your own github.yaml.

You can then create a deployment via ChatOps with the following command:

@hubot github deployment create me/my_st2_pack description Lets get the feature to production

Limitations

  • You need to have logged an OAuth key with StackStorm (via github.store_oauth_token).
  • It only works for the default github_type.
  • If using with GitHub.com your ST2 server needs to be contactable via the internet!
  • Deployment Statuses will be logged as the creating user in GitHub.
  • With StackStorm v2.1+ you should be able to deploy tags.