Skip to setup instructions
Julio M. Morales

Optional Notion Helper Tools

GitHub to Notion Research Diary

This optional automation is designed to work alongside the Projects and Research databases in the PhD Notion system. It is not required for the system to function. It provides an extra layer of bookkeeping and redundancy by recording GitHub commits as Research database items linked to their matching projects.

Each newly pushed commit creates a Research database item. Its name, or Notion page title, comes from the first line of the commit message. The item also includes the permanent commit link, matching project, assigned Notion user, and automatic creation date. Existing matching commit links are skipped to prevent duplicate entries.

The automation runs through GitHub Actions. You need permission to manage the GitHub repository and a Notion workspace owner account to create the connection.

Download the automation files (.zip)

1. Prepare the Projects and Research databases.

Use the existing databases in the PhD Notion system. If recreating the setup from scratch, create equivalent databases with the properties described below.

In Projects, create one entry for each project. Give each project the same name as its GitHub repository.

For example, repository Morales_2025a can match either Morales_2025a or Morales 2025a. The script tries the exact repository name first, then replaces underscores and hyphens with spaces. Matching project names must be unique.

In Research, confirm these properties exist:

Property nameNotion property typePurpose
Entry TitleTitle, the existing first columnReceives the first line of the commit message
Commit LinkURLStores the permanent GitHub commit link
ProjectRelationConnects the entry to the Projects database
PersonPerson/PeopleAssigns a real Notion user
DateCreated timeNotion automatically records when the entry is created

The title column can have another name; the script detects it automatically. The other property names must match exactly. Owner is also supported instead of Person.

The GitHub workflow is named Notion Research Diary, but its destination is your Research database.

2. Create a Notion connection and give it access.

Open the Notion Developer portal, find Internal connections, and create a connection in the workspace containing your databases. Give it a recognizable name, such as “GitHub Research Diary.”

In its Configuration tab, enable:

  • Read content
  • Insert content
  • Read user information without email addresses

Copy its API token and keep it private.

Open Content access → Edit access, select both the Research and Projects databases, and save. The connection needs access to both databases to create entries with a project relation. These steps follow Notion’s internal connection guide.

3. Copy the Research database’s data source ID.

Open the Research database’s settings, choose Manage data sources, and use Copy data source ID for the appropriate source.

Save this value for the GitHub setup below. It must be the data source ID, rather than a page, view, or database ID. Notion documents the distinction here.

4. Identify the person who will own the entries.

The supplied script automatically looks for a person named Julio M. Morales or Julio Morales. For that configuration, the owner ID secret is optional.

To assign another person, or distinguish between people with the same name, obtain their native Notion user ID:

  • Open Notion’s List all users API page and select Try it.
  • Authenticate with your connection token and use 2026-03-11 for Notion-Version.
  • Run the request. Find the result with the intended person’s name and "type": "person".
  • Copy that result’s id. If more results are available, follow the pagination controls or use next_cursor as start_cursor.

This ID will become NOTION_OWNER_USER_ID. It identifies the person account rather than the connection’s bot account.

5. Add the automation files to the repository.

Download the automation files. The bundle contains the working implementation and passed all 32 local tests.

Extract its contents into the top-level folder of your repository, preserving these paths:

.github/workflows/notion-research-diary.yml
.github/scripts/notion-research-diary.mjs
.github/scripts/notion-research-diary.test.mjs
Notes/notion_research_diary.md

The .github folder may be hidden in your file manager.

The workflow already includes automatic pushes to every branch and the manual workflow_dispatch trigger. GitHub installs Node.js 24 and runs the tests before processing commits.

6. Add the GitHub repository secrets.

In the GitHub repository, open Settings → Secrets and variables → Actions → New repository secret.

Add each value separately:

Secret nameValue
NOTION_TOKENThe connection token from step 2
NOTION_DATA_SOURCE_IDThe Research database’s data source ID from step 3
NOTION_OWNER_USER_IDThe person’s ID from step 4; optional for Julio’s automatic name lookup

Enter these through GitHub’s secret fields. Keep the token out of source files and commit messages. GitHub’s repository secret instructions show this process.

7. Commit and push the files.

Put the files on the repository’s default branch, usually main or master. From that branch in your local repository, run:

git add .github/workflows/notion-research-diary.yml \
  .github/scripts/notion-research-diary.mjs \
  .github/scripts/notion-research-diary.test.mjs \
  Notes/notion_research_diary.md

git commit -m "Add Notion Research Diary automation"
git push

This push can itself create a Research database entry for the setup commit.

The workflow must exist on the default branch for GitHub’s manual Run workflow button to appear. GitHub documents this requirement.

8. Run a manual test.

Open GitHub → Actions → Notion Research Diary → Run workflow.

Choose a branch containing the automation files, then choose either:

  • Leave commit_sha empty to process the latest commit of the selected branch.
  • Paste a full commit ID into commit_sha to process that specific commit.

Start the run and inspect Record pushed or manually selected commits. A successful run logs either that it created the entry or skipped an existing entry.

In the Research database, check:

  • The item’s title matches the first line of the commit message.
  • Commit Link opens the exact GitHub commit.
  • Project points to the matching project.
  • Person or Owner contains the intended Notion user.
  • Date contains the entry’s automatic creation timestamp.

Run the same test again. It should skip the existing record because its Commit Link already matches. The setup push may already have recorded the commit, so a skipped result during the first manual test can be correct.

9. Enable additional repositories and branches.

Repeat the GitHub file installation and secret configuration for every repository with a matching Notion project. The repositories can share the same connection token, Research database data source, and owner.

Existing branches also need the automation files merged or copied into them. New branches inherit the files when created from an installed branch.

A push containing three new commits creates up to three Research database entries. Repeated commits within the same repository are skipped. Creating a matching Notion project alone does not install the workflow in a new repository.