Merge pull request #36787 from github/repo-sync

Repo sync

Author: docs-bot

.github/workflows/article-api-docs.yml

@@ -0,0 +1,45 @@
+name: 'Check article-api docs'
+
+# **What it does**: Makes sure changes to the article api are documented.
+# **Why we have it**: So what's documented doesn't fall behind
+# **Who does it impact**: Docs engineering, CGS team
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'src/article-api/middleware/article.ts'
+      - 'src/article-api/middleware/pagelist.ts'
+      # Self-test
+      - .github/workflows/article-api-docs.yml
+
+permissions:
+  contents: read
+
+jobs:
+  check-content-linter-rules-docs:
+    runs-on: ${{ fromJSON('["ubuntu-latest", "ubuntu-20.04-xl"]')[github.repository == 'github/docs-internal'] }}
+    if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - uses: ./.github/actions/node-npm-setup
+
+      - name: Check that src/article-api/README.md is up-to-date
+        run: npm run generate-article-api-docs
+
+      - name: Fail if it isn't up-to-date
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git status
+            git diff
+
+            # Some whitespace for the sake of the message below
+            echo ""
+            echo ""
+
+            echo "src/article-api/README.md is out of date."
+            echo "Please run 'npm run generate-article-api-docs' and commit the changes."
+            exit 1;
+          fi

.github/workflows/first-responder-v2-prs-collect.yml

@@ -71,9 +71,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          ISSUE_NUMS=$(echo "${{ github.event.pull_request.body }}" | grep -oE '#[0-9]+' | tr -d '#')
+          ISSUE_NUMS=$(echo "${{ github.event.pull_request.body }}" | grep -oE '(https://github.com/github/docs-content/issues/[0-9]+|#[0-9]+)' | grep -oE '[0-9]+')
           for ISSUE_NUM in $ISSUE_NUMS; do
-            LABELS=$(gh issue view $ISSUE_NUM --json labels --jq '.labels[].name')
+            LABELS=$(gh issue view $ISSUE_NUM --repo github/docs-content --json labels --jq '.labels[].name')
             if echo "$LABELS" | grep -q 'DIY docs'; then
               echo "DIY_DOCS_LABEL=true" >> $GITHUB_ENV
               break

content/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes.md

@@ -71,7 +71,7 @@ When SCIM is enabled, you will no longer be able to delete, suspend, or promote
 
 If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing users during SCIM provisioning.
 
-* When SCIM is enabled, users with SAML-linked identities will **not be able to sign in** until their identities have been provisioned by SCIM.
+* When SCIM is enabled, users with SAML-linked identities will **not be able to sign in** until their identities have been provisioned by SCIM.{% ifversion scim-for-ghes-ga %} You will no longer be able to update the SAML `NameID` of existing users in the site admin dashboard.{% endif %}
 * When your instance receives a SCIM request, SCIM identities are matched to existing users by **comparing the `userName` SCIM field with the {% data variables.product.prodname_dotcom %} username**. If a user with a matching username doesn't exist, {% data variables.product.prodname_dotcom %} creates a new user.
 * If {% data variables.product.prodname_dotcom %} successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance **overwrites the details** with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account.
 

content/admin/managing-iam/using-saml-for-enterprise-iam/updating-a-users-saml-nameid.md

@@ -21,6 +21,10 @@ In some situations, you may need to update values associated with a person's acc
 
 To update user SAML `NameID` mappings in bulk, you can use the `ghe-saml-mapping-csv` command. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-saml-mapping-csv).
 
+{% ifversion scim-for-ghes-ga %}
+When SCIM is enabled on your {% data variables.product.prodname_ghe_server %} instance, you cannot update user SAML `NameID` mappings.
+{% endif %}
+
 ## Updating a user's SAML `NameID`
 
 Enterprise owners can update a user's SAML `NameID` on a {% data variables.product.github %} instance.

content/codespaces/developing-in-a-codespace/opening-an-existing-codespace.md

@@ -62,8 +62,6 @@ You can bookmark the address of this page if you want to get back to it quickly
    1. Click **Open in**.
    1. Click **Open in APPLICATION**.
 
-   ![Screenshot of the "Open in" dialog, with "Open in {% data variables.product.prodname_vscode %}" highlighted.](/assets/images/help/codespaces/open-codespace-in-another-editor.png)
-
    You can open the codespace in:
    * Your browser
    * {% data variables.product.prodname_vscode %}

content/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces.md

@@ -29,8 +29,6 @@ If you want to use {% data variables.product.prodname_vscode %} as your default
 {% data reusables.user-settings.codespaces-tab %}
 1. Under "Editor preference", select the option you want.
 
-   ![Screenshot of the "Editor preference" options, with "{% data variables.product.prodname_vscode %} for Web" selected.](/assets/images/help/codespaces/select-default-editor.png)
-
    * {% data reusables.codespaces.application-installed-locally %}<br><br>
 
    * If you choose **{% data variables.product.prodname_vscode %}**, {% data variables.product.prodname_github_codespaces %} will automatically open in the desktop application when you next create or open a codespace.

content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md

@@ -25,12 +25,11 @@ When you add an issue type to an issue, the type will be shown on any lists of i
 1. Under "Type name", type the name of your new issue type.
 1. Under "Description", to help other people understand the purpose of your new issue type, type a description.
 1. Under "Color", click on the color you would like for the new issue type.
-1. Optionally, to stop the new issue type being available in public repositories, select **Private repositories only**.
 1. Click **Create**.
 
 ## Making changes to issue types
 
-You can change the name, description, color, and public repository visibility of your issue types.
+You can change the name, description, and color of your issue types.
 
 You can also choose to disable or delete an issue type. If you disable an issue type, it will not be shown and it won't be possible to set an issue to that type, but if you later decide to enable the issue type, it will be displayed again on any issues previously set to the issue type. If you delete an issue type, it is permanently removed.
 
@@ -40,5 +39,5 @@ You can also choose to disable or delete an issue type. If you disable an issue
    ![Screenshot of the issue types settings page for an organization. The "open type options" button is highlighted with an orange rectangle.](/assets/images/help/issues/issue-type-edit.png)
 
 1. In the menu, click **Edit** and make your changes.
-    * To make changes to the type name, description, color, and if the issue type should only appear for private repositories. Then click **Save**.
+    * To make changes to the type name, description, or color, click **Save**.
     * To disable or delete the issue type, in the "Danger zone", click **Disable** or **Delete** and follow the prompts.

data/features/scim-for-ghes-ga.yml

@@ -0,0 +1,5 @@
+# 16433
+# SCIM for GitHub Enterprise Server, GA
+
+versions:
+  ghes: '>=3.17'

data/reusables/codespaces/application-installed-locally.md

@@ -1 +1 @@
-If you choose **{% data variables.product.prodname_vscode %}**, you must make sure you have installed the selected application on your local machine.
+If you choose **{% data variables.product.prodname_vscode %}**, you must make sure you have {% data variables.product.prodname_vscode_shortname %} installed on your local machine.

package.json

@@ -57,6 +57,7 @@
     "lint-content": "tsx src/content-linter/scripts/lint-content.js",
     "lint-translation": "vitest src/content-linter/tests/lint-files.js",
     "liquid-markdown-tables": "tsx src/tools/scripts/liquid-markdown-tables/index.ts",
+    "generate-article-api-docs": "tsx src/article-api/scripts/generate-api-docs.ts",
     "generate-code-scanning-query-list": "tsx src/code-scanning/scripts/generate-code-scanning-query-list.ts",
     "generate-content-linter-docs": "tsx src/content-linter/scripts/generate-docs.ts",
     "move-content": "tsx src/content-render/scripts/move-content.js",

src/article-api/README.md

@@ -22,3 +22,128 @@ The `/api/article` endpoints return information about a page by `pathname`.
 For internal folks ask in the Docs Engineering slack channel. 
 
 For open source folks, please open a discussion in the public repository.
+
+<!-- API reference docs automatically generated, do not edit below this comment -->
+## Reference: API endpoints
+
+### GET /api/article/
+
+Get article metadata and content in a single object. Equivalent to calling `/article/meta` concatenated with `/article/body`.
+
+**Parameters**:
+- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
+
+**Returns**: (object) - JSON object with article metadata and content (`meta` and `body` keys)
+
+**Throws**:
+- (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
+- (Error): 400 - If pathname parameter is invalid.
+- (Error): 404 - If the path is valid, but the page couldn't be resolved.
+
+**Example**:
+```
+❯ curl -s "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"
+{
+  "meta": {
+    "title": "About GitHub and Git",
+    "intro": "You can use GitHub and Git to collaborate on work.",
+    "product": "Get started"
+  },
+  "body": "## About GitHub\n\nGitHub is a cloud-based platform where you can store, share, and work together with others to write code.\n\nStoring your code in a \"repository\" on GitHub allows you to:\n\n* **Showcase or share** your work.\n [...]"
+}
+```
+
+---
+
+### GET /api/article/body
+
+Get the contents of an article's body.
+
+**Parameters**:
+- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
+
+**Returns**: (string) - Article body content in markdown format.
+
+**Throws**:
+- (Error): 403 - If the article body cannot be retrieved. Reason is given in the error message.
+- (Error): 400 - If pathname parameter is invalid.
+- (Error): 404 - If the path is valid, but the page couldn't be resolved.
+
+**Example**:
+```
+❯ curl -s https://docs.github.com/api/article/body\?pathname=/en/get-started/start-your-journey/about-github-and-git
+## About GitHub
+
+GitHub is a cloud-based platform where you can store, share, and work together with others to write code.
+
+Storing your code in a "repository" on GitHub allows you to:
+[...]
+```
+
+---
+
+### GET /api/article/meta
+
+Get metadata about an article.
+
+**Parameters**:
+- **pathname** (string) - Article path (e.g. '/en/get-started/article-name')
+
+**Returns**: (object) - JSON object containing article metadata with title, intro, and product information.
+
+**Throws**:
+- (Error): 400 - If pathname parameter is invalid.
+- (Error): 404 - If the path is valid, but the page couldn't be resolved.
+
+**Example**:
+```
+❯ curl -s "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git"
+{
+  "title": "About GitHub and Git",
+  "intro": "You can use GitHub and Git to collaborate on work.",
+  "product": "Get started",
+  "breadcrumbs": [
+    {
+      "href": "/en/get-started",
+      "title": "Get started"
+    },
+    {
+      "href": "/en/get-started/start-your-journey",
+      "title": "Start your journey"
+    },
+    {
+      "href": "/en/get-started/start-your-journey/about-github-and-git",
+      "title": "About GitHub and Git"
+    }
+  ]
+}
+```
+
+---
+
+### GET /api/pagelist/:lang/:productVersion
+
+A list of pages available for a fully qualified path containing the target language and product version.
+
+**Parameters**:
+- **lang** (string) - Path parameter for language code (e.g. 'en')
+- **productVersion** (string) - Path parameter for product version (e.g. 'free-pro-team@latest')
+
+**Returns**: (string) - List of paths matching the language and version
+
+**Throws**:
+- (Error): 400 - If language or version parameters are invalid. Reason is given in the error message.
+
+**Example**:
+```
+❯ curl -s https://docs.github.com/api/pagelist/en/free-pro-team@latest
+/en
+/en/search
+/en/get-started
+/en/get-started/start-your-journey
+/en/get-started/start-your-journey/about-github-and-git
+[...]
+```
+
+---
+

src/article-api/middleware/article.ts

@@ -20,6 +20,25 @@ const router = express.Router()
 // - pathValidationMiddleware ensures the path is properly structured and handles errors when it's not
 // - pageValidationMiddleware fetches the page from the pagelist, returns 404 to the user if not found
 
+/**
+ * Get article metadata and content in a single object. Equivalent to calling `/article/meta` concatenated with `/article/body`.
+ * @route GET /api/article
+ * @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
+ * @returns {object} JSON object with article metadata and content (`meta` and `body` keys)
+ * @throws {Error} 403 - If the article body cannot be retrieved. Reason is given in the error message.
+ * @throws {Error} 400 - If pathname parameter is invalid.
+ * @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
+ * @example
+ * ❯ curl -s "https://docs.github.com/api/article?pathname=/en/get-started/start-your-journey/about-github-and-git"
+ * {
+ *   "meta": {
+ *     "title": "About GitHub and Git",
+ *     "intro": "You can use GitHub and Git to collaborate on work.",
+ *     "product": "Get started"
+ *   },
+ *   "body": "## About GitHub\n\nGitHub is a cloud-based platform where you can store, share, and work together with others to write code.\n\nStoring your code in a \"repository\" on GitHub allows you to:\n\n* **Showcase or share** your work.\n [...]"
+ * }
+ */
 router.get(
   '/',
   pathValidationMiddleware as RequestHandler,
@@ -43,6 +62,23 @@ router.get(
   }),
 )
 
+/**
+ * Get the contents of an article's body.
+ * @route GET /api/article/body
+ * @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
+ * @returns {string} Article body content in markdown format.
+ * @throws {Error} 403 - If the article body cannot be retrieved. Reason is given in the error message.
+ * @throws {Error} 400 - If pathname parameter is invalid.
+ * @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
+ * @example
+ * ❯ curl -s https://docs.github.com/api/article/body\?pathname=/en/get-started/start-your-journey/about-github-and-git
+ * ## About GitHub
+ *
+ * GitHub is a cloud-based platform where you can store, share, and work together with others to write code.
+ *
+ * Storing your code in a "repository" on GitHub allows you to:
+ * [...]
+ */
 router.get(
   '/body',
   pathValidationMiddleware as RequestHandler,
@@ -62,6 +98,35 @@ router.get(
   }),
 )
 
+/**
+ * Get metadata about an article.
+ * @route GET /api/article/meta
+ * @param {string} pathname - Article path (e.g. '/en/get-started/article-name')
+ * @returns {object} JSON object containing article metadata with title, intro, and product information.
+ * @throws {Error} 400 - If pathname parameter is invalid.
+ * @throws {Error} 404 - If the path is valid, but the page couldn't be resolved.
+ * @example
+ * ❯ curl -s "https://docs.github.com/api/article/meta?pathname=/en/get-started/start-your-journey/about-github-and-git"
+ * {
+ *   "title": "About GitHub and Git",
+ *   "intro": "You can use GitHub and Git to collaborate on work.",
+ *   "product": "Get started",
+ *   "breadcrumbs": [
+ *     {
+ *       "href": "/en/get-started",
+ *       "title": "Get started"
+ *     },
+ *     {
+ *       "href": "/en/get-started/start-your-journey",
+ *       "title": "Start your journey"
+ *     },
+ *     {
+ *       "href": "/en/get-started/start-your-journey/about-github-and-git",
+ *       "title": "About GitHub and Git"
+ *     }
+ *   ]
+ * }
+ */
 router.get(
   '/meta',
   pathValidationMiddleware as RequestHandler,

src/article-api/middleware/pagelist.ts

@@ -44,7 +44,22 @@ router.get(
   }),
 )
 
-// for a fully qualified path with language and product version, we'll serve up the pagelist
+/**
+ * A list of pages available for a fully qualified path containing the target language and product version.
+ * @route GET /api/pagelist
+ * @param {string} lang - Path parameter for language code (e.g. 'en')
+ * @param {string} productVersion - Path parameter for product version (e.g. 'free-pro-team@latest')
+ * @returns {string} List of paths matching the language and version
+ * @throws {Error} 400 - If language or version parameters are invalid. Reason is given in the error message.
+ * @example
+ * ❯ curl -s https://docs.github.com/api/pagelist/en/free-pro-team@latest
+ * /en
+ * /en/search
+ * /en/get-started
+ * /en/get-started/start-your-journey
+ * /en/get-started/start-your-journey/about-github-and-git
+ * [...]
+ */
 router.get(
   '/:lang/:productVersion',
   pagelistValidationMiddleware as RequestHandler,