GitHubHosting and version control for software projects, making collaborative development much easier.
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.
To authenticate the GitHub connector, begin by pressing New Authentication:
Then, in the window that appears, name your authentication, and select the scopes (permissions) that you want this authentication to have:
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:
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.
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:
- Issue Comment
- Pull Request
- Pull Request Review
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.
The examples below show one or two of the available connector operations in use.
Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.
As a simple example, you can list repositories and then list the branches in each repository. This is what the workflow looks like:
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:
items array. Its jsonpath will then appear in the Loop step:
Then, for List branches, import the values from the Loop step. For User/Organization import
owner.login, and for Repository import
The jsonpaths should look something like this (where
loop-1 is the name of the Loop step we are using):
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:
This is what the finished workflow will look like:
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:
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.
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:
You may wish to use the Date Time Helper to make the pushed at and created at values readable.
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:
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:
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.