Add descriptions to our actions workflows (github#18019)

Co-authored-by: Sarah Edwards <[email protected]>

.github/workflows/60-days-stale-check.yml

@@ -1,4 +1,9 @@
 name: 60 Days Stale Check
+
+# **What it does**: Pull requests older than 60 days will be flagged as stale.
+# **Why we have it**: We want to manage our queue of issues and pull requests.
+# **Who does it impact**: Everyone that works on docs or docs-internal.
+
 on:
   schedule:
     - cron: '40 16 * * *' # Run each day at 16:40 UTC / 8:40 PST

.github/workflows/auto-label-prs.yml

@@ -1,5 +1,9 @@
 name: Auto label Pull Requests
 
+# **What it does**: Automatically adds the engineering label when specific files change.
+# **Why we have it**: Other automation applies specifically to engineering label issues and pull requests.
+# **Who does it impact**: Automation that relies on the engineering label.
+
 on:
   pull_request:
 

.github/workflows/automerge-dependencies.yml

@@ -1,5 +1,9 @@
 name: Auto Merge Dependency Updates
 
+# **What it does**: Automatically merge pull requests from dependabot.
+# **Why we have it**: To keep our dependencies up-to-date, to avoid security issues.
+# **Who does it impact**: It helps docs engineering focus on higher value work.
+
 on:
   pull_request:
     paths:

.github/workflows/automerge.yml

@@ -1,4 +1,9 @@
 name: automerge
+
+# **What it does**: Pull requests with label "automerge" or "autosquash" will automatically merge.
+# **Why we have it**: While now this is a feature built into GitHub, we still use it as part of other automation.
+# **Who does it impact**: Any workflows that depend on automerge or autosquash labels.
+
 on:
   pull_request:
     types:

.github/workflows/autoupdate-branch.yml

@@ -1,5 +1,9 @@
 name: autoupdate branch
 
+# **What it does**: Any pull requests with "autoupdate" label will get main branch updates.
+# **Why we have it**: Our repo-sync automation relies on it.
+# **Who does it impact**: Our ability to support the open-source repository.
+
 #
 # This workflow checks all open PRs targeting `main` as their base branch and
 # will attempt to update them if they have the `autoupdate` label applied.

.github/workflows/browser-test.yml

@@ -1,5 +1,9 @@
 name: Browser Tests
 
+# **What it does**: This runs our browser tests on pull requests.
+# **Why we have it**: This is the only way we currently test our browser JavaScript.
+# **Who does it impact**: Docs engineering, open-source engineering contributors.
+
 on:
   workflow_dispatch:
   push:

.github/workflows/build-docker-image.yml

@@ -1,7 +1,9 @@
-# Make sure the Docker container still builds
-
 name: Build Docker image
 
+# **What it does**: This builds our Docker container.
+# **Why we have it**: We don't use the Docker container internally, but other teams depend on our Docker container.
+# **Who does it impact**: Enterprise customers.
+
 on:
   push:
     branches:

.github/workflows/check-all-english-links.yml

@@ -1,5 +1,9 @@
 name: Check all English links
 
+# **What it does**: This script once a day checks all English links and reports in issues.
+# **Why we have it**: We want to know if any links break.
+# **Who does it impact**: Docs content.
+
 on:
   workflow_dispatch:
   schedule:

.github/workflows/check-for-spammy-issues.yml

@@ -1,4 +1,9 @@
 name: Check for Spammy Issues
+
+# **What it does**: This action closes low value pull requests in the open-source repository.
+# **Why we have it**: We get lots of spam in the open-source repository.
+# **Who does it impact**: Open-source contributors.
+
 on:
   issues:
     types: [opened]
@@ -32,7 +37,7 @@ jobs:
               return
             } catch(err) {
               // An error will be thrown if the user is not a GitHub employee
-              // If a user is not a GitHub employee, we should check to see if title has at least the minimum required number of words in it and if it does, we can exit the workflow 
+              // If a user is not a GitHub employee, we should check to see if title has at least the minimum required number of words in it and if it does, we can exit the workflow
 
               if(titleWordCount > titleWordCountMin) {
                 return
@@ -42,7 +47,7 @@ jobs:
             //
             // Assuming the user is not a GitHub employee and the issue title
             // has the minimum number of words required, proceed.
-            // 
+            //
 
             // Close the issue and add the invalid label
             await github.issues.update({

.github/workflows/close-external-repo-sync-prs.yml

@@ -1,5 +1,9 @@
 name: Check for External Repo Sync PR
 
+# **What it does**: If someone made a repo sync pull request other than Octomerger, close it.
+# **Why we have it**: Another form of spam in the open-source repository.
+# **Who does it impact**: Open-source contributors.
+
 on:
   pull_request:
     types:

.github/workflows/codeql.yml

@@ -1,5 +1,9 @@
 name: CodeQL analysis
 
+# **What it does**: This runs CodeQL on our repository.
+# **Why we have it**: Security scanning.
+# **Who does it impact**: Docs engineering.
+
 on:
   push:
     branches:

.github/workflows/confirm-internal-staff-work-in-docs.yml

@@ -1,5 +1,9 @@
 name: Confirm internal staff meant to post in public
 
+# **What it does**: If a GitHub staff makes an issue/pull request in the open-source repo, creates an issue in the internal one to verify intent.
+# **Why we have it**: We don't want GitHub staff accidentally making issues/pull requests in the wrong repository.
+# **Who does it impact**: GitHub staff.
+
 on:
   issues:
     types:

.github/workflows/crowdin.yml

@@ -1,5 +1,9 @@
 name: Crowdin Sync
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**: Docs localization.
+
 on:
   workflow_dispatch:
   schedule:

.github/workflows/dry-run-sync-algolia-search-indices.yml

@@ -1,5 +1,9 @@
 name: (Dry run) Algolia
 
+# **What it does**: On request, dry run Algolia to check for issues with search indexing.
+# **Why we have it**: It helps us debug issues with search indexing.
+# **Who does it impact**: Docs engineering.
+
 on:
   workflow_dispatch:
 

.github/workflows/first-responder-docs-content.yml

@@ -1,4 +1,9 @@
 name: First responder docs-content
+
+# **What it does**: New pull requests automatically add to the content first responder board.
+# **Why we have it**: So we don't lose track of new pull reuqests for docs-content to review.
+# **Who does it impact**: Docs content.
+
 on:
   pull_request:
     types:

.github/workflows/js-lint.yml

@@ -1,5 +1,9 @@
 name: Lint JS
 
+# **What it does**: Lints our JavaScript to ensure the code matches the specified code style.
+# **Why we have it**: We want some level of consistency to our JavaScript.
+# **Who does it impact**: Docs engineering, open-source engineering contributors.
+
 on:
   workflow_dispatch:
   push:

.github/workflows/link-check-dotcom.yml

@@ -1,5 +1,9 @@
 name: 'Link Checker: Dotcom'
 
+# **What it does**: This checks links for dotcom version of docs.
+# **Why we have it**: We want to know if links break.
+# **Who does it impact**: Docs content.
+
 on:
   workflow_dispatch:
   push:

.github/workflows/link-check-ghae.yml

@@ -1,5 +1,9 @@
 name: 'Link Checker: GitHub AE'
 
+# **What it does**: This checks links for GHAE version of docs.
+# **Why we have it**: We want to know if links break.
+# **Who does it impact**: Docs content.
+
 on:
   workflow_dispatch:
   push:

.github/workflows/link-check-ghes.yml

@@ -1,5 +1,9 @@
 name: 'Link Checker: Enterprise Server'
 
+# **What it does**: This checks links for GHES version of docs.
+# **Why we have it**: We want to know if links break.
+# **Who does it impact**: Docs content.
+
 on:
   workflow_dispatch:
   push:

.github/workflows/merged-notification.yml

@@ -1,4 +1,9 @@
 name: Merged notification
+
+# **What it does**: When we merge an open-source pull request, we want to set expectations that deployment may take awhile.
+# **Why we have it**: We deploy to production from docs-internal, not docs.
+# **Who does it impact**: Open-source contributors.
+
 on:
   pull_request_target:
     types:

.github/workflows/move-help-wanted-issues.yml

@@ -1,4 +1,9 @@
 name: Move help wanted issues
+
+# **What it does**: In the open source repo, when the "help wanted" or "good first issue" labels are added to an issue, the issue is added to the "Help wanted" column on the project board.
+# **Why we have it**: To keep track of help wanted issues.
+# **Who does it impact**: Open-source contributors.
+
 on:
   issues:
     types:

.github/workflows/move-ready-to-merge-issues.yaml

@@ -1,6 +1,6 @@
 name: Move and unlabel ready to merge issues
 
-# **What it does**: This moves ready to merge PRs on the project board for the open source repo. When a PR in the open source repo is labeled "ready to merge," the "waiting for review" label is removed and the PR is moved to the "Triage" column.
+# **What it does**: This moves ready to merge issues on the project board for the open source repo. When an issue in the open source repo is labeled "ready to merge," the "waiting for review" label is removed and the issue is moved to the "Triage" column.
 # **Why we have it**:  To help with managing our project boards.
 # **Who does it impact**: Open source contributors, open-source maintainers.
 

.github/workflows/openapi-decorate.yml

@@ -1,5 +1,9 @@
 name: OpenAPI generate decorated schema files
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**:
+
 on:
   workflow_dispatch:
   pull_request:

.github/workflows/openapi-schema-check.yml

@@ -1,5 +1,9 @@
 name: OpenAPI dev mode check
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**:
+
 on:
   workflow_dispatch:
   push:

.github/workflows/pa11y.yml

@@ -1,4 +1,9 @@
 name: Pa11y
+
+# **What it does**: Runs a static accessibility check on high traffic docs pages.
+# **Why we have it**: We want accessibility support for the docs.
+# **Who does it impact**: Docs engineering, users who need accessibility features.
+
 on:
   workflow_dispatch:
   schedule:

.github/workflows/ping-staging-apps.yml

@@ -1,5 +1,9 @@
 name: Ping staging apps
 
+# **What it does**: This keeps our staging applications from automatically spinning down.
+# **Why we have it**: Staging applications can hiberate without use.
+# **Who does it impact**: Anyone with a pull request in docs-internal.
+
 on:
   schedule:
     - cron: '*/20 * * * *' # every twenty minutes

.github/workflows/post-status-updates-to-slack.yml

@@ -1,4 +1,9 @@
 name: Epic Status Update
+
+# **What it does**: For our epic issue status comments, also ping us in Slack.
+# **Why we have it**: So that we can write one status update and have it show up in two places.
+# **Who does it impact**: GitHub docs staff.
+
 on:
   issue_comment:
     types: [created]

.github/workflows/remove-from-fr-board.yaml

@@ -1,5 +1,9 @@
 name: Remove card from FR board
 
+# **What it does**: Removes the triggering issue or PR from the docs-content first responder board. This workflow is expected to trigger from a slash command.
+# **Why we have it**: To help with first responder duties
+# **Who does it impact**: Docs-content team first responders
+
 on:
   repository_dispatch:
     types: remove_from_docs_FR_board

.github/workflows/remove-unused-assets.yml

@@ -1,5 +1,9 @@
 name: Remove unused assets
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**:
+
 on:
   schedule:
     - cron: '20 15 * * 0' # run every Sunday at 20:15 UTC / 12:15 PST

.github/workflows/repo-freeze-check.yml

@@ -1,5 +1,9 @@
 name: Repo Freeze Check
 
+# **What it does**: Prevent pull requests from merging during freezes.
+# **Why we have it**: Sometimes we need to freeze deployments for various reasons.
+# **Who does it impact**: Anyone working on docs.
+
 on:
   workflow_dispatch:
   pull_request_target:

.github/workflows/repo-freeze-reminders.yml

@@ -1,5 +1,9 @@
 name: Repo Freeze Reminders
 
+# **What it does**: This reminds us that the repository is frozen for deploys.
+# **Why we have it**: To remind us to turn off the freeze after the freeze period is over.
+# **Who does it impact**: Docs engineering.
+
 on:
   schedule:
     - cron: '00 11 * * *' # once per day around 11:00am UTC

.github/workflows/repo-sync-stalls.yml

@@ -1,5 +1,9 @@
 name: Repo Sync Stalls
 
+# **What it does**: This lets us know in Slack if repo-sync doesn't happen in a timely manner.
+# **Why we have it**: We want repo-sync to keep the two repositories in sync with each other.
+# **Who does it impact**: Open-source contributors, docs engineering.
+
 on:
   workflow_dispatch:
   schedule:
@@ -30,7 +34,7 @@ jobs:
               return
             }
 
-            // Remove all pull requests that don't have the 
+            // Remove all pull requests that don't have the
             // 'automated-reposync-pr' label
             pulls.data = pulls.data.filter(pr =>
               pr.labels.some(label => label.name === 'automated-reposync-pr')
@@ -42,7 +46,7 @@ jobs:
               const minutesOpen = timeDelta / 1000 / 60;
 
               if (minutesOpen > 180) {
-                core.setFailed('Repo sync appears to be stalled') 
+                core.setFailed('Repo sync appears to be stalled')
               }
             })
       - name: Send Slack notification if workflow fails

.github/workflows/repo-sync.yml

@@ -6,6 +6,10 @@
 
 name: Repo Sync
 
+# **What it does**: Syncs docs and docs-internal.
+# **Why we have it**: To keep the open-source repository up-to-date, while still having an internal repository for sensitive work.
+# **Who does it impact**: Open-source.
+
 on:
   workflow_dispatch:
   schedule:

.github/workflows/send-issues-to-how-how-we-work-boards.yml

@@ -1,5 +1,9 @@
 name: Send Issue to How We Work Boards
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**:
+
 on:
   issues:
     types:

.github/workflows/site-policy-sync.yml

@@ -1,5 +1,9 @@
 name: site-policy-sync
 
+# **What it does**: Updates our site policy docs when changes happen to site policy.
+# **Why we have it**: We want up to date site policy docs.
+# **Who does it impact**: Site policy team.
+
 # Controls when the action will run.
 on:
   # Triggers the workflow pull requests merged to the main branch

.github/workflows/start-new-engineering-pr-workflow.yml

@@ -1,5 +1,9 @@
 name: Start new engineering PR workflow
 
+# **What it does**:
+# **Why we have it**:
+# **Who does it impact**:
+
 on:
   pull_request_target:
     types: