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.
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 name | Notion property type | Purpose |
|---|---|---|
Entry Title | Title, the existing first column | Receives the first line of the commit message |
Commit Link | URL | Stores the permanent GitHub commit link |
Project | Relation | Connects the entry to the Projects database |
Person | Person/People | Assigns a real Notion user |
Date | Created time | Notion 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-11forNotion-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 usenext_cursorasstart_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 name | Value |
|---|---|
NOTION_TOKEN | The connection token from step 2 |
NOTION_DATA_SOURCE_ID | The Research database’s data source ID from step 3 |
NOTION_OWNER_USER_ID | The 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_shaempty to process the latest commit of the selected branch. - Paste a full commit ID into
commit_shato 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 Linkopens the exact GitHub commit.Projectpoints to the matching project.PersonorOwnercontains the intended Notion user.Datecontains 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.