In this guide we will go through how to add a Github repo to Kyso so that every commit you make to Github will be reflected on Kyso.
It's very easy to add connect Github to Kyso - all you need to do is navigate to the Github page by clicking New > Connect Github Repository from the New button on the top right.
If you've signed up to Kyso with Github you will already be connected and you should see all your public repos. If not, just click the Connect Github account button. Using the dropdown on the right you have the option to authorize all your Github repositories, or just your public ones (default). Its not possible to authorize just one repo at this time given the way Github's OAuth authorisation works.
On the Github OAuth page you will have the option to authorise your own account and any organisations you may be part of.
You can search and filter your repositories, and import them to Kyso by clicking Connect to Kyso. You can then browse to your post on Kyso and choose whichever file you want to be shown to your visitors by default.
You can optionally add a 'kyso.yaml' file to your directory with the following options:
branch: this allows you to specify only a single branch which will be posted to Kyso.
main: Specify the main file you want your visitors to see
title: Specify the title of the post
description: Specify the description of the post
tags: any tags you want added to the post
email: an email address that a Kyso team member used to sign up to Kyso and they will be attributed as the creator on Kyso. This only applies to child posts.
created_at: to set the post date just add this field as a string that can be parsed by moment.js https://momentjs.com/guides/#/parsing/ This only applies to child posts.
updated_at: same as created_at but for when the post is updated. This only applies to child posts.
So for example if you had a directory with a 'my-article.ipynb' notebook and you wanted Kyso to only accept the staging branch you would create a 'kyso.yaml' file like the following:
title: "My awesome post"description: "This is a description of what I did in my awesome post"branch: stagingmain: my-article.ipynbtags:- apples- organges
You can also set the title and description, and preview image in the post config on Kyso.
Recommendation: Always add a title, description and preview image to your posts. You will get a ton more readers.
If you want to validate your yaml before pushing to Github - checkout this YAML Validator
In the absence of any kyso.yaml file in the directory, Kyso will look for a YAML header in a notebook's metadata. This may be a better option for those of you posting ongoing projects, to which commits are made on a daily or weekly basis. Rather than manually configuring a YAML file each time, you can simply update the metadata while working in the notebook.
The example below is our YAML configs contained within 3 dashed (-) lines top and bottom, in the first Markdown cell of the notebook:
---title: "My awesome post"description: "This is a description of what I did in my awesome post"branch: stagingmain: my-article.ipynbtags:- apples- organges---
If you repository contains many different folders which would be better presented as different posts on Kyso you can do that. There are various fields you can add to your 'kyso.yaml' to configure the behaviour you like
Posts: All you need is to add a 'posts' field to the 'kyso.yaml' with a list of folders you want to include. Currently the child posts must be organised in folders, importing different files from one folder as different child posts is not possible.
posts:- folder1- folder2
You can use wildcards, so for example, if you wanted to include all folders in the root directory just use:
Or if you wanted to include all folders starting with "article" use:
You must specify the 'posts' field in order to import child posts.
main: this is the default main file for all the include posts - you can overwrite this on a per post basis (see below).
hideRoot: (optional - default false) use this if you dont want the root repository appearing as its own Kyso post.
When you delete the parent repository all the child posts will be deleted too.Overriding config in the child posts
You can add a 'kyso.yaml' to each child folder and override any of the defaults the same as you do when your importing just one repo.
Go to your repository on Github and navigate to the Settings > Webhooks page and if you see a webhook that points to 'api.kyso.io' simply delete it and then re import your repository to Kyso.
If your post is not appearing the way you expect - make sure that the yaml in the 'kyso.yaml' file is correct, verify it at YAML Validator.