Status first: I built this admin and ran 41 API checks against mock GitHub, dev.to and IndexNow servers. I have not run it against the live services yet. Treat the code below as a pattern tested against mocks, not a battle-tested one.

The short answer

Commit with one request:

PUT /repos/{owner}/{repo}/contents/{path}

Send message, content (the file, base64-encoded) and branch. For an update, also send the file's current sha. A new file needs no sha. A stale sha returns 409. Show that to the editor instead of retrying blindly. After the commit, Vercel redeploys the site.

You also get git history, diffs and rollback for every edit, because the content is just files in the repo.

Set up the GitHub Contents API as a CMS

Articles are Markdown files in content/articles/<slug>.md. The admin runs on the server side of the same Next.js app, so the GitHub token never reaches the browser.

Environment variables (names only):

GITHUB_TOKEN
GITHUB_OWNER
GITHUB_REPO
GITHUB_BRANCH
SITE_ORIGIN

Use a fine-grained personal access token limited to this one repository, with Contents set to read and write (as of October 2026, verify the permission name in GitHub's settings). Never prefix it with NEXT_PUBLIC_.

Read and write a file

This is a minimal version written for Next.js 16. It is server-only code.

// lib/github-content.ts
const OWNER = process.env.GITHUB_OWNER;
const REPO = process.env.GITHUB_REPO;
const BRANCH = process.env.GITHUB_BRANCH || "main";
const base = `https://api.github.com/repos/${OWNER}/${REPO}/contents`;

function ghHeaders() {
  return {
    Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
    Accept: "application/vnd.github+json",
    "X-GitHub-Api-Version": "2022-11-28",
    "Content-Type": "application/json",
  };
}

export function isValidSlug(slug: unknown) {
  return typeof slug === "string" && /^[a-z0-9-]{1,80}$/.test(slug);
}

export async function readArticle(slug: string) {
  const res = await fetch(
    `${base}/content/articles/${slug}.md?ref=${BRANCH}`,
    { headers: ghHeaders(), cache: "no-store" }
  );
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`GitHub read failed: ${res.status}`);
  const data = await res.json();
  const markdown = Buffer.from(data.content, "base64").toString("utf8");
  return { markdown, sha: data.sha };
}

export async function writeArticle(slug: string, markdown: string, sha?: string) {
  const res = await fetch(`${base}/content/articles/${slug}.md`, {
    method: "PUT",
    headers: ghHeaders(),
    body: JSON.stringify({
      message: sha ? `Update article: ${slug}` : `Add article: ${slug}`,
      content: Buffer.from(markdown, "utf8").toString("base64"),
      branch: BRANCH,
      sha,
    }),
  });
  if (res.status === 409) return { conflict: true, sha: null };
  if (!res.ok) throw new Error(`GitHub write failed: ${res.status}`);
  const data = await res.json();
  return { conflict: false, sha: data.content.sha };
}

JSON.stringify drops sha when it is undefined, so one function handles both create and update. Validate the slug before it becomes part of a path. That regex is what stops ../ tricks.

The route handler

// app/api/admin/articles/route.ts
import { NextResponse } from "next/server";
import { cookies } from "next/headers";
import { verifySession } from "@/lib/session"; // your own signed-cookie check, not shown
import { isValidSlug, writeArticle } from "@/lib/github-content";

export async function PUT(req: Request) {
  if (req.headers.get("origin") !== process.env.SITE_ORIGIN) {
    return NextResponse.json({ error: "Bad origin" }, { status: 403 });
  }
  const store = await cookies();
  if (!verifySession(store.get("admin_session")?.value)) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { slug, markdown, sha } = await req.json();
  if (!isValidSlug(slug) || typeof markdown !== "string" || markdown === "") {
    return NextResponse.json({ error: "Invalid input" }, { status: 400 });
  }

  try {
    const result = await writeArticle(slug, markdown, sha);
    if (result.conflict) {
      return NextResponse.json(
        { error: "File changed on GitHub. Reload before saving." },
        { status: 409 }
      );
    }
    return NextResponse.json({ sha: result.sha });
  } catch {
    return NextResponse.json({ error: "Publish failed" }, { status: 502 });
  }
}

In Next.js 15 and later, cookies() is async, hence the await. This route has no dynamic segment. If you add one, params is a Promise too. Next.js 14 is sync for both.

The sha rule and the 409

Updating a file needs the blob sha of the version you are replacing. Get it from a read (GET .../contents/{path}) and send it back with the edit.

Two details cause most bugs:

• Keep the new sha. A successful PUT returns the new file sha in content.sha. Store it in the editor's state. If you keep sending the old one, the second save fails.

• Do not auto-retry a 409. It means the file (or the branch) changed since you read it, for example from a second tab or a direct commit. Fetching a fresh sha and resending would silently overwrite that change. Return the 409 and let the editor reload.

Browser side:

const res = await fetch("/api/admin/articles", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug, markdown, sha }),
});
if (res.status === 409) {
  // tell the editor to reload
} else if (res.ok) {
  const data = await res.json();
  sha = data.sha; // use this on the next save
}

Pitfalls

• Every save is a commit, and every commit can trigger a deploy. Keep draft: true in the front matter until the article is ready, and save less often.

• UTF-8 and base64. Encode on the server with Buffer. In the browser, btoa throws on characters outside Latin-1, which includes Bangla text.

• Write one file at a time. Parallel writes to the same branch can conflict. GitHub advises serial requests (as of October 2026, verify in the REST docs).

• Branch protection. If the target branch requires pull requests, the direct commit is rejected. Commit to a branch that allows it.

• Large files. The Contents API has size limits. Keep articles as text and store images elsewhere (as of October 2026, verify the current limits).

• A missing sha on an existing file is rejected with a validation error, not a 409 (as of October 2026, verify the exact status code).

• Protect the login route. Anyone who gets past the admin password can commit to your repo. Put a rate limit in front of it, as in Next.js rate limiting with Upstash Redis.

• Not tested live. Everything above passed against mock servers only. Run one real commit to a scratch branch before you rely on it.

Summary

• One PUT /repos/{owner}/{repo}/contents/{path} call turns a browser form into a commit, and the host redeploys.

• New files need no sha. Updates need the current sha, and you must store the new one after each save.

• Treat 409 as "someone changed this". Show it, do not retry blindly.

• Keep the token server-side and scoped to one repo. Validate the slug before building the path.

Next: if you want a 6-digit code login for an admin or app instead of a password, here is the Supabase version. Supabase Email OTP in Next.js.

Originally published at najmulhasan.navicore.co/blog/github-contents-api-cms-in-next-js-publish-markdown-without-a-database.

The short answer

Change the email template to print {{ .Token }}, call signInWithOtp to send the code, then call verifyOtp with type: "email" to create the session. Rate-limit verification per email address.

1. Change the email template

In the Supabase dashboard go to Authentication → Email Templates → Magic Link and replace the link with the token:

<h2>Your sign-in code</h2>
<p>Enter this code to continue:</p>
<p style="font-size:28px;letter-spacing:6px"><strong>{{ .Token }}</strong></p>
<p>It expires soon. If you didn't request it, ignore this email.</p>

If the template still contains {{ .ConfirmationURL }}, users receive a link and the code flow looks broken. Also configure custom SMTP (Resend, Postmark, SES). The default sender is intended for testing and is heavily rate-limited.

2. A server client that handles cookies

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export function createClient() {
  const cookieStore = cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll(list) {
          try {
            list.forEach(({ name, value, options }) => cookieStore.set(name, value, options));
          } catch {
            // Called from a Server Component; middleware refreshes the session instead.
          }
        },
      },
    },
  );
}

3. Send the code

// app/api/auth/send-otp/route.ts
import { NextResponse } from "next/server";
import { z } from "zod";
import { createClient } from "@/lib/supabase/server";
import { clientIp, limiters } from "@/lib/rate-limit";

const Body = z.object({ email: z.string().email().max(254) });

export async function POST(req: Request) {
  const ip = await limiters.otpSend.limit(clientIp(req));
  if (!ip.success) return NextResponse.json({ error: { code: "RATE_LIMIT_EXCEEDED" } }, { status: 429 });

  const parsed = Body.safeParse(await req.json().catch(() => null));
  if (!parsed.success) return NextResponse.json({ error: { code: "INVALID_EMAIL" } }, { status: 400 });

  const supabase = createClient();
  const { error } = await supabase.auth.signInWithOtp({
    email: parsed.data.email.toLowerCase(),
    options: { shouldCreateUser: true },
  });
  if (error) console.error("send-otp", error.message);

  // Same response whether or not the email exists or sending failed: no account enumeration.
  return NextResponse.json({ ok: true });
}

4. Verify the code

// app/api/auth/verify-otp/route.ts
import { NextResponse } from "next/server";
import { z } from "zod";
import { createClient } from "@/lib/supabase/server";
import { limiters } from "@/lib/rate-limit";

const Body = z.object({
  email: z.string().email().max(254),
  token: z.string().regex(/^\d{6}$/),
});

export async function POST(req: Request) {
  const parsed = Body.safeParse(await req.json().catch(() => null));
  if (!parsed.success) return NextResponse.json({ error: { code: "INVALID_CODE" } }, { status: 400 });

  const email = parsed.data.email.toLowerCase();
  const rl = await limiters.otpVerify.limit(email); // keyed by email, not IP
  if (!rl.success) return NextResponse.json({ error: { code: "RATE_LIMIT_EXCEEDED" } }, { status: 429 });

  const supabase = createClient();
  const { error } = await supabase.auth.verifyOtp({ email, token: parsed.data.token, type: "email" });
  if (error) return NextResponse.json({ error: { code: "INVALID_CODE" } }, { status: 401 });

  return NextResponse.json({ ok: true }); // session cookies were set by the server client
}

Key the verify limiter on the email. An attacker can rotate IPs for free but can't change the account they're targeting. The limiter implementation and the numbers are in the Upstash rate limiting guide.

5. Keep the session fresh with middleware

// middleware.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request });
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => request.cookies.getAll(),
        setAll(list) {
          list.forEach(({ name, value }) => request.cookies.set(name, value));
          response = NextResponse.next({ request });
          list.forEach(({ name, value, options }) => response.cookies.set(name, value, options));
        },
      },
    },
  );
  await supabase.auth.getUser(); // refreshes the token if needed
  return response;
}

export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };

Pitfalls

• Users get a link, not a code. The template still contains {{ .ConfirmationURL }}.

• Account enumeration. Returning "no such user" from the send endpoint lets anyone test which emails are registered. Always return { ok: true }.

• Unlimited guesses. A 6-digit code has 1,000,000 values; without a verify limit a fast script covers a large share of them within the code's lifetime. Five attempts per 10 minutes per email caps it at 30 guesses an hour.

• Trusting the client. Use getUser() on the server for authorization decisions, not the session object read from cookies.

• Phone OTP is a separate problem. SMS providers have their own restrictions; for instance, trial tiers can limit delivery to verified numbers, which blocks real users in testing and launch.

Summary

• Template {{ .Token }} → signInWithOtp → verifyOtp({ type: "email" }).

• Same response for every send request; rate-limit by IP on send and by email on verify.

• Run middleware so sessions refresh, and authorize with getUser().

Originally published at najmulhasan.navicore.co/blog/supabase-email-otp-nextjs-6-digit-code.