GitHub reporting for non-technical stakeholders

A GitHub report is any recurring summary of what a team built, derived from the repository rather than from people. The repository already holds a complete record: every change, who made it, when, and what it touched. The work is turning that record into something a reader who does not write code can act on.

Most teams solve this badly. They either tax a senior engineer with writing the summary by hand, or they wire up a feed that dumps commit titles into a channel and call it reporting. This guide covers what a good report actually contains, the four ways teams produce one, and how to choose a scope and cadence that survives past the second month.

What the report has to answer

A stakeholder reading an engineering update wants three things, in this order:

1. What can customers or the business do now that they could not do before?
2. What is in progress, and is it still on the shape we agreed?
3. Is anything stuck?

Notice what is absent. Nobody outside engineering needs a commit count, a lines-changed figure, or a velocity chart. Those numbers describe motion. The questions above describe outcomes, and a report that answers them earns a forward to the board. A report that answers “we merged 47 pull requests” gets skimmed once and then filtered.

This is the test to apply to any reporting setup: could the recipient repeat one sentence of it back to an investor? If not, you built a feed.

Where the raw material lives

Three GitHub artifacts carry the information, and they are not interchangeable.

Commits are the atomic record. GitHub’s own documentation describes a commit as a way to record changes to one or more files in your branch, capturing the specific changes, when they were made, and who made them. Every commit gets a unique hash and a message. Commits are complete, which is their strength, and granular to the point of noise, which is their weakness. A single feature might be thirty of them.

Pull requests group commits into a unit of intent, usually with a title a human wrote deliberately. Better signal per item, but incomplete: plenty of teams push directly to a branch, and a PR title reflects what the author meant to do rather than what landed.

Branches decide what counts. A report that reads every branch in the org includes abandoned experiments and half-finished spikes. Reading the branch you actually ship from is almost always what you want, and getting this wrong is the single most common reason a report reads as noise.

If you want the short version of what these are before going further, start with what a GitHub commit actually is, which also covers what the feat and fix prefixes mean.

The four ways teams do this

Someone writes it by hand

A CTO or engineering manager reviews the week’s merged work, reconstructs the story, and writes the update. The output is the best of any option on this list, because a human who understands both the code and the business is doing the translation.

The cost is that it is a recurring half-day tax on your most expensive technical person, and it decays predictably. Weekly for a month, monthly after that, then only when a board meeting forces it. If your reporting depends on someone choosing to spend Friday afternoon on it, assume it stops.

A script over git log

git log will answer most of the question locally. It takes --since and --until for a window, --author to filter by person, and --pretty=format: to shape the output, all documented in the git log reference. Twenty minutes of shell gets you a per-week, per-author list of commit subjects.

This is genuinely useful for an engineer summarising their own month, and we walk through the exact invocations in generating a commit report from the command line. As stakeholder reporting it falls down on two counts: it runs on someone’s laptop, so nothing arrives unless a person remembers, and the output is commit subjects, which are written by developers for developers.

Scheduled automation

GitHub Actions can run a workflow on a cron schedule, and Zapier offers a prebuilt path that posts a digest of new GitHub commits to a Slack channel on a daily, weekly, or monthly basis. Either removes the “someone has to remember” problem.

Worth knowing before you build on Actions: GitHub documents that scheduled workflows can be delayed during periods of high load, that the shortest interval is five minutes, and that in public repositories a scheduled workflow is disabled automatically after 60 days without repository activity. None of that is disqualifying for a weekly report. All of it will surprise you at the worst moment if you do not know it.

The remaining problem is that automation moves the raw material faster. It does not translate it. See sending a weekly GitHub digest to Slack for what each route actually produces.

A tool that reads the code and writes prose

The newest category reads the diff, not just the commit message, and produces a narrative summary scoped to a project or a team. This is the only approach that removes the translation step rather than relocating it, which is also the reason to be sceptical of any tool in the category that cannot show you its output on your own repository before you pay.

Choosing a scope

Scope is the decision that determines whether the report gets read. Four options, roughly in order of how often they are the right answer:

• By project. A grouping of repositories that maps to something the business already talks about. The best default, because the reader already has a mental model for it.
• By team. Useful once you have more than one squad and a manager who needs to report on theirs specifically.
• By repository. Fine for a single-service product. Misleading the moment a feature spans a frontend and an API, which it usually does.
• By person. Legitimate for a one-on-one or an agency billing a named contractor. Distributed to a channel, it turns into surveillance and the team will route around it.

Repository scope is the tempting default because it matches how GitHub is organised. It is rarely how the business is organised, which is the whole point of the exercise.

Choosing a cadence

Weekly is right for almost everyone. It is long enough that a feature usually completes inside the window, and short enough that a stuck project surfaces before it becomes a quarter.

Daily is worth it only for teams where a day of drift is expensive, and it degrades fast: a daily report on a five-person team is mostly empty, and an empty report trains the reader to stop opening it. Monthly works for a board audience and almost nothing else, because by the time a problem shows up in a monthly report it has already cost you three weeks.

One detail teams get wrong: pick the day and time in the timezone of the reader, not the server. A “Monday morning” report that lands Sunday night for half the recipients reads as broken even when the content is perfect.

Delivery

Email and Slack solve different problems. Email is forwardable and survives, which matters when the actual destination is an investor update or a board pack. Slack is where the team already is, so it gets read, but it scrolls away and nobody digs a report out of channel history three weeks later.

Most teams want both, with the same content. Note that GitHub’s own Slack integration is real-time only. You can subscribe a channel to commits, pull requests, releases and deployments, and it will notify per event as they happen. There is no scheduled digest in it, which is the specific gap the Zapier and Actions routes exist to fill.

Three mistakes worth avoiding

Reporting on every branch. Abandoned spikes and long-lived experiments will dominate the output and make an active week look chaotic. Pick the branch you ship from.

Letting the report include a productivity ranking. The moment a recurring report contains a per-person leaderboard, you have changed what the team optimises for, and you will get more commits and less shipped software.

Treating no activity as an error. A quiet week is information. A report that silently skips empty periods hides exactly the weeks you most needed to know about.

Where to go next

If you are new to reading the underlying material, start with what a GitHub commit is. If you have the material and need to present it upward, read how to report engineering progress to non-technical stakeholders. If you want the delivery mechanics, the Slack digest guide covers the four routes and the command line guide covers doing it yourself. When you are ready to compare products, we maintain a review of the best GitHub reporting tools.

DevSummary exists because the translation step is the hard part and the one nobody wants to own. It connects to a GitHub organization, reads the branch you ship from, and writes a report scoped to a project or a team, on a schedule, to email or Slack.

The repository already knows what your team shipped. Reporting is only the work of making it say so in a language the rest of the company reads.