Open Navigation

GitHub

Hosting and version control for software projects, making collaborative development much easier.

Overview

GitHub is a hosting service for software projects that use the Git version control software. Users can host, branch, and fork projects, and create issues, pull requests, and wikis for them.

Authentication

To authenticate the GitHub connector, begin by pressing New Authentication:

add-auth

Then, in the window that appears, name your authentication, and select the scopes (permissions) that you want this authentication to have:

github-auth-window

When you've selected the scopes you want, click Add authentication. A pop-up window will appear, asking you to confirm that you want to authorise Tray.io to use the scopes that you specified. Scroll to the bottom and click Authorize tray.io:

github-scopes

You may then be asked to confirm your password. Once you have done this, the window will be closed and you will have successfully authenticated the GitHub connector.

GitHub trigger

If you wish your workflow to be kicked off by a particular action in GitHub, you can use the GitHub Trigger.

The GitHub trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger operations available

Operations are available to subscribe to the following events in GitHub:

  • Fork
  • Issue Comment
  • Issues
  • Pull Request
  • Pull Request Review
  • Push
  • Release

When creating a new workflow choose GitHub as your trigger at the 'Create new workflow' section and wait to be redirected to your new workflow.

select-trigger-github

Basic operations list

Full list of operations can be found HERE

  • Create issue
  • Create repository
  • Get branch protection
  • Get commit
  • List branches
  • List contributors
  • List issues
  • Update pull request
  • Update repository

Examples

List repositories and branches

As a simple example, you can list repositories and then list the branches in each repository. This is what the workflow looks like:

example-workflow

The List repositories operation returns all repositories in your account. You can then use a Loop connector to iterate through each repository. You can do this by dragging a line from the List input field inside the Loop connector, up to the List repositories step, at which point a menu will appear:

menu

Select the items array. Its jsonpath will then appear in the Loop step:

list-field-loop

Then, for List branches, import the values from the Loop step. For User/Organization import owner.login, and for Repository import name:

select-login

The jsonpaths should look something like this (where loop-1 is the name of the Loop step we are using):

list-branches-fields

Consolidate security information of all repositories

NOTE: The GitHub account that you authenticate with in the Tray app must have the Owner permission level to view security information. Please visit the GitHub Docs for more information on permission levels.

A more advanced workflow will be able to pick up the security information of all repositories within your account and display them in a Google Sheets document. The resulting document will look similar to this:

Google Sheets output

This is what the finished workflow will look like:

Security information workflow example

Step 1 - List all repositories and loop

NOTE: The List repositories operation will return a maximum of 100 repositories per page. If your collection is greater than 100 repositories you will need to paginate. Please refer to the Pagination Docs for instructions.

Refer to List repositories and branches example for instructions on how to use the List repositories operation and how to loop through the collection.

Step 2 - Get branch protection information

Inside the loop use the Get branch protection operation of the GitHub connector to retrieve the protection information. Input the user/organization into the relevant field, link the Repository property to $.steps.loop-1.value.name and the Branch property to $.steps.loop-1.value.default_branch. The properties panel of the github-2 step will look like this:

github-2 properties panel

Finally, if the repository does not have branch protection it will return an error; in order to catch this we scroll to the bottom of the properties panel of the github-2 step and change the error handling to manual.

Step 3 - Input results into Google Sheets

For information on how to set up the Google Sheets connector please visit the Google Sheets Docs page.

ERROR

If an error is returned we pass the branch information from the loop-1 step into the Google Sheets connector using the Add row operation. Depending on the information you would like to include in Google Sheets the properties panel of sheets-1 will look similar to this:

Properties panel of Google Sheets for ERROR

You may wish to use the Date Time Helper to make the pushed at and created at values readable.

SUCCESS

If the GitHub connector successfully returns the protection information we can then start to manipulate the payload to input into your spreadsheet.

A common issue with the output of the Get branch protection operation is that output will differ between repositories, i.e. repo1 may output fields for restrictions and require_pr_reviews while repo2 may not. To overcome this we setup logic that identifies the missing field and sets a default value if it is missing. This section of the workflow achieves that with the restrictions field:

Google Sheets input ERROR

Here we set the boolean-condition-1 step to the Property exists operation and give the JSON Path Property field a value of $.steps.github-2.restrictions. If it does not exist we use the Data storage connector to set the key restrictions to a value of '', and if it does exist we set the key restrictions to a value of $.steps.github-2.restrictions. Finally we expose the restrictions key with Get value operation of step storage-3.

Similar to the ERROR branch we now use the Google Sheets connector to input the data into your spreadsheet. Again, your input will vary depending on the required spreadsheet content, in this example we have included the following additional fields:

Google Sheets input SUCCESS

The additional fields will grab the protection information from the github-2 step or a Data Storage connector. Ahead of inputing the data to the Google Sheets connector you may want to enter a few extra steps to make the data readable via the Helper connectors.

Was this article helpful?
Yes
No