DEV Community

sunah kim
sunah kim

Posted on Originally published at zenn.dev

Connecting Zenn to a GitHub Repository: The Setup Steps and Two Pitfalls

#zenn #github #blogging #tutorial

Introduction

In my previous article, I introduced a pipeline that cross-posts from a single GitHub repository to Zenn, dev.to, and velog. I briefly touched on Zenn's GitHub integration there, but that part was actually where I stumbled first. In this post, I'll zoom in on just the integration: the correct setup steps, and the two pitfalls I actually ran into. If you follow the steps in this order, you should be able to avoid the same swamps.

(For context: Zenn is one of the most popular tech blogging platforms in Japan, and its killer feature is publishing articles by simply pushing Markdown to a connected GitHub repository.)

What the GitHub integration gives you

Once connected, pushing Markdown files under articles/ in your repository publishes or updates articles automatically. No web editor needed, and your articles get proper Git history. Private repositories work too, so your drafts and idea notes stay private while only the published articles become public.

The correct setup flow

  1. Log in to Zenn and open "Deploy from GitHub" in the dashboard (zenn.dev/dashboard/deploys)
  2. Start the connection from the "Connect repository" button on Zenn's side, then pick the target repository on GitHub's authorization screen (I recommend granting access to only the selected repository, not all repositories)
  3. After the connection completes, pushing an article triggers a deploy, and the deploy log shows up in the dashboard

It looks completely unremarkable — the point is that you must start from Zenn's side.

Pitfall 1: Installing the app from GitHub's side doesn't connect anything

This was my first mistake. I installed the Zenn Connect app from the GitHub Marketplace first, and the connection never showed up in Zenn's dashboard. No error message either, so I had no idea what was wrong.

The cause is how the connection flow is designed. Zenn's GitHub integration assumes the OAuth authorization and repository selection happen from Zenn's own screen. Installing the app from GitHub's side alone never creates the link to your Zenn account. The official docs even state explicitly: if the app is already installed and you see this screen, uninstall it once and reconnect.

The fix: uninstall Zenn Connect from GitHub's Settings → Applications, then redo the connection from Zenn's "Connect repository" button. After that, it showed up in the dashboard immediately.

Pitfall 2: Commits pushed before connecting never get deployed

Just when I thought I was done, the next trap. Articles I had pushed before connecting never got deployed, no matter how long I waited.

The cause: only pushes made after the connection is established are detected as deploy targets. Existing commits are not processed retroactively.

The fix: push a new commit after connecting. An empty commit is enough.

git commit --allow-empty -m "trigger zenn deploy"
git push
Enter fullscreen mode Exit fullscreen mode

That triggered the first deploy, and my existing articles finally appeared in the dashboard.

How article files work

Deploy targets live at articles/<slug>.md. The slug must be 12–50 characters of lowercase letters, digits, and hyphens — anything outside that range fails at deploy time. It's easy to pick a slug that's too short, so watch out.

The front matter looks like this:

---
title: "Article title"
emoji: "🔗"
type: "tech" # tech or idea
topics: ["zenn", "github"] # lowercase, up to 5
published: true # false means draft
---
Enter fullscreen mode Exit fullscreen mode

Pushing with published: false keeps the article as a draft, so it's safest to verify your deploy setup with a draft first.

Summary

  • Always start the connection from Zenn's "Connect repository" button. If you installed the app from GitHub's side first, uninstall it and reconnect
  • Commits pushed before connecting are never deployed. Push an empty commit after connecting to trigger the first deploy
  • Slugs are 12–50 characters of lowercase letters, digits, and hyphens. Use published: false for drafts
  • Private repositories work, so only the articles go public while your writing history stays private

By the way, the pushes to this repository are themselves automated as a scheduled task run by an AI agent. The full picture is in my previous article if you're curious.

Top comments (0)