The first time I tried to push code from my work machine, GitHub said no. Not a polite error — a flat 401 on every git clone and git push, while the exact same credentials worked fine through the API. My files were ready, my commit message was written, and the normal road was closed. That afternoon I learned to push to GitHub without git — not as a party trick, but as the only way my projects were going to ship. Two months later, this API workflow has pushed hundreds of commits across a dozen repositories, and I have not missed git push once.

Why I Can't Just Use Git

My setup is unusual, and the problem started there. I work from a Linux VM where my GitHub credential is substituted only for api.github.com — the API endpoint. Git transport (github.com over HTTPS or SSH) never sees that credential, so every clone and push dies with a 401. Worse, several of my repos track large files with Git LFS, and the LFS objects are unreachable from this machine too, so even a successful clone would arrive broken: package.json files that are actually LFS pointers, builds that cannot run.

I had three options: stop shipping from this machine, fight the network setup for days, or learn the layer underneath git. I picked the third. Git is, at its core, a content-addressed object store with a friendly command line on top — and GitHub exposes that store directly through its git-database API. Blobs, trees, commits, refs: the same four objects git manipulates locally, available as HTTP endpoints. Once I understood that, the 401 stopped being a wall and became a detour.

How to Push to GitHub Without Git: The Four API Objects

A git commit is not magic. It is four objects linked together, and the API lets you build each one by hand:

  1. Blob — the content of one file. You POST the file's contents (base64-encoded) and GitHub returns a SHA.
  2. Tree — a directory listing: filenames mapped to blob SHAs. You POST the tree and get a tree SHA.
  3. Commit — a commit object pointing at a tree, with a parent commit, a message, and author/committer idents. You POST it and get a commit SHA.
  4. Ref — the branch pointer. You PATCH refs/heads/main to the new commit SHA, and the branch moves.

That is the entire push. git push does exactly this, plus negotiation, packing, and delta compression you do not need for ordinary changes. My multi-file helper follows the same sequence: create blobs for every changed file in parallel, build one tree on top of the current branch head, create one commit with explicit author and committer idents, then move the ref — and refuse to move it if the remote head has moved since I started, so I never silently overwrite someone else's work.

For a single-file change the flow is even simpler: GitHub's Contents API lets you PUT one file with a message and a branch, and it builds the commit for you. I keep both helpers around — the single-file one for quick fixes, the multi-file one for real work — because reaching for the wrong one is how you end up with ten commits where one would do.

The SHA Rebuild Trick Nobody Tells You About

Here is the part that surprised me most: a commit SHA is not random. It is a SHA-1 hash of the commit's exact bytes — tree line, parent line, author line, committer line, blank line, message. If you can reproduce those bytes, you reproduce the SHA. That matters because after an API push, my local clone does not know about the new commit; the only way to keep local and remote history in sync is to rebuild the identical commit object locally with git hash-object and move the branch pointer to it.

The catch is that GitHub does not store exactly what it echoes back. Twice I learned this the expensive way. First, the API's POST response once echoed an author timestamp of 09:19:23Z while the stored object actually carried 09:22:08Z — a small difference, a completely different SHA. Second, GitHub is inconsistent about trailing newlines on commit messages: sometimes it stores the message verbatim, sometimes with \n appended, and the JSON response shows neither. And the ident timezone can be +0000 or +0500 depending on which session pushed.

So my rebuild script brute-forces the combinations: message with and without a trailing newline, both timezone suffixes, and timestamps swept at one-second granularity over a window of a couple of hours around the echoed time. The old script swept in 30-second steps and missed a real commit whose offset was 165 seconds — a one-second sweep is the only honest one. The byte length in the commit header must be the byte length too, not the character count: an em-dash in a message once threw the whole calculation off by two bytes. When the rebuilt SHA matches the API-returned SHA, local and remote are in sync, and only then do I move the branch.

The Three Traps That Cost Me Real Hours

Trap one: the workflow directory. My token cannot modify anything under .github/workflows/ through the API — nested tree entries there return 404, hand-built trees return 422, and Contents PUTs return 404 — while identical operations under scripts/ or docs/ work fine. The token almost certainly lacks the Actions workflow scope. Workflow fixes go through the GitHub web UI, by hand. I spent an afternoon debugging this before accepting it as a platform rule rather than a bug in my code.

Trap two: the wrong path in the push helper. One of my helpers takes the repo-relative path on the left of an equals sign and the local file on the right. Passing a repo name there instead of a path silently created a junk file at that literal path in the repo root, reported "OK pushed", and left the real file untouched. A broken automation config went live and a scheduled run failed before I found the junk file. The fix is a rule I now follow without exception: after every push, fetch the file back from the remote tree and grep for the expected change. A push receipt is not proof — the remote tree is.

Trap three: API-built history leaves the local clone incomplete. The helper writes files through the API and rebuilds only the commit object locally, not the tree objects. So git log reads fine, but git status can fail with "bad tree object HEAD" because the local object store never received those trees. If a later task needs diff-based workflows against HEAD, re-clone or fetch the objects first instead of debugging a working tree against a HEAD it cannot materialise.

The Verification Rule I Never Skip

Every push ends the same way: I fetch the remote tree with GET /git/trees/<sha>?recursive=1 and confirm every pushed path is present with the right blob SHA. Then, for anything user-facing, I check the live surface — the deployed site, the workflow run, the page itself. This rule has caught a silent build failure, a junk-path push, and a push that "succeeded" while the site kept serving the old build for nearly an hour. The lesson generalises far beyond this workflow: a success message from a tool is a claim, not evidence. Evidence is the remote state, read back.

There is a second half to this rule. When the remote head moves while I am working, I walk its parent chain before assuming anything was rewritten. More than once the new head turned out to be a linear extension of my own work — two commits from a parallel session, nothing lost — and reconstructing those commits locally restored sync without any force-push. Force-push is the one operation this workflow never uses.

When This Workflow Is (and Isn't) Worth It

Use it when git transport is blocked, when you are automating pushes from a sandbox or a serverless function, or when you want a script to push exactly one curated commit with no working-tree state at all. It is also the fastest way I know to truly learn git's object model.

Do not use it as a daily driver if normal git works. You lose git status, git diff, merge conflict resolution, and every safety net the working tree provides, and verification becomes a manual discipline — skip it once and you will ship a junk file with a green receipt, as I did. Keep workflow-file edits out of it entirely; that scope gap is real.

What surprised me most is how portable the lesson turned out to be. The same "read the remote state back, never trust the receipt" discipline now shapes how I deploy sites, submit URLs for indexing, and verify scheduled jobs. The API workflow started as a workaround for a 401 — it ended up as the most reliable shipping habit I have, and the reason projects like the free software library at filecobra.com and the tools I write about on rehmanahmad.com/blog keep moving on days when the normal road is closed.

Push to GitHub Without Git: The Checklist

  • Map the constraint first. Confirm whether git transport, the API, or both are blocked — the fix depends on the answer.
  • Learn the four objects. Blob, tree, commit, ref. If you can build them by hand once, you understand every push you will ever make.
  • Use explicit idents. Always pass author and committer name, email, and date when creating a commit through the API, or the SHA will not be reproducible locally.
  • Rebuild and match the SHA. Reconstruct the commit locally and compare SHAs before moving any local branch pointer.
  • Sweep timestamps at one-second granularity, and brute-force the message-newline and timezone variants. The API echo is not the stored truth.
  • Verify from the remote tree. Fetch the tree back and grep for your change. A push receipt proves nothing on its own.
  • Never force-push. Walk the parent chain when the remote head moves; it is usually a linear extension, not a rewrite.
  • Keep workflow files out. .github/workflows/ needs the web UI or a broader token — plan for it instead of debugging it.
  • Keep the single-file helper for single files. One file, one Contents PUT. Anything bigger gets the blob-tree-commit flow in a single commit.

The best tool is rarely the one with the most features. Sometimes it is the one that works on the machine you actually have, on the day you actually need it. Mine is a handful of API calls and a verification habit — and it has never once left a project stranded.