How to Use GitHub for Journalism Projects (2026) Guide

If you have ever lost a working scraper two days before a story published, or had to explain to an editor exactly how one number in a graphic was produced, GitHub is the fix. Learning how to use GitHub for journalism projects takes about an afternoon of setup, and the payoff is a versioned, reviewable, reproducible record of everything your team builds for a story. You do not need to be a programmer. You do need to be willing to stop saving files as final_v2_REAL.xlsx.

GitHub is a cloud platform that stores a project folder and every change ever made to it, using Git, a version control system that records each edit as a labeled snapshot. For a newsroom, that snapshot history doubles as an audit trail: you can see who changed a figure, when, and why, and you can roll back to Tuesday’s script after a bad edit on Wednesday. Spreadsheets and shared drives cannot do that. Google Drive keeps file versions but does not tell you what changed inside a script, who requested the change, or whether the input data was replaced.

This guide walks through the workflow I would set up for a new data story: create the repository, plan the work, commit as you go, review through pull requests, protect the main branch, document the decisions, and publish a preview when the piece is ready. It also covers the part that matters most in a newsroom and that most tutorials skip entirely, which is what must never land in a repository.

What You Need

You need four things: a GitHub account, a repository to hold the project, the people who will work on it with you, and one way to make changes. That last part is either your computer with Git installed, or nothing at all if you would rather work entirely in the browser.

The four prerequisites and what each one is for

• A GitHub account. Free for individuals and public repositories. Sign up with your work email so an organization can claim the account later.
• A repository. A single project folder on GitHub, with its own history. One investigation usually gets one repository.
• Collaborators. Add people from the repository’s Settings, or invite an outside reviewer on a specific pull request only.
• A way to edit. Git installed on your machine with an editor such as Visual Studio Code, the GitHub CLI for scripted work, or the built-in web editor for quick changes.

Readers without a terminal can do everything in the browser. Open a file in the repository, click the pencil icon, change the text, then type a description and commit directly from the page. Nothing in this guide requires you to open a terminal, though the local loop in step 3 is faster once you get used to it.

Public or private, and who gets to see it

Decide visibility on day one, because switching a repository to public publishes its entire history, including deleted files. Public repositories are searchable and free. Private repositories require a paid plan for organizations with more than a few private collaborators, and individual private repositories have a limited free allowance.

Permissions are simple enough to remember: read lets someone view, triage lets someone manage issues without changing code, write lets someone push branches, and maintain lets someone change settings and merge. Add an editor as a write collaborator on a private repository if they need to review code, or invite them on the pull request if they only need to leave comments once.

If your outlet already has a GitHub organization, ask for a repository there rather than creating one under your personal account. Repositories that live on someone’s personal profile disappear from the team when that person leaves the newsroom, and they cannot be governed by an organization’s rules or billing.

GitHub concept mapped to the newsroom version

GitHub concept	What it actually is	Newsroom equivalent
Repository	A project folder plus its full change history	The story folder, but with a memory
Commit	A labeled snapshot of the project at one moment	Version 3 saved in your shared drive
Commit message	The sentence explaining why you made the change	The note in your documentation log
Branch	A private copy of the project you test changes on	A scratch copy of the story you break safely
Pull request	A request to merge one branch into another, with review	Submitting a draft for editor sign-off
Merge	Accepting those changes into the main version	The version the whole team works from
Merge conflict	Two people changed the same lines, so Git asks a human	Two desks rewrote the same paragraph
Issue	A tracked task with a discussion thread	A line on the assignment tracker
Release	A named, frozen snapshot, often the published version	Archiving the approved version at publication
Fork	Your own copy of someone else’s public repository	Downloading a template to adapt it

Step-by-Step

Seven steps take a journalism project from an empty folder to a reviewable, publishable one. The order matters less than the habit, and the habit is that nothing changes on the main version without a commit and a review behind it.

1. Create a Repository for the Journalism Project

To use GitHub for journalism projects, you create one repository per story, choose an owner, give it a descriptive name, and decide whether it is public or private. Ten minutes of setup here saves hours of confusion later.

The current web workflow: sign in and open your profile or the organization’s page, then choose Create new repository from the plus menu at the top right. Enter a short descriptive name with no spaces, such as school-district-spending, and a sentence describing the project. Choose visibility, then tick Add a README file so the repository starts with a landing page, and add a .gitignore if the project will hold Python or R work, which tells Git to skip folders like virtual environments and your operating system’s clutter.

You know it worked when you can open the repository on GitHub and read your README at the top of the file list. Note that exact menu labels shift slightly between GitHub Free, Pro, Team and Enterprise plans, so if you do not see an option, check which plan the organization is on before assuming you did something wrong.

A useful starting structure for a data story looks like this, and keeping it from day one prevents the folder sprawl that makes handoffs painful:

• data/raw/ — files exactly as the source delivered them, never edited
• data/clean/ — the cleaned and processed versions, generated by scripts
• notebooks/ — analysis in Jupyter notebooks or R Markdown
• scripts/ — reusable cleaning and scraping code
• output/ — generated charts, tables and data for the story
• docs/ — source list, methodology, decisions and notes

GitHub renders .ipynb notebooks directly in the browser, so an editor can read your analysis without installing anything. That single feature is often the argument that wins a newsroom over a shared drive.

2. Plan the Work in GitHub Projects and Issues

Turn your assignment into issues, then group them on a project board so the whole team can see status at a glance. Every piece of work gets an issue: reporting, data cleaning, design, development, fact-checking, accessibility, and publication.

From your repository, open the Issues tab and select New issue. Give it a short imperative title, such as “Fix y-axis on budget-by-district chart”, and use the body for the detail: what is wrong, what the correct value should be, and a link to the source material or the reporting memo that settles it. Add labels so work can be filtered, an assignee so ownership is clear, and a due date that matches the story calendar.

A project board is the kanban layer on top of that. Open Projects, create a board, and add columns for to do, in progress, in review and done. Issues and pull requests get dragged across it. If your team already lives in an assignment tracker, GitHub boards do not have to replace it, and for small teams they are often the first thing to drop because the drag-and-drop view stops being interesting after the second story.

The payoff shows up on deadline days. When a reporter asks what state the data cleaning is in, the answer is a board rather than a group chat scroll.

3. Make Changes Locally and Commit Them

The local loop is clone, branch, edit, add, commit, push. Run it once end to end and Git stops feeling mysterious. Commit often, and treat every commit as a sentence a colleague could read six months from now.

Here is the sequence with a plain-English gloss on each line. The first six run once per project, the rest repeat every time you make progress.

git clone https://github.com/your-org/school-district-spending.git   # download the project
cd school-district-spending                                          # work inside it
git switch -c fix-district-names                                          # create a safe branch
git status                                                               # what changed so far
git diff                                                                 # exactly which lines changed
git add data/clean/districts.csv                                         # stage one specific file
git commit -m "Correct Madison County name to match state source"        # save with a reason
git push -u origin fix-district-names                                    # share the branch

git status answers “am I in trouble?”, git diff answers “what did I just change?”, and git log --oneline gives you the running history of the project with the newest first. Pull with git pull before you start work so you are building on the latest main version, and stage files by name rather than using git add ., which is how scratch files and half-finished experiments sneak into commits.

Write commit messages in the imperative and say why, not what. “Add districts” is a what; “Add districts to fix dropped rows in the state source join” is a why. When a story is challenged a year later, the why is what makes the number defensible.

One rule is non-negotiable in a newsroom: never commit embargoed data, personal information, source documents, unpublished reporting material, credentials or API keys. Git stores history, so a secret pushed once stays retrievable even after you delete the file. Add sensitive paths to .gitignore before your first commit, keep anything under embargo in an encrypted store or a private, access-limited system, and rotate any credential that was ever pushed by mistake.

4. Open Pull Requests for Review

A pull request is how work gets reviewed before it reaches the shared version. You push a branch, open a pull request, and a colleague reads the line-by-line differences and leaves comments without touching your files.

After pushing your branch, GitHub shows a Compare & pull request link. Open it and fill in three things: the title, a short description of what changed and why, and a link to the issue it closes. Typing Closes #42 in the body links the work automatically once it merges.

Then assign reviewers. For a newsroom, this is where a standards or legal check can live: the pull request itself becomes the sign-off artifact, with every comment kept in one thread. Pick the correction example and it reads clearly. Someone maps school spending by district, an intern and a senior reporter both edited the map file on the same day, and the intern opens a pull request titled “Repair county boundaries on district spending map” that fixes the county lines and adds the state shapefile date in the description. The reporter approves, a second person approves if your branch protection requires it, and the merge happens with a permanent record of who checked what.

Responding to feedback is ordinary work. Make the requested change on the same branch, push again, and the pull request updates automatically with a new commit. Conflicts appear when two people changed the same lines; GitHub marks them inline, you edit the file to combine both versions, then commit and push again.

5. Protect the Main Branch

Turn on branch protection for the main branch so nobody can change it directly, and every change arrives as a reviewed pull request. Open Settings, then Branches, add a rule for your main branch and require a pull request before merging.

Three settings do most of the work. Requiring a pull request stops direct edits. Requiring approvals, set to one or two people, stops solo merges. Requiring status checks makes the project wait for automated tests or checks to pass before anyone can merge. Adding Require linear history keeps the main branch readable as a straight line of changes, which matters more to a legal reviewer reading the history than it does to a developer.

Match the process to the risk. A solo reporter learning Git does not need two approvals, and requirement fatigue leads people to disable the rules entirely. A shared investigative repository should require at least one reviewer, and anything that will be published should require a second set of eyes. Availability of some review and ruleset features depends on the organization’s GitHub plan, so check with whoever administers it.

6. Document Decisions, Data, and Handoffs

Write the documentation so an editor, a lawyer or your future self can understand the project without a meeting. Four files cover almost everything: a README, a CONTRIBUTING guide, issue templates, and a data document inside docs/.

The README is the front door. Open with what the project investigates and who is responsible, then add how to run it locally with exact commands, where the source data comes from with URLs and retrieval dates, and known limitations. A reader who can rerun your analysis from your README alone has a reproducible project, which is the standard serious data journalism aims for.

The CONTRIBUTING guide tells outside contributors how you work: branch naming such as yourname-short-description, commit style, how to submit a pull request, and what review means here. Issue templates turn repeated questions into a form, so a volunteer bug report arrives with the browser, steps and screenshot already filled in.

Document data decisions where the code cannot show them. Which columns you dropped and why, which outliers you excluded, how a county name was matched across two sources, what the analysis cannot answer. This is what protects you when a figure is challenged, and it is the material a standards editor will ask for.

Handoffs are where documentation pays off most. When a reporter leaves, the new person reads the README, the docs/ folder and the closed issues, and knows what is running, what is known to be broken, and where the last published version lives. Newsroom practitioners treat handoffs and sunsets as first-class work for exactly this reason, and a repository with good history makes both far less painful.

7. Publish a Project Preview or GitHub Pages Site

You publish with GitHub Pages for a static preview and a GitHub Actions workflow that builds and deploys the project automatically. Treat this as a preview surface for a prototype, not a content management system for your published journalism.

For a notebook collection or a small static site, open Settings, then Pages, choose the branch and folder to publish from, and save. GitHub builds the site and gives you a URL you can check before anyone else sees it. For anything with a build step, add a workflow file under .github/workflows/ that installs dependencies, runs tests and deploys on merge to the main branch. The Actions tab shows whether each run passed or failed, which is where you look when a deploy breaks.

Two rules for a newsroom. Keep the automated deploy pointed at a staging URL until an editor has signed off, and never let an automated build pull unpublished or embargoed material into a public site. A public static preview and an embargo-safe private workflow are different setups, and the distinction is worth deciding out loud before publication day rather than during it.

Worth reading while you set this up: The Pudding and BuzzFeed News publish their analysis repositories publicly, and FiveThirtyEight’s and The Associated Press’s data projects are public reading material for structure. The Data Journalism Primer points to these and to classroom syllabi. Open a couple of their READMEs and copy what you like; that is faster than designing a convention from scratch.

Common Mistakes

Almost every painful GitHub story in a newsroom comes from one of a handful of habits. Here they are with the fix.

• Pushing secrets, source documents or personal data into a public repository. Fix: add sensitive paths to .gitignore before the first commit, and rotate any credential that was ever pushed.
• Editing the main branch directly. Fix: turn on branch protection so the only path in is a pull request.
• Vague commit messages like “fixes” or “stuff”. Fix: say what changed and why, in one line, in the imperative.
• Pull requests with three unrelated changes at once. Fix: one idea per branch and per pull request, so a reviewer can approve or reject each part.
• Contributor instructions nobody reads. Fix: keep CONTRIBUTING short and link it from the README.
• Dependency drift. Fix: commit an environment or requirements file so a re-run a year from now installs the same versions.
• Deploying publicly before anyone reviews. Fix: point automation at staging until sign-off, and treat “it is on a preview” as still unpublished.

Start small and stay consistent: one repository per story, branches named the same way every time, review before merging, and a note in the README about how to roll back. None of that is exotic. It is just a small set of rules applied before a deadline makes them optional.

Frequently Asked Questions

Conclusion

Start with the smallest useful version: create or join the repository for the story you are working on, write a short README that says what the project is and who owns it, and turn the first assignment into an issue. Then make one commit and see what it looks like in the history.

Add safeguards in proportion to the risk. A solo prototype needs a README and a private repository. An investigation shared across desks needs branch protection, a reviewer on every pull request, and a documented place where sensitive material lives. Those three things cover most of what goes wrong, and none of them require a newsroom to change how it publishes.