I was experimenting with my agentic workflow which uses Markdown. I edited the same Markdown, and reran the action, but it surprised me that nothing changed.

The workflow was built for a daily repo report which I’d setup a week ago. There was nothing complex in there. It was using very simple instructions. Whenever I push a file in the repo the job runs and it does it’s thing. The problem was that even after updating the Markdown being used in the workflow, it was doing the same old thing.

Then I went ahead and changed some things in the Markdown file again and pushed it. Still there was no difference at all. It looked exactly like my changes never existed.

This is when I started to think what if GitHub is caching something here.

I went ahead and ran the workflow again. It finished successfully. To make sure I didn’t had anything messed up in the local copy of the repo, I pulled the repo again.

I didn’t find anything messed up there. Everything was good and the new instructions were present.

But, interesting it was not reflecting in the workflow runs.

The part I didn’t realize

I learnt that GitHub workflow Markdown was perfectly fine. It was me misunderstanding what actually executes there.

Interestingly, GitHub runs the compiled lock file for agentic workflows, not the Markdown workflow definition.

I was ignoring the .lock.yml file which was right there next to the Markdown file. I had noticed it earlier but treated it like metadata which is something that is generated and something that is internal. I didn’t think it was something that is important.

But it matters a lot.

This is the most important thing to understand here: the Markdown file describes the intent in Natural language. It is basically the frontmatter config that you want the workflow to do.

But that file is not interpreted every time when the workflow runs.

It gets compiled into a deterministic execution plan. That plan is written into the lock file. And that lock file is what GitHub Actions executes every time.

So when I edited the Markdown, nothing changed… because I never recompiled the workflow.

The executable plan was not in the Markdown file after compilation.

gh aw compile

The above command regenerates the .lock.yml file from the Markdown definition. Without running it, the runtime never sees your changes.

Which explains everything that looked like caching, ignoring, or broken behavior.

It wasn’t any of those.

I was editing the source but the problem was GitHub was running the compiled artifact.

The most important thing I learnt

The Markdown is the source of truth for intent and the lock file is the workflow that actually runs.