From 117d1f18583258fb5a2d4de0a45d43b95ad7d696 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Wed, 24 May 2023 09:27:21 -0700 Subject: [PATCH 1/4] Document setup URL (#37243) Co-authored-by: James Martin --- .../about-the-setup-url.md | 30 +++++++++++++++++++ ...out-the-user-authorization-callback-url.md | 6 ++-- ...ating-a-github-app-using-url-parameters.md | 2 +- .../creating-a-github-app.md | 2 +- .../setting-up-a-github-app/index.md | 1 + .../handling-new-purchases-and-free-trials.md | 2 +- 6 files changed, 37 insertions(+), 6 deletions(-) create mode 100644 content/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url.md diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url.md b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url.md new file mode 100644 index 000000000000..725b42868bd3 --- /dev/null +++ b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url.md @@ -0,0 +1,30 @@ +--- +title: About the setup URL +intro: 'You can specify a URL that users will be redirected to after they install a {% data variables.product.prodname_github_app %}.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - GitHub Apps +shortTitle: Setup URL +--- + +When you create a {% data variables.product.prodname_github_app %}, you can specify a setup URL. When users install your {% data variables.product.prodname_github_app %}, they are redirected to the setup URL. If additional setup is required after installation, you can use this URL to tell users what steps to take next. + +If you specify a setup URL, you can also select **Redirect on update** to specify that users should be redirected to the setup URL after they update an installation. An update includes adding or removing access to a repository for an installation. + +{% warning %} + +**Warning**: When {% data variables.product.company_short %} redirects users to the setup URL, it includes an `installation_id` query parameter. Bad actors can hit this URL with a spoofed `installation_id`. Therefore, you should not rely on the validity of the `installation_id` parameter. Instead, you should generate a user access token for the user who installed the {% data variables.product.prodname_github_app %} and then check that the installation is associated with that user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." + +{% endwarning %} + +{% ifversion fpt or ghec %} +Although the setup URL is optional in the {% data variables.product.prodname_github_app %} settings, it is required if you want to allow users to purchase your app in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials)." +{% endif %} + +The setup URL is different from the callback URL. Users are redirected to the setup URL after they install a {% data variables.product.prodname_github_app %}. Users are redirected to the callback URL when they authorize a {% data variables.product.company_short %} via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)." + +For more information about creating or modifying a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)." diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md index 54fdf80e3477..cae8908c9a66 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url.md @@ -1,6 +1,6 @@ --- title: About the user authorization callback URL -intro: 'You can specify a URL that users will be redirected to after they authorize an app.' +intro: 'You can specify a URL that users will be redirected to after they authorize a {% data variables.product.prodname_github_app %}.' versions: fpt: '*' ghes: '*' @@ -17,6 +17,6 @@ When you create a {% data variables.product.prodname_github_app %}, you can spec You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your app, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. -The callback URL is different from the setup URL. Users are redirected to the setup URL after they install an app. Users are redirected to the callback URL when they authorize an app via the web application flow. +The callback URL is different from the setup URL. Users are redirected to the setup URL after they install an app. Users are redirected to the callback URL when they authorize an app via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." -For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about creating a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." +For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about creating or modifying a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)." diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md index f8bbe5ee09a6..02d00411d4ca 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters.md @@ -49,7 +49,7 @@ Parameter name | Type | Description `url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage. `callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to generate a user access token. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)." `request_oauth_on_install` | `boolean` | If your app authorizes users using the OAuth flow, you can set this option to `true` to allow people to authorize the app when they install it, saving a step. If you select this option, the `setup_url` becomes unavailable and users will be redirected to your `callback_url` after installing the app. -`setup_url` | `string` | The full URL to redirect to after someone installs the {% data variables.product.prodname_github_app %} if the app requires additional setup after installation. +`setup_url` | `string` | The full URL to redirect to after someone installs the {% data variables.product.prodname_github_app %} if the app requires additional setup after installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." `setup_on_update` | `boolean` | Set to `true` to redirect people to the setup URL when installations have been updated, for example, after repositories are added or removed. `public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. `webhook_active` | `boolean` | Set to `true` to enable webhook. Webhook is disabled by default. diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md index c75512ca155a..4e351ade677f 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app.md @@ -45,7 +45,7 @@ You can create a {% data variables.product.prodname_github_app %} owned by your 1. Optionally, to prevent user access tokens from expiring, deselect **Expire user authorization tokens**. {% data variables.product.company_short %} strongly recommends that you leave this option selected. For more information about refreshing expired tokens and the benefits of user access tokens that expire, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)." If your app does not need to generate a user access token, this field will be ignored. 1. Optionally, to prompt users to authorize your app when they install it, select **Request user authorization (OAuth) during installation**. If a user authorizes your app, your app can generate a user access token to make API requests on the user's behalf and attribute app activity to the user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." 1. Optionally, if you want to use device flow to generate a user access token, select **Enable Device Flow**. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." -1. Optionally, under "Setup URL", enter the URL to redirect users to after they install your app. If additional setup is required after installation, you can use this URL to tell users what steps to take after installation. +1. Optionally, under "Setup URL", enter the URL to redirect users to after they install your app. If additional setup is required after installation, you can use this URL to tell users what steps to take after installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." If you selected **Request user authorization (OAuth) during installation** in an earlier step, you will not be able to enter a URL here. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. 1. Optionally, if you want to redirect users to the setup URL after they update an installation, select **Redirect on update**. An update includes adding or removing a repository for an installation. If "Setup URL" is blank, this will be ignored. diff --git a/content/apps/creating-github-apps/setting-up-a-github-app/index.md b/content/apps/creating-github-apps/setting-up-a-github-app/index.md index 84debae99452..c20b90542954 100644 --- a/content/apps/creating-github-apps/setting-up-a-github-app/index.md +++ b/content/apps/creating-github-apps/setting-up-a-github-app/index.md @@ -22,5 +22,6 @@ children: - /creating-a-github-app-using-url-parameters - /creating-a-custom-badge-for-your-github-app - /about-the-user-authorization-callback-url + - /about-the-setup-url --- diff --git a/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md b/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md index 1300346f2241..d702df1f7341 100644 --- a/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md +++ b/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md @@ -43,7 +43,7 @@ At this point, if you specified a **Setup URL** in your {% data variables.produc {% note %} -**Note:** The **Setup URL** is described as optional in {% data variables.product.prodname_github_app %} settings, but it is a required field if you want to offer your app in {% data variables.product.prodname_marketplace %}. +**Note:** The **Setup URL** is described as optional in {% data variables.product.prodname_github_app %} settings, but it is a required field if you want to offer your app in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)." {% endnote %} From d688891ecbb9c482892caf8ab0df5d96e23475e9 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Wed, 24 May 2023 09:28:06 -0700 Subject: [PATCH 2/4] Add request for more engineering info in pull request body (#37069) Co-authored-by: Peter Bengtsson --- .../workflows/codeowners-docs-engineering.yml | 47 +++++++++++++++++-- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/.github/workflows/codeowners-docs-engineering.yml b/.github/workflows/codeowners-docs-engineering.yml index f282ba38d516..3f47e6fe147d 100644 --- a/.github/workflows/codeowners-docs-engineering.yml +++ b/.github/workflows/codeowners-docs-engineering.yml @@ -1,7 +1,8 @@ name: Codeowners - Docs Engineering # **What it does**: Automatically add reviewers based on paths, but only for the docs-internal repo. -# And sets the 'engineering' label on the PR. +# And sets the 'engineering' label on the PR. It also edits the PR body to add a template +# for asking questions for the sake of being confident about the PRs rollout. # **Why we have it**: So we can have reviewers automatically without getting open source notifications. # **Who does it impact**: Docs team. @@ -21,9 +22,45 @@ jobs: codeowners-docs-engineering: if: ${{ github.repository == 'github/docs-internal' }} runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ secrets.DOCS_BOT_FR }} + PR: ${{ github.event.pull_request.html_url }} + steps: + - name: Label as engineering + run: gh pr edit $PR --add-label engineering + - name: Add Docs Engineering as a reviewer - env: - GH_TOKEN: ${{ secrets.DOCS_BOT_FR }} - PR: ${{ github.event.pull_request.html_url }} - run: gh pr edit $PR --add-reviewer github/docs-engineering --add-label engineering + run: | + has_reviewer=$( + gh pr view $PR --json reviews | + jq 'any(.reviews[]; select(length > 0))' + ) + if ! $has_reviewer + then + gh pr edit $PR --add-reviewer github/docs-engineering + fi + + - name: Additional information requested + run: | + id=9664BE8F1CA3 + body=$(gh pr view $PR --json body | jq -r .body) + append=$(cat <<-EOM + + ### For engineers + + - **How to test**: {Step by step.} + - **How to review**: {What to look for when reviewing.} + - **Potential risks**: {Any additional risks this change may introduce.} + - **How to monitor**: {Datadog link, etc.} + - **How to rollback**: {Any additional information beyond shipping a revert pull request.} + - **Accessibility impact**: {Any changes to React components.} + + If this involves manual change, please create a [production change issue](https://github.com/github/docs-engineering/issues/new?labels=engineering&projects=&template=production-config-change.md). + EOM + ) + if [[ ! $body =~ $id ]] + then + body+=$append + gh pr edit $PR --body "$body" + fi From 77f2b537ada8754f0911a6914c4c562151179e3c Mon Sep 17 00:00:00 2001 From: Matt Pollard Date: Wed, 24 May 2023 18:44:41 +0200 Subject: [PATCH 3/4] Add date to release note for self-hosted runner limit in GHES 3.7 (#37259) --- data/release-notes/enterprise-server/3-7/0.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/release-notes/enterprise-server/3-7/0.yml b/data/release-notes/enterprise-server/3-7/0.yml index de9ee09556f0..d89ee769728b 100644 --- a/data/release-notes/enterprise-server/3-7/0.yml +++ b/data/release-notes/enterprise-server/3-7/0.yml @@ -321,7 +321,7 @@ sections: - The size of the search field for user, organization, and enterprise audit logs has increased. # https://github.com/github/actions-dotnet/pull/12831 - - The maximum number of self-hosted runners in a runner group is limited to 10,000. Previously, there was no limit. + - 'The maximum number of self-hosted runners in a runner group is limited to 10,000. Previously, there was no limit. [Updated: 2023-05-24]' known_issues: - On a freshly set up {% data variables.product.prodname_ghe_server %} instance without any users, an attacker could create the first admin user. From c75433439e2fdd43640af008c7cd69afbdc26979 Mon Sep 17 00:00:00 2001 From: Matt Pollard Date: Wed, 24 May 2023 18:49:31 +0200 Subject: [PATCH 4/4] Mention availability of IP exception list for maintenance mode in GHES 3.4 docs (#37260) --- .../enabling-and-scheduling-maintenance-mode.md | 10 ++++++++++ data/features/ip-exception-list.yml | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/content/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode.md b/content/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode.md index 427ddd144d34..2745eee79213 100644 --- a/content/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode.md +++ b/content/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode.md @@ -56,6 +56,16 @@ You can perform initial validation of your maintenance operation by configuring ## Validating changes in maintenance mode using the IP exception list +{% ifversion ghes = 3.4 %} + +{% note %} + +**Note**: To validate changes in maintenance mode using the IP exception list, your {% data variables.product.product_name %} instance must be running version 3.4.4 or later. + +{% endnote %} + +{% endif %} + The IP exception list provides controlled and restricted access to {% data variables.location.product_location %}, which is ideal for initial validation of server health following a maintenance operation. Once enabled, {% data variables.location.product_location %} will be taken out of maintenance mode and available only to the configured IP addresses. The maintenance mode checkbox will be updated to reflect the change in state. If you re-enable maintenance mode, the IP exception list will be disabled and {% data variables.location.product_location %} will return to maintenance mode. If you just disable the IP exception list, {% data variables.location.product_location %} will return to normal operation. diff --git a/data/features/ip-exception-list.yml b/data/features/ip-exception-list.yml index 25902ba928ed..8c9bdce8aa4b 100644 --- a/data/features/ip-exception-list.yml +++ b/data/features/ip-exception-list.yml @@ -1,2 +1,2 @@ versions: - ghes: '>=3.5' + ghes: '>=3.4'