GitHub Engineering’s Communication Playbook Goes Public

GitHub has been remote-first since its founding, and its engineering organization—now over 1,500 engineers—has spent years refining how to collaborate asynchronously at scale. Today, the company is publishing that internal guidance as “How we communicate” under a CC-BY-4.0 license, inviting other organizations to fork, adapt, and learn from it.

The guidance emerged from a collaborative effort in early 2023, when GitHub’s Engineering Operations and Culture team worked with more than 100 engineers to define shared expectations for internal communication. The goal wasn’t to enforce uniformity but to establish a common baseline across autonomous teams, reducing the overhead of renegotiating communication norms before any cross-team work could begin.

Eight principles, then prescriptive practices

At the heart of the document are eight guiding principles:

  • Be asynchronous first.
  • Write things down.
  • Make work visible and overcommunicate.
  • Prefer GitHub tools and workflows.
  • Embrace collaboration.
  • Foster a culture that values documentation maintenance.
  • Communicate openly, honestly, and authentically.
  • Remember, practicality beats purity.

From these principles, the team developed concrete practices for the most common communication formats—chat, discussions, issues, project boards, pull requests—as well as guidance on managing notifications, running effective meetings, and scheduling with inclusivity in mind.

Taming the notification fire hose

With thousands of engineers across functions, GitHub Engineering’s biggest challenge was the classic signal-to-noise problem: engineers could either receive a “fire hose” of every notification or tune out entirely. Many ended up missing important information either way.

The solution involves a mix of structural changes and automation built around GitHub’s native features. Since engineers already work on GitHub.com, GitHub Discussions became the primary channel for sharing information both within and across teams.

Opt-in subscriptions over org-wide broadcasts

Teams were encouraged to post discussions to the most logical repository (github/copilot for Copilot topics, github/actions for Actions, etc.) rather than the central github/engineering repository. This lets interested individuals subscribe to specific repositories and receive notifications only for topics they care about, while reducing the noise reaching the entire organization.

“Magic labels” for broad amplification

Some posts—like staff ships, required actions, promotions, and priority updates—need to reach all of GitHub Engineering. A small set of “magic labels” handles this case: when applied to a post, the label adds it to a daily content roundup and automatically amplifies it across the organization. An excerpt from the reusable GitHub Actions workflow that applies these labels:

label:
          - name: eng-action-required
            description: Upcoming process/workflow changes/activities requiring Engineering Hubbers to take action
          - name: eng-availability
            description: Discussions about availability, incident response, et al
          - name: eng-celebrations
            description: Celebrating Hubber promotions and other amazingness
          - name: eng-feedback-request
            description: Posts requesting feedback from the Engineering organization
          - name: eng-org-change
            description: Announcements related to organizational changes
          - name: eng-priorities
            description: Discussions related to Engineering priorities
          - name: eng-roundup
            description: Newsletters, weekly digests, and other content and team roundups
          - name: eng-show-and-tell
            description: Share what you've learned or show off something you've made
          - name: eng-staff-ship
            description: Announcements for features made available to Hubbers for feedback and early access
          - name: eng-strategy
            description: Discussions related to strategy and vision

GitHub Actions also runs a scheduled workflow that creates daily and weekly digests of labeled activity, posting them as discussion threads in github/engineering.

Screenshot of the GitHub Actions workflow in the eng-ops-automations repository that creates roundups of activity based on labels and posts them as discussions in the github/engineering repository.

These roundups consolidate notifications into a single daily email or web digest, making it easier to catch up after time away from the keyboard. For engineers who prefer real-time updates on every labeled post, the #engineering-discussions-firehose Slack channel streams everything as it’s posted.

AI-assisted skimming

To make the roundups more scannable, GitHub Engineering turned to Azure’s OpenAI service. Many authors already write TL;DR summaries at the top of posts, but for those that don’t, AI drafts one. The prompt used for these summaries is published in the public repository.

// OpenAI
export const encodingModel = "gpt-3.5-turbo";
export const openaiModel = "gpt-35-turbo";
export const openaiPrompt = `
  The following is an internal discussion post from the engineering department at GitHub formatted in GitHub flavored Markdown. Please write a short summary appropriate for inclusion in a digest of internal discussion posts with the following requirements:

  - The summary should be no more than 3 sentences
  - The summary should focus on the most important and impactful information from the post, including key points and any calls to action
  - The summary should be detailed, thorough, to-the-point, and written for a technical audience, while maintaining clarity and conciseness
  - The communications style should be professional, but informal
  - The summary should use emoji where appropriate, but use emoji sparingly
  - The summary should be formatted in GitHub Flavored Markdown with no line breaks
  - DO NOT use the phrases "the engineering department" or "at GitHub"; instead, whenever possible, name the specific team in reference, or else use "we" to refer to the team or engineering department. For example, use, "We recently shipped a feature", and NOT, "The engineering department at GitHub recently shipped a feature".
  - Employees at GitHub are referred to as "Hubbers"
  - GitHub is ALWAYS capitalized as "GitHub", never "Github"
  - Teams are referred to as "the Actions team" or "the Copilot team", never just "actions team" or "copilot team"
`;

export const estimatedPromptTokens = 300;
export const completionTokens = 300;

Interestingly, the workflow itself was built with heavy assistance from GitHub Copilot—an apt demonstration of robots helping humans teach robots to summarize human work for other humans. The AI summaries aren’t always perfect, but they’ve proven reliable enough for daily use.

Getting started with your own guidelines

For organizations looking to adopt similar practices, GitHub suggests starting with principles: define the core values you want to promote, then ensure alignment across teams so there’s a common “API” for how everyone communicates. Next, translate those principles into specific, actionable practices. Finally, experiment with automation—using GitHub Actions, AI tools, or other solutions—to reduce noise and improve workflows.

GitHub acknowledges communication guidance is never static. The published document is lightly edited for the community (internal URLs and references removed) and will continue to evolve alongside the organization. Pull requests are welcome at github/github-how-engineering-communicates.