Documentation

Notion-Board brings Notion and GitHub closer than before. Notion-board lets you sync your GitHub Issues with notion database, so whenever a new issue is opened or existing issue is updated in GitHub it syncs your notion database accordingly.

Currently Notion-Board syncs issue title, lables and state. In future we are going to support more features so stay tuned.

You can try it out by opening a new issue in this repository and see it get synced in this Notion Database.

Setup Guide

To use Notion-Board you need to write a GitHub workflow and setup some unique properties in your notion database as well. In this guide we are going to help you setup Notion-board and get started.

Setting up GitHub workflow

Create a file notion.yaml in the folder .github/workflows and add these lines —

name: Notion Board
on:
  issues:
  issue_comment:
  workflow_dispatch:
    inputs:
      setup:
        description: 'Populate your notion database with all the requried properties'
        type: boolean
      syncIssues:
        description: 'sync all other existing issues in this repo'
        type: boolean
      issueType:
        type: choice
        description: 'The issue type you want to sync'
        options:
          - all
          - open
          - closed
        default: open
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Notion Board
        uses: Souvikns/Notion-Board@2.2.0
        with:
          setup: ${{github.event.inputs.setup}}
          syncIssues: ${{github.event.inputs.syncIssues}}
          issueType: ${{github.event.inputs.issueType}}
        env: 
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
          NOTION_DATABASE: ${{ secrets.NOTION_DATABASE }}

Adding `env` Variables

Now you need to setup some env variables for the workflow to run properly —

variable name	Description	Required
`GITHUB_TOKEN`	Github workflow token, this is added by default	true
`NOTION_API_KEY`	Notion Integration token	true
`NOTION_DATABASE`	Notion Database ID	true

To learn how to add custom env variables follow this blog.
To learn how you can create a new notion integration api key you can follow this step by step guide from Notion.
You can grab your notion database id from the url:

https://www.notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...
                                  |--------- Database ID --------|

To get the url you can right click on the database name from the side bar and copy the link.

Setting up Notion Database Properties

Now that you have successfully completed setting up GitHub side of things you have to add some required notion properties for Notion-Board to run properly.

Notion Properties

Property	Type
State	`Select`
URL	`url`
Label	`multi-select`
ID	`number`

You can also use the notion workflow_dispatch to automatically setup your notion database.

Steps

Just head over to the actions tab and go to Notion Board workflow.
Click the Run workflow button and select the first option that you see.
This will create the required properties in your notion database.

Sync Your Existing Issues

If you are adding Notion-Board to a project that already has some existing issues, you have to set them up manually. All you have to do is run the workflow with sync all other existing issues in this repo checked.

Notion Template

I hope to make a list of different useful notion templates for you to pick from, you can even submit the one you are using by opening a new Issue.

Here is a simple barebones Notion Template that you can duplicate to quickly get started. You can also share your notion template that you are using by opening a new issue and we can create a notion template library right here.

Notion Templates

Minimal
More coming soon...

Reporting Issues

Currently Notion-Board is under development and it has a lot of bugs that we are fixing as they come up. Feel free to let us know if you find any bug, it would help the tool get better. To report a bug just open an Issue describing the bug.

Contributing

Please take a moment to read our contributing guide to learn about our development process. I would suggest to open an issue first to discuss potential changes/addition.

Contributing Guide

This project is built using TypeScript so you need to have Node.js installed in your system. You can download Node.js from here.

Getting Started Quick

In order to contribute to this project, you should:

Clone this repository from your fork.
Run npm install in the project directory to install all the required dependencies.
Create a new branch with a meaningful name.
Develop a new feature or fix a bug you want.
Open a pull request to the main branch.
- Remember to build and package the code before you commit run —
  - npm run build
  - npm run package

Community Support

Currently I am the sole maintainer of the project, you can star this project to follow its development. Feel free to open issues for any new feature that you want, and I will try to build it. Feel free to fork the project and build the feature for yourself if I am too slow.

License

This software is licensed under Apache-2.0, see the LICENSE file for more information.