How we use GitHub Actions to manage GitHub Docs

👋 Hello from the GitHub Docs team! We build everything you see at docs.github.com. Over the past year, we’ve written a bunch of GitHub Actions workflows to do some fun automation that saves us time and effort. We thought folks might be interested in a peek under the hood.

If you’re new to GitHub Actions, get started at https://docs.github.com/en/actions.

Our docs content and tooling are all open source, so you can check out our full suite of workflow files in https://github.com/github/docs/tree/main/.github/workflows.

Why use GitHub Actions for project management?

As the team responsible for documenting every aspect of GitHub, as well as managing open source contributions from the community, we have a lot of work to track. But every minute (or hour…) we spend on manual project management tasks is one we don’t spend on important content or site improvements that benefit users.

Fortunately, because we use GitHub issues and project boards to manage our work, our project data is accessible via GitHub’s comprehensive REST and GraphQL APIs. This means we can write programs to manage work for us!

GitHub’s APIs existed long before Actions, but in the old days, you had to write scripts from scratch, hook up an Octokit library, or use a framework like Probot. While Probot is awesome, Actions does a lot more heavy lifting out of the box. Within a YAML workflow file, you can use github-script and the GitHub CLI to access the full power of GitHub’s APIs, find and use prebuilt actions from the Marketplace, or write your own action!

We’ve found we can spin up a workflow file in a fraction of the amount of time it would take us to write a new script or create an app. And the YAML format is friendly enough that every member of our team is empowered to contribute, not just engineers.

The fun stuff: our favorite workflows for project management

Our team uses Actions for lots of things—CI/CD, automating API docs, even checking for broken links—but we’ll keep the examples in this post scoped to project management tasks we use all the time in our open source repo.

When a contributor opens an issue, our Triage new issues workflow adds a triage label and moves the issue to the “Triage” column of the repo’s project board. This makes it easy for our maintainers to easily find new issues from the community.

As can be expected of a large open source project, we get a lot of spam. 🗑️ Check for Spammy Issues closes issues that contain too few words, which serves as a reasonable heuristic for spam in our repo. Other issues don’t include enough information to be actionable. If the author of one of these issues does not respond to our request for more info, our No response workflow will close the issue with a friendly message so that our maintainers can focus on actionable issues.

Some areas of the docs, like the REST API reference, are generated using internal automation and cannot be updated manually by outside contributors. Transfer REST API issue to rest-api-description transfers an issue to our open source OpenAPI repo. Copy to REST API issue to docs-content copies an issue to our internal docs repo but keeps the original issue in our open source docs repo so that our contributors retain visibility.

When our maintainers see an issue that they think is good for members of the community to work on, they add a help wanted label to it, and Move help wanted issues puts it in a project board where it is easy for contributors to find.

When a contributor submits a pull request, Check unallowed file changes validates that the pull request doesn’t change certain files.

Triage new pull requests adds a triage label and moves the issue to the “Triage” column of the repo’s project board to make sure our maintainers see it.

After our maintainers approve a pull request, Move and unlabel ready to merge PRs makes sure a member of our team merges the pull request. When the pull request is merged, Merge notification lets the contributor know when they can expect to see their changes go live on docs.github.com.

Sometimes the author of a pull request is unable to continue working on it for any one of a number of reasons. When this happens, Public Repo Stale Check adds a comment with a gentle bump and eventually closes the pull request. If the author comes back to a pull request that was closed due to lack of activity, they are always welcome to reopen it!

Contributions and feedback welcome!

These are just a few of the workflows we rely on every day to help us manage GitHub’s open source documentation. Feel free to take a spin in our workflow directory and let us know if you have any ideas or suggestions in a discussion! Better yet, open a pull request and our actions will tell us all about it. 😁

Written by

Sarah Edwards

@skedwards88