Skip to content

Repo sync #36787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 12, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .github/workflows/article-api-docs.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions .github/workflows/first-responder-v2-prs-collect.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
5 changes: 5 additions & 0 deletions data/features/scim-for-ghes-ga.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# 16433
# SCIM for GitHub Enterprise Server, GA

versions:
ghes: '>=3.17'
2 changes: 1 addition & 1 deletion data/reusables/codespaces/application-installed-locally.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
125 changes: 125 additions & 0 deletions src/article-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
[...]
```

---

65 changes: 65 additions & 0 deletions src/article-api/middleware/article.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down
17 changes: 16 additions & 1 deletion src/article-api/middleware/pagelist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading