你好从GitHub文档团队!我们构建everything you see atdocs.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 athttps://docs.github.com/en/actions.
Our docs content and tooling are allopen source, so you can check out our full suite of workflow files inhttps://github.com/github/docs/tree/main/.github/workflows.
As the team responsible for documentingevery aspect of GitHub, as well as managing open source contributions from the community, we havea lotof 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 anOctokit图书馆, or use a framework likeProbot. While Probot is awesome, Actions does a lot more heavy lifting out of the box. Within a YAML workflow file, you can use
github-scriptandthe GitHub CLIto access the full power of GitHub’s APIs, find and use prebuilt actions from theMarketplace, orwrite 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.
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 ouropen source repo.
When a contributor opens an issue, ourTriage new issuesworkflow adds a
triagelabel 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 Issuescloses 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, ourNo responseworkflow 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传输一个issue to ouropen source OpenAPI repo.Copy to REST API issue to docs-contentcopies 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 wantedlabel to it, andMove help wanted issuesputs it in a project board where it is easy for contributors to find.
When a contributor submits a pull request,Check unallowed file changesvalidates that the pull request doesn’t change certain files.
Triage new pull requestsadds a
triagelabel 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 PRsmakes sure a member of our team merges the pull request. When the pull request is merged,Merge notificationlets the contributor know when they can expect to see their changes go live ondocs.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 Checkadds 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!
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 inour workflow directoryand let us know if you have any ideas or suggestions in adiscussion! Better yet, open a pull request and our actions will tell us all about it.