update pipeline readmes (#50561)

rachmari · github-actions · web-flow · commit aaaf433e7ac4 · 2024-05-13T17:39:48.000Z
Co-authored-by: github-actions &lt;github-actions@github.com&gt;
diff --git a/src/github-apps/README.md b/src/github-apps/README.md
@@ -2,20 +2,32 @@
 
 Our GitHub Apps pipeline creates autogenerated documentation for docs.github.com from the OpenAPI stored in the open-source repository [`github/rest-api-description`](https://github.com/github/rest-api-description).
 
-The pipeline is used to generate data that is used by the docs.github.com site when deployed locally, in preview environments, or in production.
+The pipeline is used to generate the data used on these pages:
+- [Endpoints available for Github App installation access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-github-app-installation-access-tokens)
+- [Endpoints available for GitHub App user access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-github-app-user-access-tokens)
+- [Endpoints available for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens)
+- [Permissions required for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps)
+- [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)
 
 ## How does it work
 
 ![A flow chart describing how the automation pipeline for GitHub Apps generates documentation](./github-apps-pipeline-flowchart.png)
 
 A [workflow](.github/workflows/sync-openapi.yml) is used to trigger the automation of the GitHub Apps documentation. The workflow runs automatically on a schedule. The workflow that triggers the GitHub Apps pipeline also triggers other automation pipelines that use the OpenAPI as the source data:
+
 - GitHub Apps
 - REST
 - Webhooks
 
 The workflow automatically creates a pull request with the changes (for all three pipelines) and the label `github-openapi-bot`.
 
-The workflow runs the `src/rest/scripts/update-files.js` script.
+The data used by the GitHub Apps pages is generated from two sources of programmatic access data and the OpenAPI. Changes to the programmatic access files do not trigger this pipeline to run, but this pipeline can be manually triggered at any time.
+
+## Manually running the pipeline
+
+You can manually sync the data used by the REST, Webhooks, and GitHub App pipelines before the scheduled daily run [here](https://github.com/github/docs-internal/actions/workflows/sync-openapi.yml). Use the default input options.
+
+If the OpenAPI has changed, you will need to first wait for the OpenAPI to be merged into `github/rest-api-description`.
 
 ## Local development
 
@@ -26,11 +38,12 @@ To run the GitHub Apps pipeline locally:
 
 ## About this directory
 
-- `src/rest/data` - The automatically generated data files created by running this pipeline.
-- `src/rest/lib` - The source code used in production for the automated documentation generated by the GitHub Apps pipeline and configuration files edited by content and engineering team members.
-  - `src/rest/lib/config.json` - A configuration file used to specify metadata about the GitHub Apps pipeline. This file contains the SHA of the commit in `github/rest-api-description` that was used to generate the data in `src/github-apps/data`. This value is automatically updated when the pipeline runs.
-- `src/rest/scripts` - The scripts and source code used run the GitHub Apps pipeline, which updates the `src/github-apps/data` directory. 
-- `src/rest/tests` - The tests used to verify the GitHub Apps pipeline.
+- `src/github-apps/components` - The React source code.
+- `src/github-apps/data` - The automatically generated data files created by running this pipeline.
+- `src/github-apps/lib` - The source code used in production for the automated documentation generated by the GitHub Apps pipeline and configuration files edited by content and engineering team members.
+  - `src/github-apps/lib/config.json` - A configuration file used to specify metadata about the GitHub Apps pipeline. This file contains the SHA of the commit in `github/rest-api-description` that was used to generate the data in `src/github-apps/data`. This value is automatically updated when the pipeline runs.
+- `src/github-apps/scripts` - The scripts and source code used to run the GitHub Apps pipeline, which updates the `src/github-apps/data` directory.
+- `src/github-apps/tests` - The tests used to verify the GitHub Apps pipeline.
 
 ## Configuring the pipeline
 
diff --git a/src/github-apps/github-apps-pipeline-flowchart.png b/src/github-apps/github-apps-pipeline-flowchart.png
diff --git a/src/github-apps/scripts/sync.js b/src/github-apps/scripts/sync.js
@@ -163,7 +163,6 @@ export async function getProgAccessData(progAccessSource) {
   }
 
   let progAccessDataRaw
-  // config/locales/programmatic_actor_fine_grained_resources.en.yml
   let progActorResources
   const progAccessFilepath = 'config/access_control/programmatic_access.yaml'
   const progActorFilepath = 'config/locales/programmatic_actor_fine_grained_resources.en.yml'
diff --git a/src/rest/README.md b/src/rest/README.md
@@ -9,6 +9,7 @@ The pipeline is used to generate data that is used by the docs.github.com site w
 ![A flow chart describing how the automation pipeline for REST generates documentation](./rest-pipeline-flowchart.png)
 
 A [workflow](.github/workflows/sync-openapi.yml) is used to trigger the automation of the REST documentation. The workflow runs automatically on a schedule. The workflow that triggers the REST pipeline also triggers other automation pipelines that use the OpenAPI as the source data:
+
 - GitHub Apps
 - REST
 - Webhooks
@@ -23,6 +24,12 @@ You can manually run the workflow leaving the source branch input parameter with
 
 If there is a pull request that is still unmerged in `github/rest-api-description` that needs to be propagated to the docs.github.com site, manually run the workflow and provide the branch name of the pull request in the `github/rest-api-description` repo that you would like to get the changes from. This will create a new pull request in the `github/docs-internal` repo with the changes.
 
+## Manually running the pipeline
+
+You will need to first wait for the OpenAPI to be merged into `github/rest-api-description`.
+
+Then, you can manually sync the data used by the REST, Webhooks, and GitHub App pipelines before the scheduled daily run [here](https://github.com/github/docs-internal/actions/workflows/sync-openapi.yml). Use the default input options.
+
 ## Local development
 
 To run the REST pipeline locally:
@@ -32,7 +39,8 @@ To run the REST pipeline locally:
 
 ## About this directory
 
-- `src/rest/api` - The source code for the api endpoint used in production that redirects specific anchor links on a page under `docs.github.com/rest`.
+- `src/github-apps/api` - API endpoints used by source code in `src/rest`.
+- `src/github-apps/components` - The React source code.
 - `src/rest/data` - The automatically generated data files created by running this pipeline.
 - `src/rest/lib` - The source code used in production for the automated documentation generated by the REST pipeline and configuration files edited by content and engineering team members.
   - `src/rest/lib/config.json` - A configuration file used to specify metadata about the REST pipeline.
diff --git a/src/webhooks/README.md b/src/webhooks/README.md
@@ -9,6 +9,7 @@ The pipeline is used to generate data that is used by the docs.github.com site w
 ![A flow chart describing how the automation pipeline for webhooks generates documentation](./webhooks-pipeline-flowchart.png)
 
 A [workflow](.github/workflows/sync-openapi.yml) is used to trigger the automation of the webhooks documentation. The workflow runs automatically on a schedule. The workflow that triggers the webhooks pipeline also triggers other automation pipelines that use the OpenAPI as the source data:
+
 - GitHub Apps
 - REST
 - Webhooks
@@ -17,6 +18,12 @@ The workflow automatically creates a pull request with the changes (for all thre
 
 The workflow runs the `src/rest/scripts/update-files.js` script, which then calls the `src/webhooks/scripts/sync.js` script.
 
+## Manually running the pipeline
+
+You will need to first wait for the OpenAPI to be merged into `github/rest-api-description`.
+
+Then, you can manually sync the data used by the REST, Webhooks, and GitHub App pipelines before the scheduled daily run [here](https://github.com/github/docs-internal/actions/workflows/sync-openapi.yml). Use the default input options.
+
 ## Local development
 
 To run the webhooks pipeline locally:

Original file line number	Diff line number	Diff line change
`@@ -163,7 +163,6 @@ export async function getProgAccessData(progAccessSource) {`
`163`	`163`	`}`
`164`	`164`
`165`	`165`	`let progAccessDataRaw`
`166`		`- // config/locales/programmatic_actor_fine_grained_resources.en.yml`
`167`	`166`	`let progActorResources`
`168`	`167`	`const progAccessFilepath = 'config/access_control/programmatic_access.yaml'`
`169`	`168`	`const progActorFilepath = 'config/locales/programmatic_actor_fine_grained_resources.en.yml'`