Merge pull request #33398 from github/repo-sync

Repo sync
2026-01-08 12:01:53 -05:00 · 2024-06-07 10:30:26 -07:00
parent cc8d3b2a26 5212e15931
commit 0e682bbdb6
8 changed files with 126 additions and 111 deletions
--- a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md
+++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md
@@ -38,13 +38,14 @@ If your app runs in the browser, you should use the web application flow to gene

 1. Direct the user to this URL, and add any necessary query parameters from the following list of parameters: `{% data variables.product.oauth_host_code %}/login/oauth/authorize`. For example, this URL specifies the `client_id` and `state` parameters: `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=12345&state=abcdefg`.

-   Query parameter | Type | Description
-   -----|------|------------
-   `client_id` | `string` | **Required.** The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings)."
-   `redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters.
-   `state` | `string` | When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data.
-   `login` | `string` | When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app.
-   `allow_signup` | `boolean` | Whether unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
+   Query parameter | Type | Required? | Description
+   -----|------|------------|------
+   `client_id` | `string` | Required | The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings)."
+   `redirect_uri` | `string` | Strongly recommended |  The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters.
+   `state` | `string` | Strongly recommended |  When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data.
+   `login` | `string` | Optional | When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app.
+   `allow_signup` | `boolean` | Optional |  Whether unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
+{% ifversion oauth_account_picker %}   `prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. {% endif %}

 1. If the user accepts your authorization request, {% data variables.product.company_short %} will redirect the user to one of the callback URLs in your app settings, and provide a `code` query parameter you can use in the next step to create a user access token. If you specified `redirect_uri` in the previous step, that callback URL will be used. Otherwise, the first callback URL on your app's settings page will be used.

--- a/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md
+++ b/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md
@@ -57,14 +57,15 @@ The web application flow to authorize users for your app is:

 This endpoint takes the following input parameters.

-Parameter name | Type | Description
-----|------|--------------
-`client_id`|`string` | **Required**. The client ID you received from GitHub when you {% ifversion fpt or ghec %}[registered](https://github.com/settings/applications/new){% else %}registered{% endif %}.
-`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
-`login` | `string` | Suggests a specific account to use for signing in and authorizing the app.
-`scope`|`string` | A space-delimited list of [scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope.
-`state` | `string` | {% data reusables.apps.state_description %}
-`allow_signup`|`string` | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
+Query parameter | Type | Required? |Description
+-----|------|---------|-----
+`client_id`|`string` | Required | The client ID you received from GitHub when you {% ifversion fpt or ghec %}[registered](https://github.com/settings/applications/new){% else %}registered{% endif %}.
+`redirect_uri`|`string` |Strongly recommended| The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
+`login` | `string` | Optional| Suggests a specific account to use for signing in and authorizing the app.
+`scope`|`string` |Context dependent| A space-delimited list of [scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope.
+`state` | `string` |Strongly recommended| {% data reusables.apps.state_description %}
+`allow_signup`|`string` | Optional | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
+{% ifversion oauth_account_picker %}`prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. {% endif %}

 The PKCE (Proof Key for Code Exchange) parameters `code_challenge` and `code_challenge_method` are not supported at this time. CORS pre-flight requests (OPTIONS) are not supported at this time.

@@ -78,12 +79,12 @@ Exchange this `code` for an access token:

 This endpoint takes the following input parameters.

-Parameter name | Type | Description
-----|------|--------------
-`client_id` | `string` | **Required.** The client ID you received from {% data variables.product.product_name %} for your {% data variables.product.prodname_oauth_app %}.
-`client_secret` | `string` | **Required.** The client secret you received from {% data variables.product.product_name %} for your {% data variables.product.prodname_oauth_app %}.
-`code` | `string` | **Required.** The code you received as a response to Step 1.
-`redirect_uri` | `string` | The URL in your application where users are sent after authorization.
+Parameter name | Type | Required?| Description
+-----|------|---------|-----
+`client_id` | `string` | Required | The client ID you received from {% data variables.product.product_name %} for your {% data variables.product.prodname_oauth_app %}.
+`client_secret` | `string` | Required | The client secret you received from {% data variables.product.product_name %} for your {% data variables.product.prodname_oauth_app %}.
+`code` | `string` | Required | The code you received as a response to Step 1.
+`redirect_uri` | `string` | Strongly recommended | The URL in your application where users are sent after authorization. We can use this to match against the URI originally provided when the `code` was issued, to prevent attacks against your service.

 By default, the response takes the following form:

@@ -124,6 +125,8 @@ For example, in curl you can set the Authorization header like this:
 curl -H "Authorization: Bearer OAUTH-TOKEN" {% data variables.product.rest_url %}/user
 ```

+Every time you receive an access token, you should use the token to revalidate the user's identity. A user can change which account they are signed into when you send them to authorize your app, and you risk mixing user data if you do not validate the user's identity after every sign in.
+
 ## Device flow

 The device flow allows you to authorize users for a headless application, such as a CLI tool or the [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager).
--- a/data/features/oauth_account_picker.yml
+++ b/data/features/oauth_account_picker.yml
@@ -0,0 +1,6 @@
+# Reference: #14694
+# Detailing the account picker behavior during OAuth
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.15'
--- a/package-lock.json
+++ b/package-lock.json
@@ -115,6 +115,7 @@
        "@types/express": "4.17.21",
        "@types/imurmurhash": "^0.1.4",
        "@types/js-cookie": "^3.0.6",
+        "@types/js-yaml": "^4.0.9",
        "@types/lodash": "^4.17.0",
        "@types/lodash-es": "4.17.12",
        "@types/morgan": "1.9.9",
@@ -3283,6 +3284,12 @@
      "integrity": "sha512-wkw9yd1kEXOPnvEeEV1Go1MmxtBJL0RR79aOTAApecWFVu7w0NNXNqhcWgvw2YgZDYadliXkl14pa3WXw5jlCQ==",
      "dev": true
    },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "dev": true
+    },
    "node_modules/@types/json-schema": {
      "version": "7.0.15",
      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
--- a/package.json
+++ b/package.json
@@ -303,6 +303,7 @@
    "@types/express": "4.17.21",
    "@types/imurmurhash": "^0.1.4",
    "@types/js-cookie": "^3.0.6",
+    "@types/js-yaml": "^4.0.9",
    "@types/lodash": "^4.17.0",
    "@types/lodash-es": "4.17.12",
    "@types/morgan": "1.9.9",
--- a/src/links/lib/excluded-links.ts
+++ b/src/links/lib/excluded-links.ts
@@ -1,97 +1,27 @@
 /**
- * This file exports a mix of strings and of regexes. Linkinator relies
+ * Linkinator relies
 * on this in `src/links/scripts/rendered-content-link-checker-cli.js` when we encounter external
 * links that we *specifically ignore*. That means, that URLs or patterns
- * mentioned in this file might appear within our content but we don't
+ * mentioned in the corresponding YAML file might appear within our content but we don't
 * bother checking that they actually work.
 */

-/* eslint-disable prefer-regex-literals */
+import yaml from 'js-yaml'
+import fs from 'fs'

-type ExcludedLink = string | RegExp
+type ExcludedLink = {
+  startsWith: string | undefined
+  is: string | undefined
+}

-const excludedLinks: ExcludedLink[] = [
-  // Skip GitHub search links.
-  // E.g. https://github.com/search?foo=bar
-  regex('https://github.com/search?'),
-  regex('https://github.com/github/gitignore/search?'),
+const excludedLinks = yaml.load(
+  fs.readFileSync('./src/links/lib/excluded-links.yml', 'utf8'),
+) as ExcludedLink[]

-  // https://github.com/contact always redirects to support.github.com that
-  // is heavily protected by rate limiting.
-  regex('https://github.com/contact'),
-  // All support.github.com links are currently firewalled and you get a
-  // "403 Forbidden" every time.
-  regex('https://support.github.com'),
-
-  // These links require auth.
-  regex('https://github.com/settings/profile'),
-  regex('https://github.com/settings/billing'),
-  regex('https://github.com/github/docs/edit'),
-  regex('https://github.com/github/insights-releases/releases/latest'),
-  regex('https://classroom.github.com/videos'),
-
-  // Oneoff links that link checkers think are broken but are not.
-  'https://haveibeenpwned.com/',
-  'https://www.ilo.org/dyn/normlex/en/f?p=NORMLEXPUB:12100:0::NO::P12100_ILO_CODE:P029',
-  'https://www.linkedin.com/company/github',
-  'https://www.facebook.com/',
-  'https://ko-fi.com/',
-  'https://en.liberapay.com/',
-  'https://nbviewer.jupyter.org/github/bokeh/bokeh-notebooks/blob/main/tutorial/06%20-%20Linking%20and%20Interactions.ipynb',
-  'https://www.vmware.com/products/esxi-and-esx.html',
-  'https://www.ecfr.gov/cgi-bin/text-idx?SID=ad384e1f1e017076f8c0136f322f0a4c&mc=true&node=pt15.2.744&rgn=div5',
-  'https://wiki.oasis-open.org/security',
-  'https://www.ipaddressguide.com/cidr',
-  'https://crates.io/',
-  'https://opensource.org/about',
-  'https://www.openstreetmap.org/user/new',
-  'https://wiki.debian.org/chroot',
-  'https://www.adobe.com/products/coldfusion-builder.html',
-  'https://developer.android.com/studio',
-  'https://lastpass.com/',
-  'https://lastpass.com/auth/',
-  'https://zenodo.org/account/settings/github/',
-  'https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files',
-  'https://developer.apple.com/documentation/swift_packages',
-  'https://developer.android.com/studio/run/emulator-acceleration',
-  'https://support.discord.com/hc/en-us/articles/360045138571-Beginner-s-Guide-to-Discord',
-  'https://www.microsoft.com/en-us/edge',
-  'https://github.com/features/bitbucket-migrations/signup',
-  'https://www.servicenow.com/products/devops.html',
-  'https://daringfireball.net/projects/markdown/syntax',
-  'https://www.microsoft.com/en-us/security/mobile-authenticator-app',
-  'https://microsoft.com/powershell',
-  'https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_method',
-  'https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ID3QAM/github-connector',
-  'https://www.patreon.com/',
-  regex('https://packages.debian.org/'),
-  'https://oidref.com/1.3.6.1.2.1.25.4',
-  'https://www.ilo.org/global/about-the-ilo/newsroom/news/WCMS_574717/lang--en/index.htm',
-  'https://cdrdv2-public.intel.com/671488/248966-Software-Optimization-Manual-R047.pdf',
-  regex('https://www.lumendatabase.org/'),
-  regex('https://azure.microsoft.com/'),
-  regex('https://support.patreon.com/'),
-  'https://moodle.org',
-  'https://azure.microsoft.com',
-  'https://api.octocorp.ghe.com',
-  'https://platform.openai.com/docs/guides/safety-best-practices',
-  'https://global.rel.tunnels.api.visualstudio.com/api/version',
-  'https://www.wireguard.com/quickstart/',
-  'https://docs.openstack.org/horizon/latest/',
-  'https://packages.ubuntu.com/search?keywords=netcat&searchon=names',
-]
+if (excludedLinks.some(({ startsWith, is }) => startsWith && is)) {
+  throw new Error(
+    'Excluded links cannot have both <startsWith> and <is> keys. Please update excluded-links.yml to only have one of them for each entry.',
+  )
+}

 export default excludedLinks
-
-// Return a regular expression from a URL string that matches the URL
-// as a base. It's basically shorthand for "URL.startsWith(BASE_URL)"
-// but as a RegExp object.
-// For example:
-//
-//   > regex('https://github.com').test('https://github.com/page')
-//   true
-//   > regex('https://github.com').test('otherhttps://github.com/page')
-//   false
-function regex(url: string) {
-  return new RegExp('^' + url.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-}
--- a/src/links/lib/excluded-links.yml
+++ b/src/links/lib/excluded-links.yml
@@ -0,0 +1,68 @@
+# Skip GitHub search links.
+# E.g. https://github.com/search?foo=bar
+- startsWith: https://github.com/search?
+- startsWith: https://github.com/github/gitignore/search?
+
+# https://github.com/contact always redirects to support.github.com that
+# is heavily protected by rate limiting.
+- startsWith: https://github.com/contact
+# All support.github.com links are currently firewalled and you get a
+# "403 Forbidden" every time.
+- startsWith: https://support.github.com
+
+# These links require auth.
+- startsWith: https://github.com/settings/profile
+- startsWith: https://github.com/settings/billing
+- startsWith: https://github.com/github/docs/edit
+- startsWith: https://github.com/github/insights-releases/releases/latest
+- startsWith: https://classroom.github.com/videos
+
+# Oneoff links that link checkers think are broken but are not.
+- is: https://haveibeenpwned.com/
+- is: https://www.ilo.org/dyn/normlex/en/f?p=NORMLEXPUB:12100:0::NO::P12100_ILO_CODE:P029
+- is: https://www.linkedin.com/company/github
+- is: https://www.facebook.com/
+- is: https://ko-fi.com/
+- is: https://en.liberapay.com/
+- is: https://nbviewer.jupyter.org/github/bokeh/bokeh-notebooks/blob/main/tutorial/06%20-%20Linking%20and%20Interactions.ipynb
+- is: https://www.vmware.com/products/esxi-and-esx.html
+- is: https://www.ecfr.gov/cgi-bin/text-idx?SID=ad384e1f1e017076f8c0136f322f0a4c&mc=true&node=pt15.2.744&rgn=div5
+- is: https://wiki.oasis-open.org/security
+- is: https://www.ipaddressguide.com/cidr
+- is: https://crates.io/
+- is: https://opensource.org/about
+- is: https://www.openstreetmap.org/user/new
+- is: https://wiki.debian.org/chroot
+- is: https://www.adobe.com/products/coldfusion-builder.html
+- is: https://developer.android.com/studio
+- is: https://lastpass.com/
+- is: https://lastpass.com/auth/
+- is: https://zenodo.org/account/settings/github/
+- is: https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files
+- is: https://developer.apple.com/documentation/swift_packages
+- is: https://developer.android.com/studio/run/emulator-acceleration
+- is: https://support.discord.com/hc/en-us/articles/360045138571-Beginner-s-Guide-to-Discord
+- is: https://www.microsoft.com/en-us/edge
+- is: https://github.com/features/bitbucket-migrations/signup
+- is: https://www.servicenow.com/products/devops.html
+- is: https://daringfireball.net/projects/markdown/syntax
+- is: https://www.microsoft.com/en-us/security/mobile-authenticator-app
+- is: https://microsoft.com/powershell
+- is: https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_method
+- is: https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ID3QAM/github-connector
+- is: https://www.patreon.com/
+- startsWith: https://packages.debian.org/
+- is: https://oidref.com/1.3.6.1.2.1.25.4
+- is: https://www.ilo.org/global/about-the-ilo/newsroom/news/WCMS_574717/lang--en/index.htm
+- is: https://cdrdv2-public.intel.com/671488/248966-Software-Optimization-Manual-R047.pdf
+- startsWith: https://www.lumendatabase.org/
+- startsWith: https://azure.microsoft.com/
+- startsWith: https://support.patreon.com/
+- is: https://moodle.org
+- is: https://azure.microsoft.com
+- is: https://api.octocorp.ghe.com
+- is: https://platform.openai.com/docs/guides/safety-best-practices
+- is: https://global.rel.tunnels.api.visualstudio.com/api/version
+- is: https://www.wireguard.com/quickstart/
+- is: https://docs.openstack.org/horizon/latest/
+- is: https://packages.ubuntu.com/search?keywords=netcat&searchon=names
--- a/src/links/scripts/rendered-content-link-checker.ts
+++ b/src/links/scripts/rendered-content-link-checker.ts
@@ -133,10 +133,9 @@ function jitter(base: number, percentage: number) {
 // Do this so we can use a `Set` and a `iterable.some()` for a speedier
 // check.
 function linksToSkipFactory() {
-  const set = new Set(excludedLinks.filter((regexOrURL) => typeof regexOrURL === 'string'))
-  // This `... as RegExp` because TypeScript can't (currently) understand the filtering.
-  const regexes = excludedLinks.filter((regexOrURL) => regexOrURL instanceof RegExp) as RegExp[]
-  return (href: string) => set.has(href) || regexes.some((regex) => regex.test(href))
+  const set = new Set(excludedLinks.map(({ is }) => is).filter(Boolean))
+  const arr = excludedLinks.map(({ startsWith }) => startsWith).filter(Boolean)
+  return (href: string) => set.has(href) || arr.some((v) => v && href.startsWith(v))
 }

 const linksToSkip = linksToSkipFactory()