diff --git a/.github/allowed-actions.js b/.github/allowed-actions.js index 6450852204..9d2d7400e2 100644 --- a/.github/allowed-actions.js +++ b/.github/allowed-actions.js @@ -30,7 +30,7 @@ module.exports = [ 'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e', 'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88', 'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d', - 'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815', + 'someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd', 'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0', 'EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575' ] diff --git a/.github/workflows/js-lint.yml b/.github/workflows/js-lint.yml index 3da0e854a2..4c138c5955 100644 --- a/.github/workflows/js-lint.yml +++ b/.github/workflows/js-lint.yml @@ -10,23 +10,8 @@ on: - translations jobs: - see_if_should_skip: - runs-on: ubuntu-latest - - outputs: - should_skip: ${{ steps.skip_check.outputs.should_skip }} - steps: - - id: skip_check - uses: fkirc/skip-duplicate-actions@36feb0d8d062137530c2e00bd278d138fe191289 - with: - cancel_others: 'false' - github_token: ${{ github.token }} - paths: '["**/*.js", "package*.json", ".github/workflows/js-lint.yml", ".eslint*"]' - lint: runs-on: ubuntu-latest - needs: see_if_should_skip - if: ${{ needs.see_if_should_skip.outputs.should_skip != 'true' }} steps: - name: Check out repo uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f diff --git a/.github/workflows/repo-freeze-reminders.yml b/.github/workflows/repo-freeze-reminders.yml index e6f7eb479e..f3b166cd87 100644 --- a/.github/workflows/repo-freeze-reminders.yml +++ b/.github/workflows/repo-freeze-reminders.yml @@ -14,11 +14,10 @@ jobs: if: github.repository == 'github/docs-internal' steps: - name: Send Slack notification if repo is frozen + uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: ${{ env.FREEZE == 'true' }} - uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 - env: - SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} - SLACK_USERNAME: docs-repo-sync - SLACK_ICON_EMOJI: ':freezing_face:' - SLACK_COLOR: '#51A0D5' # Carolina Blue - SLACK_MESSAGE: All repo-sync runs will fail for ${{ github.repository }} because the repo is currently frozen! + with: + channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} + bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} + color: info + text: All repo-sync runs will fail for ${{ github.repository }} because the repo is currently frozen! diff --git a/.github/workflows/repo-sync-stalls.yml b/.github/workflows/repo-sync-stalls.yml new file mode 100644 index 0000000000..fb605313c3 --- /dev/null +++ b/.github/workflows/repo-sync-stalls.yml @@ -0,0 +1,54 @@ +name: Repo Sync Stalls +on: + workflow_dispatch: + schedule: + - cron: '*/30 * * * *' +jobs: + check-freezer: + name: Check for deployment freezes + runs-on: ubuntu-latest + steps: + - name: Exit if repo is frozen + if: ${{ env.FREEZE == 'true' }} + run: | + echo 'The repo is currently frozen! Exiting this workflow.' + exit 1 # prevents further steps from running + repo-sync-stalls: + runs-on: ubuntu-latest + steps: + - name: Check if repo sync is stalled + uses: actions/github-script@626af12fe9a53dc2972b48385e7fe7dec79145c9 + with: + github-token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }} + script: | + let pulls; + const owner = context.repo.owner + const repo = context.repo.repo + try { + pulls = await github.pulls.list({ + owner: owner, + repo: repo, + head: `${owner}:repo-sync`, + state: 'open' + }); + } catch(err) { + throw err + return + } + + pulls.data.forEach(pr => { + const timeDelta = Date.now() - Date.parse(pr.created_at); + const minutesOpen = timeDelta / 1000 / 60; + + if (minutesOpen > 30) { + core.setFailed('Repo sync appears to be stalled') + } + }) + - name: Send Slack notification if workflow fails + uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd + if: failure() + with: + channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} + bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} + color: failure + text: Repo sync appears to be stalled for ${{github.repository}}. See https://github.com/${{github.repository}}/pulls?q=is%3Apr+is%3Aopen+repo+sync diff --git a/.github/workflows/repo-sync.yml b/.github/workflows/repo-sync.yml index b33242e90b..298eab5668 100644 --- a/.github/workflows/repo-sync.yml +++ b/.github/workflows/repo-sync.yml @@ -7,6 +7,7 @@ name: Repo Sync on: + workflow_dispatch: schedule: - cron: '*/15 * * * *' # every 15 minutes @@ -70,11 +71,10 @@ jobs: number: ${{ steps.find-pull-request.outputs.number }} - name: Send Slack notification if workflow fails - uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 - if: ${{ failure() }} - env: - SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} - SLACK_USERNAME: docs-repo-sync - SLACK_ICON_EMOJI: ':ohno:' - SLACK_COLOR: '#B90E0A' # Crimson - SLACK_MESSAGE: The last repo-sync run for ${{github.repository}} failed. See https://github.com/${{github.repository}}/actions?query=workflow%3A%22Repo+Sync%22 + uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd + if: failure() + with: + channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} + bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} + color: failure + text: The last repo-sync run for ${{github.repository}} failed. See https://github.com/${{github.repository}}/actions?query=workflow%3A%22Repo+Sync%22 diff --git a/.github/workflows/sync-algolia-search-indices.yml b/.github/workflows/sync-algolia-search-indices.yml index a7f9ac3b49..512b3b0e0c 100644 --- a/.github/workflows/sync-algolia-search-indices.yml +++ b/.github/workflows/sync-algolia-search-indices.yml @@ -33,8 +33,10 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: npm run sync-search - name: Send slack notification if workflow run fails - uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 + uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: failure() - env: - SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} - SLACK_MESSAGE: The last Algolia workflow run for ${{github.repository}} failed. Search actions for `workflow:Algolia` + with: + channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} + bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} + color: failure + text: The last Algolia workflow run for ${{github.repository}} failed. Search actions for `workflow:Algolia` diff --git a/.github/workflows/yml-lint.yml b/.github/workflows/yml-lint.yml index 69d665ecde..f8248961e0 100644 --- a/.github/workflows/yml-lint.yml +++ b/.github/workflows/yml-lint.yml @@ -10,23 +10,8 @@ on: - translations jobs: - see_if_should_skip: - runs-on: ubuntu-latest - - outputs: - should_skip: ${{ steps.skip_check.outputs.should_skip }} - steps: - - id: skip_check - uses: fkirc/skip-duplicate-actions@36feb0d8d062137530c2e00bd278d138fe191289 - with: - cancel_others: 'false' - github_token: ${{ github.token }} - paths: '["**/*.yml", "**/*.yaml", "package*.json", ".github/workflows/yml-lint.yml"]' - lint: runs-on: ubuntu-latest - needs: see_if_should_skip - if: ${{ needs.see_if_should_skip.outputs.should_skip != 'true' }} steps: - name: Check out repo uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f diff --git a/assets/images/help/discussions/public-repo-settings.png b/assets/images/help/discussions/public-repo-settings.png new file mode 100644 index 0000000000..c337a3a220 Binary files /dev/null and b/assets/images/help/discussions/public-repo-settings.png differ diff --git a/assets/images/help/images/overview-actions-result-navigate.png b/assets/images/help/images/overview-actions-result-navigate.png new file mode 100644 index 0000000000..819f0e75e7 Binary files /dev/null and b/assets/images/help/images/overview-actions-result-navigate.png differ diff --git a/assets/images/help/images/overview-actions-result-updated-2.png b/assets/images/help/images/overview-actions-result-updated-2.png new file mode 100644 index 0000000000..7035583127 Binary files /dev/null and b/assets/images/help/images/overview-actions-result-updated-2.png differ diff --git a/assets/images/help/images/workflow-graph-job.png b/assets/images/help/images/workflow-graph-job.png new file mode 100644 index 0000000000..7aafcb5d89 Binary files /dev/null and b/assets/images/help/images/workflow-graph-job.png differ diff --git a/assets/images/help/images/workflow-graph.png b/assets/images/help/images/workflow-graph.png new file mode 100644 index 0000000000..ebd1b6a07c Binary files /dev/null and b/assets/images/help/images/workflow-graph.png differ diff --git a/assets/images/help/organizations/update-profile-button.png b/assets/images/help/organizations/update-profile-button.png new file mode 100644 index 0000000000..bb701e7aed Binary files /dev/null and b/assets/images/help/organizations/update-profile-button.png differ diff --git a/assets/images/help/pull_requests/dependency-review-rich-diff.png b/assets/images/help/pull_requests/dependency-review-rich-diff.png new file mode 100644 index 0000000000..dd782e3168 Binary files /dev/null and b/assets/images/help/pull_requests/dependency-review-rich-diff.png differ diff --git a/assets/images/help/pull_requests/dependency-review-source-diff.png b/assets/images/help/pull_requests/dependency-review-source-diff.png new file mode 100644 index 0000000000..aa5e394d81 Binary files /dev/null and b/assets/images/help/pull_requests/dependency-review-source-diff.png differ diff --git a/assets/images/help/pull_requests/dependency-review-vulnerability.png b/assets/images/help/pull_requests/dependency-review-vulnerability.png new file mode 100644 index 0000000000..9e69c9d0d5 Binary files /dev/null and b/assets/images/help/pull_requests/dependency-review-vulnerability.png differ diff --git a/assets/images/help/pull_requests/file-filter-menu-json.png b/assets/images/help/pull_requests/file-filter-menu-json.png new file mode 100644 index 0000000000..f37475293b Binary files /dev/null and b/assets/images/help/pull_requests/file-filter-menu-json.png differ diff --git a/assets/images/help/pull_requests/pull-request-tabs-changed-files.png b/assets/images/help/pull_requests/pull-request-tabs-changed-files.png index a5ca74c433..34f5f6fc16 100644 Binary files a/assets/images/help/pull_requests/pull-request-tabs-changed-files.png and b/assets/images/help/pull_requests/pull-request-tabs-changed-files.png differ diff --git a/assets/images/help/repository/actions-delete-artifact-updated.png b/assets/images/help/repository/actions-delete-artifact-updated.png new file mode 100644 index 0000000000..b84fc77bd4 Binary files /dev/null and b/assets/images/help/repository/actions-delete-artifact-updated.png differ diff --git a/assets/images/help/repository/actions-failed-pester-test-updated.png b/assets/images/help/repository/actions-failed-pester-test-updated.png new file mode 100644 index 0000000000..022a0a5370 Binary files /dev/null and b/assets/images/help/repository/actions-failed-pester-test-updated.png differ diff --git a/assets/images/help/repository/artifact-drop-down-updated.png b/assets/images/help/repository/artifact-drop-down-updated.png new file mode 100644 index 0000000000..6ddc426fec Binary files /dev/null and b/assets/images/help/repository/artifact-drop-down-updated.png differ diff --git a/assets/images/help/repository/cancel-check-suite-updated.png b/assets/images/help/repository/cancel-check-suite-updated.png new file mode 100644 index 0000000000..533a2bcb5e Binary files /dev/null and b/assets/images/help/repository/cancel-check-suite-updated.png differ diff --git a/assets/images/help/repository/copy-link-button-updated-2.png b/assets/images/help/repository/copy-link-button-updated-2.png new file mode 100644 index 0000000000..dfa0bab265 Binary files /dev/null and b/assets/images/help/repository/copy-link-button-updated-2.png differ diff --git a/assets/images/help/repository/delete-all-logs-updated-2.png b/assets/images/help/repository/delete-all-logs-updated-2.png new file mode 100644 index 0000000000..a902b47f60 Binary files /dev/null and b/assets/images/help/repository/delete-all-logs-updated-2.png differ diff --git a/assets/images/help/repository/docker-action-workflow-run-updated.png b/assets/images/help/repository/docker-action-workflow-run-updated.png new file mode 100644 index 0000000000..ae31b91911 Binary files /dev/null and b/assets/images/help/repository/docker-action-workflow-run-updated.png differ diff --git a/assets/images/help/repository/download-logs-drop-down-updated-2.png b/assets/images/help/repository/download-logs-drop-down-updated-2.png new file mode 100644 index 0000000000..128d392113 Binary files /dev/null and b/assets/images/help/repository/download-logs-drop-down-updated-2.png differ diff --git a/assets/images/help/repository/in-progress-run.png b/assets/images/help/repository/in-progress-run.png new file mode 100644 index 0000000000..0419dc4929 Binary files /dev/null and b/assets/images/help/repository/in-progress-run.png differ diff --git a/assets/images/help/repository/javascript-action-workflow-run-updated-2.png b/assets/images/help/repository/javascript-action-workflow-run-updated-2.png new file mode 100644 index 0000000000..b60a7536fd Binary files /dev/null and b/assets/images/help/repository/javascript-action-workflow-run-updated-2.png differ diff --git a/assets/images/help/repository/passing-data-between-jobs-in-a-workflow-updated.png b/assets/images/help/repository/passing-data-between-jobs-in-a-workflow-updated.png new file mode 100644 index 0000000000..c498028024 Binary files /dev/null and b/assets/images/help/repository/passing-data-between-jobs-in-a-workflow-updated.png differ diff --git a/assets/images/help/repository/rerun-checks-drop-down-updated.png b/assets/images/help/repository/rerun-checks-drop-down-updated.png new file mode 100644 index 0000000000..4d769074ee Binary files /dev/null and b/assets/images/help/repository/rerun-checks-drop-down-updated.png differ diff --git a/assets/images/help/repository/search-log-box-updated-2.png b/assets/images/help/repository/search-log-box-updated-2.png new file mode 100644 index 0000000000..9ab228e44c Binary files /dev/null and b/assets/images/help/repository/search-log-box-updated-2.png differ diff --git a/assets/images/help/repository/super-linter-workflow-results-updated-2.png b/assets/images/help/repository/super-linter-workflow-results-updated-2.png new file mode 100644 index 0000000000..6bdde69b11 Binary files /dev/null and b/assets/images/help/repository/super-linter-workflow-results-updated-2.png differ diff --git a/assets/images/help/repository/superlinter-lint-code-base-job-updated.png b/assets/images/help/repository/superlinter-lint-code-base-job-updated.png new file mode 100644 index 0000000000..80ee94d0ce Binary files /dev/null and b/assets/images/help/repository/superlinter-lint-code-base-job-updated.png differ diff --git a/assets/images/help/repository/upload-build-test-artifact.png b/assets/images/help/repository/upload-build-test-artifact.png deleted file mode 100644 index 8739bf1192..0000000000 Binary files a/assets/images/help/repository/upload-build-test-artifact.png and /dev/null differ diff --git a/assets/images/help/repository/view-run-billable-time.png b/assets/images/help/repository/view-run-billable-time.png index 9f1b8643f9..c627f398b3 100644 Binary files a/assets/images/help/repository/view-run-billable-time.png and b/assets/images/help/repository/view-run-billable-time.png differ diff --git a/assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated-2.png b/assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated-2.png new file mode 100644 index 0000000000..952e86f576 Binary files /dev/null and b/assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated-2.png differ diff --git a/assets/images/help/settings/appearance-tab.png b/assets/images/help/settings/appearance-tab.png index 5e5e975891..dcd3422ac6 100644 Binary files a/assets/images/help/settings/appearance-tab.png and b/assets/images/help/settings/appearance-tab.png differ diff --git a/assets/images/help/settings/theme-settings-radio-buttons.png b/assets/images/help/settings/theme-settings-radio-buttons.png new file mode 100644 index 0000000000..32c87156c7 Binary files /dev/null and b/assets/images/help/settings/theme-settings-radio-buttons.png differ diff --git a/assets/images/help/settings/update-theme-preference-button.png b/assets/images/help/settings/update-theme-preference-button.png new file mode 100644 index 0000000000..19fd375fe1 Binary files /dev/null and b/assets/images/help/settings/update-theme-preference-button.png differ diff --git a/assets/images/help/sponsors/billing-account-switcher.png b/assets/images/help/sponsors/billing-account-switcher.png new file mode 100644 index 0000000000..d3240f358a Binary files /dev/null and b/assets/images/help/sponsors/billing-account-switcher.png differ diff --git a/assets/images/help/sponsors/edit-sponsorship-payment-button.png b/assets/images/help/sponsors/edit-sponsorship-payment-button.png index 36d2c51e49..369165c851 100644 Binary files a/assets/images/help/sponsors/edit-sponsorship-payment-button.png and b/assets/images/help/sponsors/edit-sponsorship-payment-button.png differ diff --git a/assets/images/help/sponsors/link-account-button.png b/assets/images/help/sponsors/link-account-button.png new file mode 100644 index 0000000000..c8d6992730 Binary files /dev/null and b/assets/images/help/sponsors/link-account-button.png differ diff --git a/assets/images/help/sponsors/manage-your-sponsorship-button.png b/assets/images/help/sponsors/manage-your-sponsorship-button.png index 3c094ea2fc..d6a7ad78bc 100644 Binary files a/assets/images/help/sponsors/manage-your-sponsorship-button.png and b/assets/images/help/sponsors/manage-your-sponsorship-button.png differ diff --git a/assets/images/help/sponsors/organization-update-email-textbox.png b/assets/images/help/sponsors/organization-update-email-textbox.png new file mode 100644 index 0000000000..2e5c3fdfc1 Binary files /dev/null and b/assets/images/help/sponsors/organization-update-email-textbox.png differ diff --git a/assets/images/help/sponsors/pay-prorated-amount-link.png b/assets/images/help/sponsors/pay-prorated-amount-link.png new file mode 100644 index 0000000000..6d73469e51 Binary files /dev/null and b/assets/images/help/sponsors/pay-prorated-amount-link.png differ diff --git a/assets/images/help/sponsors/select-an-account-drop-down.png b/assets/images/help/sponsors/select-an-account-drop-down.png new file mode 100644 index 0000000000..8cbe763af7 Binary files /dev/null and b/assets/images/help/sponsors/select-an-account-drop-down.png differ diff --git a/assets/images/help/sponsors/sponsor-as-drop-down-menu.png b/assets/images/help/sponsors/sponsor-as-drop-down-menu.png new file mode 100644 index 0000000000..0f9419d47f Binary files /dev/null and b/assets/images/help/sponsors/sponsor-as-drop-down-menu.png differ diff --git a/assets/images/help/sponsors/sponsoring-as-drop-down-menu.png b/assets/images/help/sponsors/sponsoring-as-drop-down-menu.png new file mode 100644 index 0000000000..1ee7126df3 Binary files /dev/null and b/assets/images/help/sponsors/sponsoring-as-drop-down-menu.png differ diff --git a/assets/images/help/sponsors/sponsoring-settings-button.png b/assets/images/help/sponsors/sponsoring-settings-button.png new file mode 100644 index 0000000000..ce20577af9 Binary files /dev/null and b/assets/images/help/sponsors/sponsoring-settings-button.png differ diff --git a/assets/images/help/sponsors/sponsoring-tab.png b/assets/images/help/sponsors/sponsoring-tab.png new file mode 100644 index 0000000000..0c62587deb Binary files /dev/null and b/assets/images/help/sponsors/sponsoring-tab.png differ diff --git a/assets/images/help/sponsors/update-checkbox-manage.png b/assets/images/help/sponsors/update-checkbox-manage.png new file mode 100644 index 0000000000..8fe85c0aa9 Binary files /dev/null and b/assets/images/help/sponsors/update-checkbox-manage.png differ diff --git a/assets/images/marketplace/marketplace-request-button.png b/assets/images/marketplace/marketplace-request-button.png index 5d20741085..f8152f0de5 100644 Binary files a/assets/images/marketplace/marketplace-request-button.png and b/assets/images/marketplace/marketplace-request-button.png differ diff --git a/assets/images/marketplace/marketplace_verified_creator_badges_apps.png b/assets/images/marketplace/marketplace_verified_creator_badges_apps.png new file mode 100644 index 0000000000..6f353f0adf Binary files /dev/null and b/assets/images/marketplace/marketplace_verified_creator_badges_apps.png differ diff --git a/content/actions/creating-actions/creating-a-docker-container-action.md b/content/actions/creating-actions/creating-a-docker-container-action.md index a51ab9b2ca..ba06a3a938 100644 --- a/content/actions/creating-actions/creating-a-docker-container-action.md +++ b/content/actions/creating-actions/creating-a-docker-container-action.md @@ -226,6 +226,10 @@ jobs: ``` {% endraw %} -From your repository, click the **Actions** tab, and select the latest workflow run. You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. +From your repository, click the **Actions** tab, and select the latest workflow run. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Under **Jobs** or in the visualization graph, click **A job to say hello**. {% endif %}You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +![A screenshot of using your action in a workflow](/assets/images/help/repository/docker-action-workflow-run-updated.png) +{% else %} ![A screenshot of using your action in a workflow](/assets/images/help/repository/docker-action-workflow-run.png) +{% endif %} diff --git a/content/actions/creating-actions/creating-a-javascript-action.md b/content/actions/creating-actions/creating-a-javascript-action.md index e2987d0d15..d738d7cd43 100644 --- a/content/actions/creating-actions/creating-a-javascript-action.md +++ b/content/actions/creating-actions/creating-a-javascript-action.md @@ -261,9 +261,11 @@ jobs: ``` {% endraw %} -From your repository, click the **Actions** tab, and select the latest workflow run. You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. +From your repository, click the **Actions** tab, and select the latest workflow run. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Under **Jobs** or in the visualization graph, click **A job to say hello**. {% endif %}You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. -{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +![A screenshot of using your action in a workflow](/assets/images/help/repository/javascript-action-workflow-run-updated-2.png) +{% elsif currentVersion ver_gt "enterprise-server@2.22" %} ![A screenshot of using your action in a workflow](/assets/images/help/repository/javascript-action-workflow-run-updated.png) {% else %} ![A screenshot of using your action in a workflow](/assets/images/help/repository/javascript-action-workflow-run.png) diff --git a/content/actions/guides/about-packaging-with-github-actions.md b/content/actions/guides/about-packaging-with-github-actions.md index 020c8e636f..aba20c17f6 100644 --- a/content/actions/guides/about-packaging-with-github-actions.md +++ b/content/actions/guides/about-packaging-with-github-actions.md @@ -25,7 +25,11 @@ Creating a package at the end of a continuous integration workflow can help duri Now, when reviewing a pull request, you'll be able to look at the workflow run and download the artifact that was produced. +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down-updated.png) +{% else %} ![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png) +{% endif %} This will let you run the code in the pull request on your machine, which can help with debugging or testing the pull request. diff --git a/content/actions/guides/building-and-testing-powershell.md b/content/actions/guides/building-and-testing-powershell.md index ccfa14b990..be50ffc52f 100644 --- a/content/actions/guides/building-and-testing-powershell.md +++ b/content/actions/guides/building-and-testing-powershell.md @@ -60,7 +60,11 @@ jobs: * `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory. * `Should -Be $true` - Uses Pester to define an expected result. If the result is unexpected, then {% data variables.product.prodname_actions %} flags this as a failed test. For example: + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Failed Pester test](/assets/images/help/repository/actions-failed-pester-test-updated.png) + {% else %} ![Failed Pester test](/assets/images/help/repository/actions-failed-pester-test.png) + {% endif %} * `Invoke-Pester Unit.Tests.ps1 -Passthru` - Uses Pester to execute tests defined in a file called `Unit.Tests.ps1`. For example, to perform the same test described above, the `Unit.Tests.ps1` will contain the following: ``` diff --git a/content/actions/guides/storing-workflow-data-as-artifacts.md b/content/actions/guides/storing-workflow-data-as-artifacts.md index 5b8e0e7189..cf0932f879 100644 --- a/content/actions/guides/storing-workflow-data-as-artifacts.md +++ b/content/actions/guides/storing-workflow-data-as-artifacts.md @@ -108,8 +108,6 @@ jobs: path: output/test/code-coverage.html ``` -![Image of workflow upload artifact workflow run](/assets/images/help/repository/upload-build-test-artifact.png) - {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} ### Configuring a custom artifact retention period @@ -238,7 +236,12 @@ jobs: echo The result is $value ``` +The workflow run will archive any artifacts that it generated. For more information on downloading archived artifacts, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)." +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +![Workflow that passes data between jobs to perform math](/assets/images/help/repository/passing-data-between-jobs-in-a-workflow-updated.png) +{% else %} ![Workflow that passes data between jobs to perform math](/assets/images/help/repository/passing-data-between-jobs-in-a-workflow.png) +{% endif %} {% if currentVersion == "free-pro-team@latest" %} diff --git a/content/actions/learn-github-actions/introduction-to-github-actions.md b/content/actions/learn-github-actions/introduction-to-github-actions.md index eecfa6589a..455cac19cf 100644 --- a/content/actions/learn-github-actions/introduction-to-github-actions.md +++ b/content/actions/learn-github-actions/introduction-to-github-actions.md @@ -204,7 +204,7 @@ In this diagram, you can see the workflow file you just created and how the {% d ### Viewing the job's activity -Once your job has started running, you can view each step's activity on {% data variables.product.prodname_dotcom %}. +Once your job has started running, you can {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}see a visualization graph of the run's progress and {% endif %}view each step's activity on {% data variables.product.prodname_dotcom %}. {% data reusables.repositories.navigate-to-repo %} 1. Under your repository name, click **Actions**. @@ -213,7 +213,14 @@ Once your job has started running, you can view each step's activity on {% data ![Screenshot of workflow results](/assets/images/help/images/learn-github-actions-workflow.png) 1. Under "Workflow runs", click the name of the run you want to see. ![Screenshot of workflow runs](/assets/images/help/images/learn-github-actions-run.png) -{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +1. Under **Jobs** or in the visualization graph, click the job you want to see. + ![Select job](/assets/images/help/images/overview-actions-result-navigate.png) +{% endif %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +1. View the results of each step. + ![Screenshot of workflow run details](/assets/images/help/images/overview-actions-result-updated-2.png) +{% elsif currentVersion ver_gt "enterprise-server@2.22" %} 1. Click on the job name to see the results of each step. ![Screenshot of workflow run details](/assets/images/help/images/overview-actions-result-updated.png) {% else %} diff --git a/content/actions/managing-workflow-runs/canceling-a-workflow.md b/content/actions/managing-workflow-runs/canceling-a-workflow.md index 20b9ba1cb4..153659d966 100644 --- a/content/actions/managing-workflow-runs/canceling-a-workflow.md +++ b/content/actions/managing-workflow-runs/canceling-a-workflow.md @@ -17,9 +17,14 @@ versions: {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} +1. From the list of workflow runs, click the name of the `queued` or `in progress` run that you want to cancel. +![Name of workflow run](/assets/images/help/repository/in-progress-run.png) 1. In the upper-right corner of the workflow, click **Cancel workflow**. +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Cancel check suite button](/assets/images/help/repository/cancel-check-suite-updated.png) +{% else %} ![Cancel check suite button](/assets/images/help/repository/cancel-check-suite.png) +{% endif %} ### Steps {% data variables.product.prodname_dotcom %} takes to cancel a workflow run diff --git a/content/actions/managing-workflow-runs/downloading-workflow-artifacts.md b/content/actions/managing-workflow-runs/downloading-workflow-artifacts.md index 22d5651efe..11843c3cec 100644 --- a/content/actions/managing-workflow-runs/downloading-workflow-artifacts.md +++ b/content/actions/managing-workflow-runs/downloading-workflow-artifacts.md @@ -20,4 +20,8 @@ versions: {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. Under **Artifacts**, click the artifact you want to download. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down-updated.png) + {% else %} ![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png) + {% endif %} diff --git a/content/actions/managing-workflow-runs/index.md b/content/actions/managing-workflow-runs/index.md index 5096b761c7..8905d8b087 100644 --- a/content/actions/managing-workflow-runs/index.md +++ b/content/actions/managing-workflow-runs/index.md @@ -18,6 +18,7 @@ versions: {% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-github-hosted-runners %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}{% link_in_list /using-the-visualization-graph %}{% endif %} {% link_in_list /viewing-workflow-run-history %} {% link_in_list /using-workflow-run-logs %} {% link_in_list /manually-running-a-workflow %} diff --git a/content/actions/managing-workflow-runs/re-running-a-workflow.md b/content/actions/managing-workflow-runs/re-running-a-workflow.md index 61590387db..323ebab2d3 100644 --- a/content/actions/managing-workflow-runs/re-running-a-workflow.md +++ b/content/actions/managing-workflow-runs/re-running-a-workflow.md @@ -16,5 +16,4 @@ versions: {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} -1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**. - ![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down.png) +1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down-updated.png){% else %}![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down.png){% endif %} diff --git a/content/actions/managing-workflow-runs/removing-workflow-artifacts.md b/content/actions/managing-workflow-runs/removing-workflow-artifacts.md index 9c7e96fe79..33595a42cf 100644 --- a/content/actions/managing-workflow-runs/removing-workflow-artifacts.md +++ b/content/actions/managing-workflow-runs/removing-workflow-artifacts.md @@ -27,7 +27,11 @@ versions: {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. Under **Artifacts**, click {% octicon "trashcan" aria-label="The trashcan icon" %} next to the artifact you want to remove. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Delete artifact drop-down menu](/assets/images/help/repository/actions-delete-artifact-updated.png) + {% else %} ![Delete artifact drop-down menu](/assets/images/help/repository/actions-delete-artifact.png) + {% endif %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} ### Setting the retention period for an artifact diff --git a/content/actions/managing-workflow-runs/using-the-visualization-graph.md b/content/actions/managing-workflow-runs/using-the-visualization-graph.md new file mode 100644 index 0000000000..2fe6753a30 --- /dev/null +++ b/content/actions/managing-workflow-runs/using-the-visualization-graph.md @@ -0,0 +1,23 @@ +--- +title: Using the visualization graph +intro: Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug workflows. +product: '{% data reusables.gated-features.actions %}' +versions: + free-pro-team: '*' + enterprise-server: '>=3.1' +--- + +{% data reusables.actions.enterprise-beta %} +{% data reusables.actions.visualization-beta %} +{% data reusables.actions.enterprise-github-hosted-runners %} + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.actions-tab %} +{% data reusables.repositories.navigate-to-workflow %} +{% data reusables.repositories.view-run %} + +1. The graph displays each job in the workflow. An icon to the left of the job name indicates the status of the job. Lines between jobs indicate dependencies. + ![Workflow graph](/assets/images/help/images/workflow-graph.png) + +2. Click on a job to view the job log. + ![Workflow graph](/assets/images/help/images/workflow-graph-job.png) diff --git a/content/actions/managing-workflow-runs/using-workflow-run-logs.md b/content/actions/managing-workflow-runs/using-workflow-run-logs.md index 92ad242d9c..9cffb45bc3 100644 --- a/content/actions/managing-workflow-runs/using-workflow-run-logs.md +++ b/content/actions/managing-workflow-runs/using-workflow-run-logs.md @@ -45,7 +45,11 @@ You can search the build logs for a particular step. When you search logs, only {% data reusables.repositories.navigate-to-job-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. In the upper-right corner of the log output, in the **Search logs** search box, type a search query. +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Search box to search logs](/assets/images/help/repository/search-log-box-updated-2.png) +{% else %} ![Search box to search logs](/assets/images/help/repository/search-log-box-updated.png) +{% endif %} {% else %} 1. To expand each step you want to include in your search, click the step. ![Step name](/assets/images/help/repository/failed-check-step.png) @@ -63,8 +67,12 @@ You can download the log files from your workflow run. You can also download a w {% data reusables.repositories.view-run-superlinter %} {% data reusables.repositories.navigate-to-job-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} -1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**. +1. In the upper right corner, click {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}{% octicon "gear" aria-label="The gear icon" %}{% else %}{% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}{% endif %} and select **Download log archive**. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Download logs drop-down menu](/assets/images/help/repository/download-logs-drop-down-updated-2.png) + {% else %} ![Download logs drop-down menu](/assets/images/help/repository/download-logs-drop-down-updated.png) + {% endif %} {% else %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**. ![Download logs drop-down menu](/assets/images/help/repository/download-logs-drop-down.png) @@ -80,9 +88,17 @@ You can delete the log files from your workflow run. {% data reusables.repositor {% data reusables.repositories.view-run-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Kebab-horizontal icon](/assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated-2.png) + {% else %} ![Kebab-horizontal icon](/assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated.png) + {% endif %} 2. To delete the log files, click the **Delete all logs** button and review the confirmation prompt. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Delete all logs](/assets/images/help/repository/delete-all-logs-updated-2.png) + {% else %} ![Delete all logs](/assets/images/help/repository/delete-all-logs-updated.png) + {% endif %} After deleting logs, the **Delete all logs** button is removed to indicate that no log files remain in the workflow run. {% else %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}. diff --git a/content/actions/managing-workflow-runs/viewing-job-execution-time.md b/content/actions/managing-workflow-runs/viewing-job-execution-time.md index 5b4d222793..e1b7bd9ac0 100644 --- a/content/actions/managing-workflow-runs/viewing-job-execution-time.md +++ b/content/actions/managing-workflow-runs/viewing-job-execution-time.md @@ -15,7 +15,7 @@ Billable job execution minutes are only shown for jobs run on private repositori {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} -1. Under the job summary, you can view the job's execution time. To view the billable job execution time, click **Run and billable time details**. +1. Under the job summary, you can view the job's execution time. To view details about the billable job execution time, click the time under **Billable time**. ![Run and billable time details link](/assets/images/help/repository/view-run-billable-time.png) {% note %} diff --git a/content/actions/quickstart.md b/content/actions/quickstart.md index 77e8752480..812f317f03 100644 --- a/content/actions/quickstart.md +++ b/content/actions/quickstart.md @@ -60,8 +60,13 @@ Committing the workflow file in your repository triggers the `push` event and ru {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow-superlinter %} {% data reusables.repositories.view-run-superlinter %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +1. Under **Jobs** or in the visualization graph, click the **Lint code base** job. + ![Lint code base job](/assets/images/help/repository/superlinter-lint-code-base-job-updated.png) +{% else %} 1. In the left sidebar, click the **Lint code base** job. ![Lint code base job](/assets/images/help/repository/superlinter-lint-code-base-job.png) +{% endif %} {% data reusables.repositories.view-failed-job-results-superlinter %} ### More starter workflows diff --git a/content/developers/github-marketplace/about-github-marketplace.md b/content/developers/github-marketplace/about-github-marketplace.md index 55cab928e0..221d2e6447 100644 --- a/content/developers/github-marketplace/about-github-marketplace.md +++ b/content/developers/github-marketplace/about-github-marketplace.md @@ -1,6 +1,6 @@ --- title: About GitHub Marketplace -intro: 'Learn the basics to prepare your app for review before joining {% data variables.product.prodname_marketplace %}.' +intro: 'Learn about {% data variables.product.prodname_marketplace %} where you can share your apps and actions publicly with all {% data variables.product.product_name %} users.' redirect_from: - /apps/marketplace/getting-started/ - /marketplace/getting-started @@ -14,52 +14,41 @@ versions: {% data reusables.actions.actions-not-verified %} -To learn about publishing {% data variables.product.prodname_actions %} in the {% data variables.product.prodname_marketplace %}, see "[Publishing actions in GitHub Marketplace](/actions/creating-actions/publishing-actions-in-github-marketplace)." +To learn about publishing {% data variables.product.prodname_actions %} in {% data variables.product.prodname_marketplace %}, see "[Publishing actions in GitHub Marketplace](/actions/creating-actions/publishing-actions-in-github-marketplace)." ### Apps -You can list verified and unverified apps in {% data variables.product.prodname_marketplace %}. Unverified apps do not go through the security, testing, and verification cycle {% data variables.product.prodname_dotcom %} requires for verified apps. +Anyone can share their apps with other users on {% data variables.product.prodname_marketplace %} but only listings that are verified by {% data variables.product.company_short %} can include paid plans. For more information, see "[About verified creators](/developers/github-marketplace/about-verified-creators)." -Verified apps have a green badge in {% data variables.product.prodname_marketplace %}. Unverified apps have a grey badge next to their listing and are only available as free apps. +If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_app %}s, see "[Building {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps)" or "[Building {% data variables.product.prodname_oauth_app %}s](/developers/apps/building-oauth-apps)." -![Green verified and grey unverified badge](/assets/images/marketplace/marketplace_verified_badges.png) - -If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_app %}s, see "[Building apps](/apps/)." - -{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_app %}s in {% data variables.product.prodname_marketplace %}. See "[Differences between GitHub and OAuth apps](/apps/differences-between-apps/)" for more details. To learn more about switching from OAuth to {% data variables.product.prodname_github_apps %}, see [Migrating OAuth Apps to {% data variables.product.prodname_github_app %}s](/apps/migrating-oauth-apps-to-github-apps/). +{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_app %}s in {% data variables.product.prodname_marketplace %}. For more information, see "[Differences between {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/)" and "[Migrating {% data variables.product.prodname_oauth_app %}s to {% data variables.product.prodname_github_apps %}](/apps/migrating-oauth-apps-to-github-apps/)." If you have questions about {% data variables.product.prodname_marketplace %}, please contact {% data variables.contact.contact_support %} directly. -#### Unverified Apps +### Publishing an app to {% data variables.product.prodname_marketplace %} -Unverified apps do not need to meet the "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)" or go through the "[Security review process](/marketplace/getting-started/security-review-process/)". +When you have finished creating your app, you can share it with other users by publishing it to {% data variables.product.prodname_marketplace %}. In summary, the process is: -{% data reusables.marketplace.unverified-apps %} Having a published paid plan will prevent you from being able to submit an unverified app. You must remove paid plans or keep them in draft mode before publishing an unverified app. +1. Review your app carefully to ensure that it will behave as expected in other repositories and that it follows best practice guidelines. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)" and "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app#best-practice-for-customer-experience)." -To list your unverified app in {% data variables.product.prodname_marketplace %}, you only need to create a "[Listing on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/)" and submit it as an unverified listing. +1. Add webhook events to the app to track user billing requests. For more information about the {% data variables.product.prodname_marketplace %} API, webhook events, and billing requests, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -{% data reusables.marketplace.launch-with-free %} +1. Create a draft {% data variables.product.prodname_marketplace %} listing. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)." -#### Verified Apps +1. Add a pricing plan. For more information, see "[Setting pricing plans for your listing](/developers/github-marketplace/setting-pricing-plans-for-your-listing)." -If you've already built an app and you're interested in submitting a verified listing in {% data variables.product.prodname_marketplace %}, start here: +1. Check whether your app meets the requirements for listing on {% data variables.product.prodname_marketplace %} as a free or a paid app. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." -1. [Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)
Learn about requirements, guidelines, and the app submission process. +1. Read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." -1. [Integrating with the {% data variables.product.prodname_marketplace %} API](/marketplace/integrating-with-the-github-marketplace-api/)
Before you can list your app on {% data variables.product.prodname_marketplace %}, you'll need to integrate billing flows using the {% data variables.product.prodname_marketplace %} API and webhook events. +1. Submit your listing for publication in {% data variables.product.prodname_marketplace %}, requesting verification if you want to sell the app. For more information, see "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication)." -1. [Listing on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/)
Create a draft {% data variables.product.prodname_marketplace %} listing, configure webhook settings, and set up pricing plans. +An onboarding expert will contact you with any questions or further steps. For example, if you have added a paid plan, you will need to complete the verification process and complete financial onboarding. As soon as your listing is approved the app is published to {% data variables.product.prodname_marketplace %}. -1. [Selling your app](/marketplace/selling-your-app/)
Learn about pricing plans, billing cycles, and how to receive payment from {% data variables.product.prodname_dotcom %} for your app. +### Seeing how your app is performing -1. [{% data variables.product.prodname_marketplace %} Insights](/marketplace/github-marketplace-insights/)
See how your app is performing in {% data variables.product.prodname_marketplace %}. You can use metrics collected by {% data variables.product.prodname_dotcom %} to guide your marketing campaign and be successful in {% data variables.product.prodname_marketplace %}. +You can access metrics and transactions for your listing. For more information, see: -1. [{% data variables.product.prodname_marketplace %} transactions](/marketplace/github-marketplace-transactions/)
Download and view transaction data for your {% data variables.product.prodname_marketplace %} listing. - -### Reviewing your app - -We want to make sure that the apps offered on {% data variables.product.prodname_marketplace %} are safe, secure, and well tested. The {% data variables.product.prodname_marketplace %} onboarding specialists will review your app to ensure that it meets all requirements. Follow the guidelines in these articles before submitting your app: - - -* [Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/) -* [Security review process](/marketplace/getting-started/security-review-process/) +- "[Viewing metrics for your listing](/developers/github-marketplace/viewing-metrics-for-your-listing)" +- "[Viewing transactions for your listing](/developers/github-marketplace/viewing-transactions-for-your-listing)" diff --git a/content/developers/github-marketplace/about-verified-creators.md b/content/developers/github-marketplace/about-verified-creators.md new file mode 100644 index 0000000000..a3c0eeb880 --- /dev/null +++ b/content/developers/github-marketplace/about-verified-creators.md @@ -0,0 +1,43 @@ +--- +title: About verified creators +intro: 'Each organization that wants to sell apps on {% data variables.product.prodname_marketplace %} must follow a verification process. Their identity is checked and their billing process reviewed.' +versions: + free-pro-team: '*' +--- + +### About verified creators + +A verified creator is an organization that {% data variables.product.company_short %} has checked. Anyone can share their apps with other users on {% data variables.product.prodname_marketplace %} but only organizations that are verified by {% data variables.product.company_short %} can sell apps. For more information about organizations, see "[About organizations](/github/setting-up-and-managing-organizations-and-teams/about-organizations)." + +The verification process aims to protect users. For example, it verifies the seller's identity, checks that their {% data variables.product.product_name %} organization is set up securely, and that they can be contacted for support. + +After passing the verification checks, any apps that the organization lists on {% data variables.product.prodname_marketplace %} are shown with a verified creator badge {% octicon "verified" aria-label="Verified creator badge" %}. The organization can now add paid plans to any of their apps. Each app with a paid plan also goes through a financial onboarding process to check that it's set up to handle billing correctly. + +![verified creator badges](/assets/images/marketplace/marketplace_verified_creator_badges_apps.png) + +In addition to the verified creator badge, you'll also see badges for unverified and verified apps. These apps were published using the old method for verifying individual apps. + +![Green verified and grey unverified badge](/assets/images/marketplace/marketplace_verified_badges.png) + +For information on finding apps to use, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)." + +### About the verification process + +The first time you request verification for a listing of one of your apps, you will enter the verification process. An onboarding expert will guide you through the process. This includes checking: + +- Profile information - The basic profile information is populated accurately and appropriately. +- Security - The organization has enabled two-factor authentication. +- Verified domain - The organization has verified the domain of the site URL. +- Purchase webhook event - The event is handled correctly by the app. + +When your organization is verified, all your apps are shown with a verified creator badge. You are now able to offer paid plans for any of your apps. + +For more information about the requirements for listing an app on {% data variables.product.prodname_marketplace %}, see "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." + +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." + +{% note %} + +**Note:** This verification process for apps replaces the previous process where individual apps were verified. The current process is similar to the verification process for actions. If you have apps that were verified under the old process, these will not be affected by the changes. The {% data variables.product.prodname_marketplace %} team will contact you with details of how to migrate to organization-based verification. + +{% endnote %} diff --git a/content/developers/github-marketplace/billing-customers.md b/content/developers/github-marketplace/billing-customers.md index 940892862b..ed6701d671 100644 --- a/content/developers/github-marketplace/billing-customers.md +++ b/content/developers/github-marketplace/billing-customers.md @@ -13,17 +13,17 @@ versions: ### Understanding the billing cycle -Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)." +Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[Webhook events for the {% data variables.product.prodname_marketplace %} API](/developers/github-marketplace/webhook-events-for-the-github-marketplace-api)." ### Providing billing services in your app's UI -Customers must be able to perform the following actions from your app's website: -- Customers must be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. +Customers should be able to perform the following actions from your app's website: +- Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. {% data reusables.marketplace.marketplace-billing-ui-requirements %} ### Billing services for upgrades, downgrades, and cancellations -Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)." +Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan). @@ -33,7 +33,7 @@ When a customer upgrades their pricing plan or changes their billing cycle from {% data reusables.marketplace.marketplace-failed-purchase-event %} -For information about building upgrade and downgrade workflows into your app, see "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)." +For information about building upgrade and downgrade workflows into your app, see "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)." #### Downgrades and cancellations @@ -45,4 +45,4 @@ When a customer cancels a plan, you must: {% data reusables.marketplace.cancellation-clarification %} - Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time. -For information about building cancellation workflows into your app, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." +For information about building cancellation workflows into your app, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." diff --git a/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md b/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md new file mode 100644 index 0000000000..4107fa4427 --- /dev/null +++ b/content/developers/github-marketplace/customer-experience-best-practices-for-apps.md @@ -0,0 +1,20 @@ +--- +title: Customer experience best practices for apps +intro: 'Guidelines for creating an app that will be easy to use and understand.' +shortTitle: Customer experience best practice +versions: + free-pro-team: '*' +--- + +If you follow these best practices it will help you to provide a good customer experience. + +### Customer communication + +- Marketing materials for the app should accurately represent the app's behavior. +- Apps should include links to user-facing documentation that describe how to set up and use the app. +- Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app. +- Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately. + +### Plan management + +{% data reusables.marketplace.marketplace-billing-ui-requirements %} diff --git a/content/developers/github-marketplace/drafting-a-listing-for-your-app.md b/content/developers/github-marketplace/drafting-a-listing-for-your-app.md index 2f3be55bcf..11247e591d 100644 --- a/content/developers/github-marketplace/drafting-a-listing-for-your-app.md +++ b/content/developers/github-marketplace/drafting-a-listing-for-your-app.md @@ -59,8 +59,8 @@ Once you've created a {% data variables.product.prodname_marketplace %} draft li ### Submitting your app -Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, the {% data variables.product.prodname_marketplace %} onboarding team will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." +Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, an onboarding expert will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." ### Removing a {% data variables.product.prodname_marketplace %} listing -If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact [marketplace@github.com](mailto:marketplace@github.com) to remove your listing. +If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact {% data variables.contact.contact_support %} to remove your listing. diff --git a/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md b/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md index 962262a477..0c67eec856 100644 --- a/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md +++ b/content/developers/github-marketplace/handling-new-purchases-and-free-trials.md @@ -28,7 +28,7 @@ GitHub then sends the [`marketplace_purchase`](/webhooks/event-payloads/#marketp Read the `effective_date` and `marketplace_purchase` object from the `marketplace_purchase` webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins. -If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." See "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)" to find out how to transition a free trial to a paid plan when a free trial expires. +If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." See "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)" to find out how to transition a free trial to a paid plan when a free trial expires. See "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" for an example of the `marketplace_purchase` event payload. diff --git a/content/developers/github-marketplace/index.md b/content/developers/github-marketplace/index.md index 34b9741c61..0881424066 100644 --- a/content/developers/github-marketplace/index.md +++ b/content/developers/github-marketplace/index.md @@ -11,8 +11,10 @@ versions: {% topic_link_in_list /creating-apps-for-github-marketplace %} {% link_in_list /about-github-marketplace %} + {% link_in_list /about-verified-creators %} {% link_in_list /requirements-for-listing-an-app %} - {% link_in_list /security-review-process-for-submitted-apps %} + {% link_in_list /security-best-practices-for-apps %} + {% link_in_list /customer-experience-best-practices-for-apps %} {% link_in_list /viewing-metrics-for-your-listing %} {% link_in_list /viewing-transactions-for-your-listing %} {% topic_link_in_list /using-the-github-marketplace-api-in-your-app %} @@ -27,7 +29,7 @@ versions: {% link_in_list /writing-a-listing-description-for-your-app %} {% link_in_list /setting-pricing-plans-for-your-listing %} {% link_in_list /configuring-a-webhook-to-notify-you-of-plan-changes %} - {% link_in_list /submitting-your-listing-for-review %} + {% link_in_list /submitting-your-listing-for-publication %} {% topic_link_in_list /selling-your-app-on-github-marketplace %} {% link_in_list /pricing-plans-for-github-marketplace-apps %} {% link_in_list /billing-customers %} diff --git a/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md b/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md index bb33fe004f..aa9d924b49 100644 --- a/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md +++ b/content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md @@ -10,35 +10,45 @@ versions: -{% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit, and GitHub lists the price in US dollars. Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave GitHub.com. You don't have to write code to perform billing transactions, but you will have to handle [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) for purchase events. +{% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit. Prices are set, displayed, and processed in US dollars. Paid plans are restricted to verified listings. + +Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave {% data variables.product.prodname_dotcom_the_website %}. You don't have to write code to perform billing transactions, but you will have to handle events from the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." If the app you're listing on {% data variables.product.prodname_marketplace %} has multiple plan options, you can set up corresponding pricing plans. For example, if your app has two plan options, an open source plan and a pro plan, you can set up a free pricing plan for your open source plan and a flat pricing plan for your pro plan. Each {% data variables.product.prodname_marketplace %} listing must have an annual and a monthly price for every plan that's listed. For more information on how to create a pricing plan, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." -{% note %} - -**Note:** If you're listing an app on {% data variables.product.prodname_marketplace %}, you can't list your app with a free pricing plan if you offer a paid service outside of {% data variables.product.prodname_marketplace %}. - -{% endnote %} +{% data reusables.marketplace.free-plan-note %} ### Types of pricing plans -**Free pricing plans** are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. Unverified free apps do not need to implement any billing flows. Free apps that are verified by Github need to implement billing flows for new purchases and cancellations, but do not need to implement billing flows for free trials, upgrades, and downgrades. If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to resubmit the app for review. +#### Free pricing plans -**Flat rate pricing plans** charge a set fee on a monthly and yearly basis. +{% data reusables.marketplace.free-apps-encouraged %} -**Per-unit pricing plans** charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). +Free plans are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. -**Marketplace free trials** provide 14-day free trials of OAuth or GitHub Apps to customers. When you [set up a Marketplace pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/), you can select the option to provide a free trial for flat-rate or per-unit pricing plans. +All apps need to handle events for new purchases and cancellations. Apps that only have free plans do not need to handle events for free trials, upgrades, and downgrades. For more information, see: "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." + +If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to request verification for the app and go through financial onboarding. + +#### Paid pricing plans + +There are two types of paid pricing plan: + +- Flat rate pricing plans charge a set fee on a monthly and yearly basis. + +- Per-unit pricing plans charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). + +You may also want to offer free trials. These provide free, 14-day trials of OAuth or GitHub Apps to customers. When you set up a Marketplace pricing plan, you can select the option to provide a free trial for flat-rate or per-unit pricing plans. ### Free trials -Customers can start a free trial for any available paid plan on a Marketplace listing, but will not be able to create more than one free trial for a Marketplace product. +Customers can start a free trial for any paid plan on a Marketplace listing that includes free trials. However, customers cannot create more than one free trial per marketplace product. Free trials have a fixed length of 14 days. Customers are notified 4 days before the end of their trial period (on day 11 of the free trial) that their plan will be upgraded. At the end of a free trial, customers will be auto-enrolled into the plan they are trialing if they do not cancel. -See "[New purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)" for details on how to handle free trials in your app. +For more information, see: "[Handling new purchases and free trials](/developers/github-marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)." {% note %} diff --git a/content/developers/github-marketplace/requirements-for-listing-an-app.md b/content/developers/github-marketplace/requirements-for-listing-an-app.md index ead5d811bb..e54424b74a 100644 --- a/content/developers/github-marketplace/requirements-for-listing-an-app.md +++ b/content/developers/github-marketplace/requirements-for-listing-an-app.md @@ -1,6 +1,6 @@ --- title: Requirements for listing an app -intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before our {% data variables.product.prodname_marketplace %} onboarding specialists will approve the listing.' +intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before the listing can be published.' redirect_from: - /apps/adding-integrations/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ - /apps/marketplace/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ @@ -12,49 +12,62 @@ versions: free-pro-team: '*' --- + +The requirements for listing an app on {% data variables.product.prodname_marketplace %} vary according to whether you want to offer a free or a paid app. -Before you submit your app for review, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." You'll accept the terms within your [draft listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) on {% data variables.product.product_name %}. Once you've submitted your app, one of the {% data variables.product.prodname_marketplace %} onboarding specialists will reach out to you with more information about the onboarding process, and review your app to ensure it meets these requirements: +### Requirements for all {% data variables.product.prodname_marketplace %} listings -### User experience +All listings on {% data variables.product.prodname_marketplace %} should be for tools that provide value to the {% data variables.product.product_name %} community. When you submit your listing for publication, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." -- {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. -- {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. +#### User experience requirements for all apps + +All listings should meet the following requirements, regardless of whether they are for a free or paid app. + +- Listings must not actively persuade users away from {% data variables.product.product_name %}. +- Listings must include valid contact information for the publisher. +- Listings must have a relevant description of the application. +- Listings must specify a pricing plan. - Apps must provide value to customers and integrate with the platform in some way beyond authentication. - Apps must be publicly available in {% data variables.product.prodname_marketplace %} and cannot be in beta or available by invite only. -- Apps cannot actively persuade users away from {% data variables.product.product_name %}. -- Marketing materials for the app must accurately represent the app's behavior. -- Apps must include links to user-facing documentation that describe how to set up and use the app. -- When a customer purchases an app and GitHub redirects them to the app's installation URL, the app must begin the OAuth flow immediately. For details, see "[Handling new purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/#step-3-authorization)." +- Apps must have webhook events set up to notify the publisher of any plan changes or cancellations using the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -- Customers must be able to install your app and select repositories on both a personal and organization account. They should be able to view and manage those accounts separately. +For more information on providing a good customer experience, see "[Customer experience best practices for apps](/developers/github-marketplace/customer-experience-best-practices-for-apps)." -### Brand and listing +#### Brand and listing requirements for all apps -- Apps that use GitHub logos must follow the "[{% data variables.product.product_name %} Logos and Usage](https://github.com/logos)" guidelines. +- Apps that use GitHub logos must follow the {% data variables.product.company_short %} guidelines. For more information, see "[{% data variables.product.company_short %} Logos and Usage](https://github.com/logos)." - Apps must have a logo, feature card, and screenshots images that meet the recommendations provided in "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." - Listings must include descriptions that are well written and free of grammatical errors. For guidance in writing your listing, see "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." -### Security +To protect your customers, we recommend that you also follow security best practices. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)." -Apps will go through a security review before being listed on {% data variables.product.prodname_marketplace %}. A successful review will meet the requirements and follow the security best practices listed in "[Security review process](/marketplace/getting-started/security-review-process/)." For information on the review process, contact [marketplace@github.com](mailto:marketplace@github.com). +### Considerations for free apps -### Billing flows +{% data reusables.marketplace.free-apps-encouraged %} -Your app must integrate [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) using the [{% data variables.product.prodname_marketplace %} webhook event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/). +### Requirements for paid apps -#### Free apps +In addition to the requirements for all apps above, each app that you offer as a paid service on {% data variables.product.prodname_marketplace %} must also meet the following requirements: -{% data reusables.marketplace.free-apps-encouraged %} If you are listing a free app, you'll need to meet these requirements: +- {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. +- {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. +- All paid apps must handle {% data variables.product.prodname_marketplace %} purchase events for new purchases, upgrades, downgrades, cancellations, and free trials. For more information, see "[Billing requirements for paid apps](#billing-requirements-for-paid-apps)" below. +- Publishing organizations must have a verified domain and must enable two-factor authentication. For more information, see "[Requiring two-factor authentication in your organization](/github/setting-up-and-managing-organizations-and-teams/requiring-two-factor-authentication-in-your-organization.") -- Customers must be able to see that they have a free plan in the billing, profile, or account settings section of the app. -- When a customer cancels your app, you must follow the flow for [cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/). +When you are ready to publish the app on {% data variables.product.prodname_marketplace %} you must request verification for the listing. -#### Paid apps +{% note %} -To offer your app as a paid service, you'll need to meet these requirements to list your app on {% data variables.product.prodname_marketplace %}: +The verification process is open to organizations. {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." + +{% endnote %} + +### Billing requirements for paid apps + +Your app does not need to handle payments but does need to use {% data variables.product.prodname_marketplace %} purchase events to manage new purchases, upgrades, downgrades, cancellations, and free trials. For information about how integrate these events into your app, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." + +Using GitHub's billing API allows customers to purchase an app without leaving GitHub and to pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. -- To sell your app in {% data variables.product.prodname_marketplace %}, it must use GitHub's billing system. Your app does not need to handle payments but does need to use "[{% data variables.product.prodname_marketplace %} purchase events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" to manage new purchases, upgrades, downgrades, cancellations, and free trials. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" to learn about how to integrate these events into your app. Using GitHub's billing system allows customers to purchase an app without leaving GitHub and pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. - Apps must support both monthly and annual billing for paid subscriptions purchases. - Listings may offer any combination of free and paid plans. Free plans are optional but encouraged. For more information, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." -{% data reusables.marketplace.marketplace-billing-ui-requirements %} diff --git a/content/developers/github-marketplace/security-best-practices-for-apps.md b/content/developers/github-marketplace/security-best-practices-for-apps.md new file mode 100644 index 0000000000..fac3d2fcf6 --- /dev/null +++ b/content/developers/github-marketplace/security-best-practices-for-apps.md @@ -0,0 +1,60 @@ +--- +title: Security best practices for apps +intro: 'Guidelines for preparing a secure app to share on {% data variables.product.prodname_marketplace %}.' +redirect_from: + - /apps/marketplace/getting-started/security-review-process/ + - /marketplace/getting-started/security-review-process + - /developers/github-marketplace/security-review-process-for-submitted-apps +shortTitle: Security best practice +versions: + free-pro-team: '*' +--- + +If you follow these best practices it will help you to provide a secure user experience. + +### Authorization, authentication, and access control + +We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details. +- Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia. +- Apps should provide customers with a way to delete their account, without having to email or call a support person. +- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. +- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. +- Apps should not share service accounts such as email or database services to manage your SaaS service. +- All services used in your app should have unique login and password credentials. +- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. +- Apps should not use personal access tokens to authenticate and should authenticate as an [OAuth App](/apps/about-apps/#about-oauth-apps) or a [GitHub App](/apps/about-apps/#about-github-apps): + - OAuth Apps should authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/). + - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). + +### Data protection + +- Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. +- Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). +- Apps should delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. +- Apps should not require the user to provide their GitHub password. +- Apps should encrypt tokens, client IDs, and client secrets. + +### Logging and monitoring + +Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year. +A security log should include: + +- Authentication and authorization events +- Service configuration changes +- Object reads and writes +- All user and group permission changes +- Elevation of role to admin +- Consistent timestamping for each event +- Source users, IP addresses, and/or hostnames for all logged actions + +### Incident response workflow + +To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident. + +For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template. + +### Vulnerability management and patching workflow + +You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. + +If you are not ready to set up a full vulnerability management program, it's useful to start by creating a patching process. For guidance in creating a patch management policy, see this TechRepublic article "[Establish a patch management policy](https://www.techrepublic.com/blog/it-security/establish-a-patch-management-policy-87756/)." diff --git a/content/developers/github-marketplace/security-review-process-for-submitted-apps.md b/content/developers/github-marketplace/security-review-process-for-submitted-apps.md deleted file mode 100644 index d1dc369fee..0000000000 --- a/content/developers/github-marketplace/security-review-process-for-submitted-apps.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Security review process for submitted apps -intro: 'GitHub''s security team reviews all apps submitted to {% data variables.product.prodname_marketplace %} to ensure that they meet security requirements. Follow these best practices to be prepared for the review process.' -redirect_from: - - /apps/marketplace/getting-started/security-review-process/ - - /marketplace/getting-started/security-review-process -versions: - free-pro-team: '*' ---- - - - -After you've submitted your app for approval, the GitHub security team will request that you complete a security questionnaire about your app and overall security program. As part of the review, you will have the option to provide documentation to support your responses. You must submit two required documents before your app will be approved for {% data variables.product.prodname_marketplace %}: an [incident response plan](#incident-response-plan) and [vulnerability management workflow](#vulnerability-management-workflow). - - -### Security best practices - -Follow these best practices to have a successful security review and provide a secure user experience. - -#### Authorization, authentication, and access control - -We recommend submitting a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details. -- Apps must use the "[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)" and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. -- Apps must provide customers with a way to delete their account, without having to email or call a support person. -- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. -- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. -- Your app should not share service accounts such as email or database services to manage your SaaS service. -- All services used in your app should have unique login and password credentials. -- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. -- Apps cannot use personal access tokens to authenticate and must authenticate as an [OAuth App](/apps/about-apps/#about-oauth-apps) or [GitHub App](/apps/about-apps/#about-github-apps): - - OAuth Apps must authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/). - - GitHub Apps must authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). - -#### Data protection - -- Apps must encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. -- Apps must store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). -- Apps must delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. -- Apps cannot require the user to provide their GitHub password. -- Apps should encrypt tokens, client IDs, and client secrets. - -#### Logging and monitoring - -- Apps must have logging and monitoring capabilities. App logs must be retained for at least 30 days and archived for at least one year. -A security log should include: - - Authentication and authorization events - - Service configuration changes - - Object reads and writes - - All user and group permission changes - - Elevation of role to admin - - Consistent timestamping for each event - - Source users, IP addresses, and/or hostnames for all logged actions - -#### Incident response workflow - -- To partner with GitHub, you are required to have an [incident response plan](#incident-response-plan) in place before submitting your {% data variables.product.prodname_marketplace %} app listing. -- We recommend having a security and operations incident response team in your company rather than using a third-party vendor. -- You should have the capability to notify GitHub within 24 hours of a confirmed incident. -- You should familiarize yourself with sections 3.7.5 - 3.7.5.6 of the [{% data variables.product.prodname_marketplace %} Developer Agreement](/github/site-policy/github-marketplace-developer-agreement#3-restrictions-and-responsibilities), which include additional details on incident response workflow requirements. - -#### Vulnerability management and patching workflow - -- You should conduct regular vulnerability scans of production infrastructure. -- You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. -- You should familiarize yourself with section 3.7.3 of the [{% data variables.product.prodname_marketplace %} Developer Agreement](/github/site-policy/github-marketplace-developer-agreement#3-restrictions-and-responsibilities), which includes additional details on vulnerability management and patching workflows requirements. - -### Security program documentation - -During the Marketplace security review, you will be asked to submit your incident response plan and vulnerability management workflow. Each document must include a company-branded statement signed by management with a date stamp. - -#### Incident response plan -Your incident response plan documentation must include the current process that your company follows, who is accountable, and the person to contact or expect contact from if an incident occurs. The "[NIST Computer Security Incident Handling Guide](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-61r2.pdf)" is a great example of a document that covers incident response in general. Section 2.3 "Incident Response Policy, Plan, and Procedure Creation" specifically covers the policy. Another great example is the "[SANS Data Breach Response Policy](https://www.sans.org/security-resources/policies/general/pdf/data-breach-response)." - -#### Vulnerability management workflow -Your vulnerability management workflow documentation must include the current process that your company follows for vulnerability management and the patching process used. If you don't have a full vulnerability management program, it might help to start by creating a patching process. For guidance in creating a patch management policy, read the article "[Establish a patch management policy](https://www.techrepublic.com/blog/it-security/establish-a-patch-management-policy-87756/)." - -{% note %} - -**Note:** The incident response and vulnerability management workflow documents aren't expected to be massive formal policy or program documents. A page or two about what you do is more valuable than a lengthy policy template. - -{% endnote %} - -#### GitHub Marketplace security program questionnaire - -During the app submission process, our {% data variables.product.prodname_marketplace %} onboarding team will also send you a questionnaire requesting information about your security practices. This document will serve as a written record attesting: - -- The authentication method and scopes required by your app. -- That you're not requesting more scopes or {% data variables.product.product_name %} access than is needed for the app to perform its intended functionality, taking OAuth limitations and use of {% data variables.product.prodname_github_app %}s into account. -- The use of any third-party services or infrastructure, such as SaaS, PaaS, or IaaS. -- An incident response procedure exists. -- Your app's method of key/token handling. -- That a responsible disclosure policy and process in place or plans to implement one within six months. -- Your vulnerability management workflow or program. -- That you have logging and monitoring capabilities. You must also provide evidence that any relevant app logs are retained for at least 30 days and archived for at least one year. diff --git a/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md b/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md index 205978a5f6..9ab919817d 100644 --- a/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md +++ b/content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md @@ -1,6 +1,6 @@ --- title: Setting pricing plans for your listing -intro: 'When [listing your app on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/), you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' +intro: 'When you list your app on {% data variables.product.prodname_marketplace %}, you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' redirect_from: - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ @@ -17,57 +17,52 @@ versions: free-pro-team: '*' --- +### About setting pricing plans +If you want to sell an app on {% data variables.product.prodname_marketplace %}, you need to request verification when you publish the listing for your app. During the verification process, an onboarding expert checks the organization's identity and security settings. The onboarding expert will also take the organization through financial onboarding. For more information, see: "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." + +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." + +{% data variables.product.prodname_marketplace %} offers several different types of pricing plan. For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)." + +### About saving pricing plans + +You can save pricing plans in a draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published plan will function in the same way as a draft plan until your listing is approved and shown on {% data variables.product.prodname_marketplace %}. Draft plans allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish a pricing plan on a published listing, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. + +For guidelines on billing customers, see "[Billing customers](/developers/github-marketplace/billing-customers)." ### Creating pricing plans -To learn about the types of pricing plans that {% data variables.product.prodname_marketplace %} offers, see "[{% data variables.product.prodname_marketplace %} Pricing Plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." You'll also find helpful billing guidelines in "[Selling your app](/marketplace/selling-your-app/)." - -Pricing plans can be in the draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published listing will function the same way as draft listings until your app is approved and listed on {% data variables.product.prodname_marketplace %}. Draft listings allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish the pricing plan, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. - -To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). If you haven't created a {% data variables.product.prodname_marketplace %} listing yet, read "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)" to learn how. +To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). For more information, see "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)." When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: -#### Plan name +- **Plan name** - Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align with the plan's resources, the size of the company that will use the plan, or anything you'd like. -Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align to the plan's resources, the size of the company that will use the plan, or anything you'd like. +- **Pricing models** - There are three types of pricing plan: free, flat-rate, and per-unit. All plans require you to process new purchase and cancellation events from the marketplace API. In addition, for paid plans: -#### Pricing models + - You must set a price for both monthly and yearly subscriptions in US dollars. + - Your app must process plan change events. + - You must request verification to publish a listing with a paid plan. + - {% data reusables.marketplace.marketplace-pricing-free-trials %} -##### Free plans + For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %} apps](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." -{% data reusables.marketplace.free-apps-encouraged %} A free plan still requires you to handle [new purchase](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/) and [cancellation](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/) billing flows. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" for more details. +- **Available for** - {% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. -##### Flat-rate plans +- **Short description** - Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. -Flat-rate pricing plans allow you to offer your service to customers for a flat-rate fee. {% data reusables.marketplace.marketplace-pricing-free-trials %} +- **Bullets** - You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. -You must set a price for both monthly and yearly subscriptions in U.S. Dollars for flat-rate plans. - -##### Per-unit plans - -Per-unit pricing allows you to offer your app in units. For example, a unit can be a person, seat, or user. You'll need to provide a name for the unit and set a price for both monthly and yearly subscriptions, in U.S. Dollars. - -#### Available for - -{% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. - -#### Short description - -Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. - -#### Bullets - -You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. +{% data reusables.marketplace.free-plan-note %} ### Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan -If a pricing plan for your {% data variables.product.prodname_marketplace %} plan is no longer needed or if you need to adjust pricing details, you can remove it. +If a pricing plan for your {% data variables.product.prodname_marketplace %} listing is no longer needed, or if you need to adjust pricing details, you can remove it. ![Button to remove your pricing plan](/assets/images/marketplace/marketplace_remove_this_plan.png) -Once you publish a pricing plan for an app already listed in the {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." +Once you publish a pricing plan for an app that is already listed in {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan and create a new plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." Once you remove a pricing plan, users won't be able to purchase your app using that plan. Existing users on the removed pricing plan will continue to stay on the plan until they cancel their plan subscription. diff --git a/content/developers/github-marketplace/submitting-your-listing-for-publication.md b/content/developers/github-marketplace/submitting-your-listing-for-publication.md new file mode 100644 index 0000000000..b25c4580ae --- /dev/null +++ b/content/developers/github-marketplace/submitting-your-listing-for-publication.md @@ -0,0 +1,37 @@ +--- +title: Submitting your listing for publication +intro: 'You can submit your listing for the {% data variables.product.prodname_dotcom %} community to use.' +redirect_from: + - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review + - /developers/github-marketplace/submitting-your-listing-for-review +versions: + free-pro-team: '*' +--- + + + +Once you've completed the listing for your app, you'll see two buttons that allow you to request publication of the listing with or without verification. The **Request** button for "Publish without verification" is disabled if you have published any paid pricing plans in the listing. + +![Unverified and verified request button](/assets/images/marketplace/marketplace-request-button.png) + +{% data reusables.marketplace.launch-with-free %} + +After you submit your listing for review, an onboarding expert will reach out to you with additional information. + +For an overview of the process for creating and submitting a listing, see "[About {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/about-github-marketplace#publishing-an-app-to-github-marketplace)." + +### Prerequisites for publishing with verification + +Before you request verification of your listing, you'll need to integrate the {% data variables.product.prodname_marketplace %} billing flows and webhook into your app. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." + +If you've met the requirements for listing and you've integrated with the {% data variables.product.prodname_marketplace %} API, go ahead and submit your listing. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." + +{% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Transferring an app to an organization before you submit](#transferring-an-app-to-an-organization-before-you-submit)" below. + +### Transferring an app to an organization before you submit + +You cannot sell an app that's owned by a user account. You need to transfer the app to an organization that is already a verified creator, or that can request verification for a listing for the app. For details, see: + +1. "[Creating an organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)" + +1. "[Transferring ownership of a GitHub App](/developers/apps/transferring-ownership-of-a-github-app)" or "[Transferring ownership of an OAuth App](/developers/apps/transferring-ownership-of-an-oauth-app)" diff --git a/content/developers/github-marketplace/submitting-your-listing-for-review.md b/content/developers/github-marketplace/submitting-your-listing-for-review.md deleted file mode 100644 index 98a838e1f9..0000000000 --- a/content/developers/github-marketplace/submitting-your-listing-for-review.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Submitting your listing for review -intro: 'You can submit your listing as a verified or unverified app for the {% data variables.product.prodname_dotcom %} community to use.' -redirect_from: - - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review -versions: - free-pro-team: '*' ---- - - - -Once you've completed your app listing, you'll see two buttons that allow you to submit an unverified and verified app. The Publish without Verification **Request** button will not be available if you have published any paid pricing plans. - -![Unverified and verified request button](/assets/images/marketplace/marketplace-request-button.png) - -{% data reusables.marketplace.launch-with-free %} - -Before you can submit a verified app, you'll need to integrate the {% data variables.product.prodname_marketplace %} billing flows and webhook into your existing app. See [Verified apps](/marketplace/#verified-apps) for the steps required to submit your app. - -If you've met the [requirements](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/) for a verified {% data variables.product.prodname_marketplace %} listing and you've integrated with the {% data variables.product.prodname_marketplace %} API, go ahead and submit your listing! - -After you submit your listing for review, the {% data variables.product.prodname_marketplace %} onboarding team will reach out to you with additional information. diff --git a/content/developers/github-marketplace/testing-your-app.md b/content/developers/github-marketplace/testing-your-app.md index 09e79b1a7a..577b6d624a 100644 --- a/content/developers/github-marketplace/testing-your-app.md +++ b/content/developers/github-marketplace/testing-your-app.md @@ -1,6 +1,6 @@ --- title: Testing your app -intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before the {% data variables.product.prodname_marketplace %} onboarding team approves your app, it must adequately handle the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows).' +intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before an onboarding expert approves your app, it must adequately handle the billing flows.' redirect_from: - /apps/marketplace/testing-apps-apis-and-webhooks/ - /apps/marketplace/integrating-with-the-github-marketplace-api/testing-github-marketplace-apps/ @@ -13,7 +13,7 @@ versions: ### Testing apps -You can use a [draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) to simulate each of the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows). A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. +You can use a draft {% data variables.product.prodname_marketplace %} listing to simulate each of the billing flows. A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." #### Using a development app with a draft listing to test changes diff --git a/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md b/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md index e29643da16..96594bbc61 100644 --- a/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md +++ b/content/developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md @@ -1,6 +1,6 @@ --- title: Webhook events for the GitHub Marketplace API -intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan. For details on how to respond to each of these types of events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)."' +intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan.' redirect_from: - /apps/marketplace/setting-up-github-marketplace-webhooks/about-webhook-payloads-for-a-github-marketplace-listing/ - /apps/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/ diff --git a/content/discussions/index.md b/content/discussions/index.md index 9dff7d00d3..66dca4f270 100644 --- a/content/discussions/index.md +++ b/content/discussions/index.md @@ -22,6 +22,7 @@ featuredLinks: - /discussions/guides/finding-discussions-across-multiple-repositories - /discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions - /discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository +product_video: https://www.youtube-nocookie.com/embed/DbTWBP3_RbM layout: product-landing versions: free-pro-team: '*' diff --git a/content/discussions/quickstart.md b/content/discussions/quickstart.md index 7625961cdb..252da3b6cc 100644 --- a/content/discussions/quickstart.md +++ b/content/discussions/quickstart.md @@ -10,7 +10,7 @@ versions: ### Introduction -{% data variables.product.prodname_discussions %} {% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike issues. Discussions enable fluid, open conversation in a public forum. +{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike issues. Discussions enable fluid, open conversation in a public forum. Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information. @@ -21,7 +21,9 @@ Repository owners and people with write access can enable {% data variables.prod When you first enable a {% data variables.product.prodname_discussions %}, you will be invited to configure a welcome post. {% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} +1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} +**Settings**. +![Public settings button](/assets/images/help/discussions/public-repo-settings.png) 1. Under "Features", click **Set up discussions**. ![Set up a discussion button under "Features" for enabling or disabling discussions for a repository](/assets/images/help/discussions/setup-discussions-button.png) 1. Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community. @@ -57,4 +59,4 @@ People with triage permissions for a repository can help moderate a project's di ### Next steps -Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." +Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." diff --git a/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md b/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md index 8ce711f609..f33d4a73de 100644 --- a/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md +++ b/content/education/manage-coursework-with-github-classroom/create-an-individual-assignment.md @@ -4,6 +4,7 @@ intro: You can create an assignment for students in your course to complete indi versions: free-pro-team: '*' redirect_from: + - /education/manage-coursework-with-github-classroom/creating-an-individual-assignment - /education/manage-coursework-with-github-classroom/create-an-individual-assignment --- diff --git a/content/github/authenticating-to-github/reviewing-your-security-log.md b/content/github/authenticating-to-github/reviewing-your-security-log.md index 3727bef929..7882fef915 100644 --- a/content/github/authenticating-to-github/reviewing-your-security-log.md +++ b/content/github/authenticating-to-github/reviewing-your-security-log.md @@ -179,7 +179,7 @@ An overview of some of the most common actions that are recorded as events in th | `repo_funding_link_button_toggle` | Triggered when you enable or disable a sponsor button in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") | `repo_funding_links_file_action` | Triggered when you change the FUNDING file in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") | `sponsor_sponsorship_cancel` | Triggered when you cancel a sponsorship (see "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)") -| `sponsor_sponsorship_create` | Triggered when you sponsor a developer (see "[Sponsoring an open source contributor](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor#sponsoring-a-developer)") +| `sponsor_sponsorship_create` | Triggered when you sponsor an account (see "[Sponsoring an open source contributor](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor)") | `sponsor_sponsorship_preference_change` | Triggered when you change whether you receive email updates from a sponsored developer (see "[Managing your sponsorship](/articles/managing-your-sponsorship)") | `sponsor_sponsorship_tier_change` | Triggered when you upgrade or downgrade your sponsorship (see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)") | `sponsored_developer_approve` | Triggered when your {% data variables.product.prodname_sponsors %} account is approved (see "[Setting up {% data variables.product.prodname_sponsors %} for your user account](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account)") diff --git a/content/github/collaborating-with-issues-and-pull-requests/index.md b/content/github/collaborating-with-issues-and-pull-requests/index.md index 234ce781cd..ae4915c002 100644 --- a/content/github/collaborating-with-issues-and-pull-requests/index.md +++ b/content/github/collaborating-with-issues-and-pull-requests/index.md @@ -52,6 +52,7 @@ versions: {% link_in_list /finding-changed-methods-and-functions-in-a-pull-request %} {% link_in_list /commenting-on-a-pull-request %} {% link_in_list /viewing-a-pull-request-review %} + {% link_in_list /reviewing-dependency-changes-in-a-pull-request %} {% link_in_list /incorporating-feedback-in-your-pull-request %} {% link_in_list /approving-a-pull-request-with-required-reviews %} {% link_in_list /dismissing-a-pull-request-review %} diff --git a/content/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md new file mode 100644 index 0000000000..364fc8048c --- /dev/null +++ b/content/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md @@ -0,0 +1,74 @@ +--- +title: Reviewing dependency changes in a pull request +intro: 'If a pull request contains changes to dependencies, you can view a summary of what has changed and whether there are known vulnerabilities in any of the dependencies.' +versions: + free-pro-team: '*' +--- + +{% note %} + +**Note:** Dependency review is currently in beta and subject to change. + +{% endnote %} + +### About dependency review + +If a pull request targets your repository's default branch and contains changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities. + +Dependency review is available in: + +* All public repositories. +* Private repositories owned by organizations with an {% data variables.product.prodname_advanced_security %} license that have the dependency graph enabled. For more information, see "[Exploring the dependencies of a repository](/github/visualizing-repository-data-with-graphs/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph-for-a-private-repository)." + +Sometimes you might just want to update the version of one dependency in a manifest and generate a pull request. However, if the updated version of this direct dependency also has updated dependencies, your pull request may have more changes than you expected. The dependency review for each manifest and lock file provides an easy way to see what has changed, and whether any of the new dependency versions contain known vulnerabilities. + +By checking the dependency reviews in a pull request, and changing any dependencies that are flagged as vulnerable, you can avoid vulnerabilities being added to your project. {% data variables.product.prodname_dependabot_alerts %} will find vulnerabilities that are already in your dependencies, but it's much better to avoid introducing potential problems than to fix them at some later date. For more information about {% data variables.product.prodname_dependabot_alerts %}, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies#dependabot-alerts-for-vulnerable-dependencies)." + +Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph#supported-package-ecosystems)." + +### Reviewing dependencies in a pull request + +{% data reusables.repositories.sidebar-pr %} +{% data reusables.repositories.choose-pr-review %} +{% data reusables.repositories.changed-files %} + +1. If the pull request contains many files, use the **File filter** drop-down menu to collapse all files that don't record dependencies. This will make it easier to focus your review on the dependency changes. + + ![The file filter menu](/assets/images/help/pull_requests/file-filter-menu-json.png) + +1. On the right of the header for a manifest or lock file, display the dependency review by clicking the rich diff button. + + ![The rich diff button](/assets/images/help/pull_requests/dependency-review-rich-diff.png) + + {% note %} + + **Note:** The dependency review provides a clearer view of what has changed in large lock files, where the source diff is not rendered by default. + + {% endnote %} + +1. Check the dependencies listed in the dependency review. + + ![Vulnerability warnings in a dependency review](/assets/images/help/pull_requests/dependency-review-vulnerability.png) + + Any added or changed dependencies that have vulnerabilities are listed first, ordered by severity and then by dependency name. This means that the highest severity dependencies are always at the top of a dependency review. Other dependencies are listed alphabetically by dependency name. + + The icon beside each dependency indicates whether the dependency has been added ({% octicon "diff-added" aria-label="Dependency added icon" %}), updated ({% octicon "diff-modified" aria-label="Dependency modified icon" %}), or removed ({% octicon "diff-removed" aria-label="Dependency removed icon" %}) in this pull request. + + Other information includes: + + * The version, or version range, of the new, updated, or deleted dependency. + * For a specific version of a dependency: + * The age of that release of the dependency. + * The number of projects that are dependent on this software. This information is taken from the dependency graph. Checking the number of dependents can help you avoid accidentally adding the wrong dependency. + * The license used by this dependency, if this information is available. This is useful if you want to avoid code with certain licenses being used in your project. + + Where a dependency has a known vulnerability, the warning message includes: + + * A brief description of the vulnerability. + * A Common Vulnerabilities and Exposures (CVE) or {% data variables.product.prodname_security_advisories %} (GHSA) identification number. You can click this ID to find out more about the vulnerability. + * The severity of the vulnerability. + * The version of the dependency in which the vulnerability was fixed. If you are reviewing a pull request for someone, you might ask the contributor to update the dependency to the patched version, or a later release. + +1. You can return to the original view of the file by clicking the source diff button. + + ![The source diff button](/assets/images/help/pull_requests/dependency-review-source-diff.png) diff --git a/content/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request.md index b69a71eb46..883e41571f 100644 --- a/content/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request.md +++ b/content/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request.md @@ -30,6 +30,18 @@ Before you submit your review, your line comments are _pending_ and only visible ![Cancel review button](/assets/images/help/pull_requests/cancel-review-button.png) +{% if currentVersion == "free-pro-team@latest" %} +### Reviewing dependency changes + +If the pull request contains changes to dependencies you can use the dependency review for a manifest or lock file to see what has changed and check whether the changes introduce security vulnerabilities. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)." + +{% data reusables.repositories.changed-files %} + +1. On the right of the header for a manifest or lock file, display the dependency review by clicking the rich diff button. + + ![The rich diff button](/assets/images/help/pull_requests/dependency-review-rich-diff.png) +{% endif %} + ### Marking a file as viewed After you finish reviewing a file, you can mark the file as viewed, and the file will collapse. If the file changes after you view the file, it will be unmarked as viewed. @@ -56,8 +68,5 @@ After you've finished reviewing all the files you want in the pull request, subm ### Further reading -- "[About pull request reviews](/articles/about-pull-request-reviews)" -- "[About required reviews for pull requests](/articles/about-required-reviews-for-pull-requests)" -- "[Approving a pull request with required reviews](/articles/approving-a-pull-request-with-required-reviews)" -- "[Commenting on a pull request](/articles/commenting-on-a-pull-request)" -- "[Filtering pull requests by review status](/articles/filtering-pull-requests-by-review-status)" +- "[About required reviews for pull requests](/github/administering-a-repository/about-required-reviews-for-pull-requests)" +- "[Filtering pull requests by review status](/github/managing-your-work-on-github/filtering-pull-requests-by-review-status)" diff --git a/content/github/customizing-your-github-workflow/about-github-marketplace.md b/content/github/customizing-your-github-workflow/about-github-marketplace.md index 9cfd63182d..feb6fe7b41 100644 --- a/content/github/customizing-your-github-workflow/about-github-marketplace.md +++ b/content/github/customizing-your-github-workflow/about-github-marketplace.md @@ -7,26 +7,27 @@ versions: free-pro-team: '*' --- -You can discover, browse, and install free and paid tools, including [{% data variables.product.prodname_github_app %}s, {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/), and {% data variables.product.prodname_actions %}, in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). +You can discover, browse, and install free and paid tools, including {% data variables.product.prodname_github_app %}s, {% data variables.product.prodname_oauth_app %}s, and {% data variables.product.prodname_actions %}, in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). If you purchase a paid tool, you'll pay for your tool subscription with the same billing information you use to pay for your {% data variables.product.product_name %} subscription, and receive one bill on your regular billing date. For more information, see "[About billing for {% data variables.product.prodname_marketplace %}](/articles/about-billing-for-github-marketplace)." -You may also have the option to select a free 14-day trial on select tools. You can cancel at any time during your trial and you won't be charged, but you will automatically lose access to the tool. Your paid subscription will start at the end of the 14-day trial. For more information, see "[About billing for {% data variables.product.prodname_marketplace %}](/articles/about-billing-for-github-marketplace)." +You may also have the option to select a free 14-day trial on some tools. You can cancel at any time during your trial and you won't be charged, but you will automatically lose access to the tool. Your paid subscription will start at the end of the 14-day trial. For more information, see "[About billing for {% data variables.product.prodname_marketplace %}](/articles/about-billing-for-github-marketplace)." -{% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s can be verified or unverified. Verified apps meet specific requirements set by {% data variables.product.prodname_dotcom %} and go through a security review before they are listed on {% data variables.product.prodname_marketplace %}. For more information, see "[Requirements for listing an app on GitHub Marketplace](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." +### Finding tools on {% data variables.product.prodname_marketplace %} -### {% data variables.product.prodname_actions %} on {% data variables.product.prodname_marketplace %} +You can discover, browse, and install apps and actions created by others on {% data variables.product.prodname_marketplace %}, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)." -You can discover, browse, and install {% data variables.product.prodname_actions %} created by others on {% data variables.product.prodname_marketplace %}, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)." +{% data reusables.actions.actions-not-verified %} -Anyone can list an action on {% data variables.product.prodname_marketplace %}. Unlike some apps, {% data variables.product.prodname_actions %} listed on {% data variables.product.prodname_marketplace %} are never verified by {% data variables.product.prodname_dotcom %}. +Anyone can list a free {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} on {% data variables.product.prodname_marketplace %}. Publishers of paid apps are verified by {% data variables.product.company_short %} and listings for these apps are shown with a verified creator badge {% octicon "verified" aria-label="Verified creator badge" %}. You will also see badges for unverified and verified apps. These apps were published using the previous method for verifying individual apps. For more information about the current process, see "[About verified creators](/developers/github-marketplace/about-verified-creators)" and "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." ### Building and listing a tool on {% data variables.product.prodname_marketplace %} -For more information on creating your own tool to list on {% data variables.product.prodname_marketplace %}, see "[Apps](/apps)" and "[{% data variables.product.prodname_actions %}](/actions)." +For more information on creating your own tool to list on {% data variables.product.prodname_marketplace %}, see "[Apps](/developers/apps)" and "[{% data variables.product.prodname_actions %}](/actions)." ### Further reading - "[Purchasing and installing apps in {% data variables.product.prodname_marketplace %}](/articles/purchasing-and-installing-apps-in-github-marketplace)" - "[Managing billing for {% data variables.product.prodname_marketplace %} apps](/articles/managing-billing-for-github-marketplace-apps)" - "[{% data variables.product.prodname_marketplace %} support](/articles/github-marketplace-support)" +- "[Differences between GitHub Apps and OAuth Apps](/developers/apps/differences-between-github-apps-and-oauth-apps)" diff --git a/content/github/getting-started-with-github/github-glossary.md b/content/github/getting-started-with-github/github-glossary.md index a949c7a0eb..b3c87dcf68 100644 --- a/content/github/getting-started-with-github/github-glossary.md +++ b/content/github/getting-started-with-github/github-glossary.md @@ -10,8 +10,8 @@ versions: --- {% for term in site.data.glossaries.external %} - ### {{term.term}} - {{term.description}} + ### {% data glossaries.external[forloop.index0].term %} + {% data glossaries.external[forloop.index0].description %} --- {% endfor %} diff --git a/content/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies.md b/content/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies.md index a628b146fd..67f9613edb 100644 --- a/content/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies.md +++ b/content/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies.md @@ -25,6 +25,8 @@ When your code depends on a package that has a security vulnerability, this vuln - New advisory data is synchronized to {% data variables.product.prodname_ghe_server %} each hour from {% data variables.product.prodname_dotcom_the_website %}. For more information about advisory data, see "Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}."{% endif %} - The dependency graph for a repository changes. For example, when a contributor pushes a commit to change the packages or versions it depends on{% if currentVersion == "free-pro-team@latest" %}, or when the code of one of the dependencies changes{% endif %}. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)." +{% data reusables.repositories.dependency-review %} + For a list of the ecosystems that {% data variables.product.product_name %} can detect vulnerabilities and dependencies for, see "[Supported package ecosystems](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph#supported-package-ecosystems)." {% note %} diff --git a/content/github/managing-security-vulnerabilities/about-managing-vulnerable-dependencies.md b/content/github/managing-security-vulnerabilities/about-managing-vulnerable-dependencies.md new file mode 100644 index 0000000000..9041daa8de --- /dev/null +++ b/content/github/managing-security-vulnerabilities/about-managing-vulnerable-dependencies.md @@ -0,0 +1,25 @@ +--- +title: About managing vulnerable dependencies +intro: '{% data variables.product.prodname_dotcom %} helps you to avoid using third-party software that contains known vulnerabilities.' +versions: + free-pro-team: '*' +--- + +{% data variables.product.prodname_dotcom %} provides the following tools for removing and avoiding vulnerable dependencies. + +#### Dependency graph +The dependency graph is a summary of the manifest and lock files stored in a repository. It shows you the ecosystems and packages your codebase depends on (its dependencies) and the repositories and packages that depend on your project (its dependents). The information in the dependency graph is used by dependency review and {% data variables.product.prodname_dependabot %}. +For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)." + +#### Dependency review +By checking the dependency reviews on pull requests you can avoid introducing vulnerabilities from dependencies into your codebase. If the pull requests adds a vulnerable dependency, or changes a dependency to a vulnerable version, this is highlighted in the dependency review. You can change the dependency to a patched version before merging the pull request. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)." + +#### {% data variables.product.prodname_dependabot_alerts %} +{% data variables.product.prodname_dotcom %} can create {% data variables.product.prodname_dependabot_alerts %} when it detects vulnerable dependencies in your repository. The alert is displayed on the Security tab for the repository. The alert includes a link to the affected file in the project, and information about a fixed version. {% data variables.product.prodname_dotcom %} also notifies the maintainers of the repository, according to their notification preferences. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." + +#### {% data variables.product.prodname_dependabot_security_updates %} +When {% data variables.product.prodname_dotcom %} generates a {% data variables.product.prodname_dependabot %} alert for a vulnerable dependency in your repository, {% data variables.product.prodname_dependabot %} can automatically try to fix it for you. {% data variables.product.prodname_dependabot_security_updates %} are automatically generated pull requests that update a vulnerable dependency to a fixed version. For more information, see "[About {% data variables.product.prodname_dependabot_security_updates %}](/github/managing-security-vulnerabilities/about-dependabot-security-updates)." + + +#### {% data variables.product.prodname_dependabot_version_updates %} +Enabling {% data variables.product.prodname_dependabot_version_updates %} takes the effort out of maintaining your dependencies. With {% data variables.product.prodname_dependabot_version_updates %}, whenever {% data variables.product.prodname_dotcom %} identifies an outdated dependency, it raises a pull request to update the manifest to the latest version of the dependency. By contrast, {% data variables.product.prodname_dependabot_security_updates %} only raises pull requests to fix vulnerable dependencies. For more information, see "[About Dependabot version updates](/github/administering-a-repository/about-dependabot-version-updates)." diff --git a/content/github/managing-security-vulnerabilities/index.md b/content/github/managing-security-vulnerabilities/index.md index 14e9fc90c3..9afde0213a 100644 --- a/content/github/managing-security-vulnerabilities/index.md +++ b/content/github/managing-security-vulnerabilities/index.md @@ -21,6 +21,7 @@ versions: {% link_in_list /editing-a-security-advisory %} {% link_in_list /withdrawing-a-security-advisory %} {% topic_link_in_list /managing-vulnerabilities-in-your-projects-dependencies %} + {% link_in_list /about-managing-vulnerable-dependencies %} {% link_in_list /browsing-security-vulnerabilities-in-the-github-advisory-database %} {% link_in_list /about-alerts-for-vulnerable-dependencies %} {% link_in_list /configuring-notifications-for-vulnerable-dependencies %} diff --git a/content/github/managing-security-vulnerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository.md b/content/github/managing-security-vulnerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository.md index 0dea3bd05c..532fddecb5 100644 --- a/content/github/managing-security-vulnerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository.md +++ b/content/github/managing-security-vulnerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository.md @@ -12,9 +12,11 @@ Your repository's {% data variables.product.prodname_dependabot %} alerts tab li You can enable automatic security updates for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For more information, see "[About {% data variables.product.prodname_dependabot_security_updates %}](/github/managing-security-vulnerabilities/about-dependabot-security-updates)." +{% data reusables.repositories.dependency-review %} + ### About updates for vulnerable dependencies in your repository -{% data variables.product.product_name %} generates {% data variables.product.prodname_dependabot_alerts %} when we detect vulnerabilities affecting your repository. For repositories where {% data variables.product.prodname_dependabot_security_updates %} are enabled, when {% data variables.product.product_name %} detects a vulnerable dependency {% data variables.product.prodname_dependabot %} creates a pull request to fix it. The pull request will upgrade the dependency to the minimum possible secure version needed to avoid the vulnerability. +{% data variables.product.product_name %} generates {% data variables.product.prodname_dependabot_alerts %} when we detect that your codebase is using dependencies with known vulnerabilities. For repositories where {% data variables.product.prodname_dependabot_security_updates %} are enabled, when {% data variables.product.product_name %} detects a vulnerable dependency in the default branch, {% data variables.product.prodname_dependabot %} creates a pull request to fix it. The pull request will upgrade the dependency to the minimum possible secure version needed to avoid the vulnerability. ### Viewing and updating vulnerable dependencies diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md index fec21f3ab7..f5cb393123 100644 --- a/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md +++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md @@ -9,6 +9,8 @@ versions: {% data reusables.sponsors.sponsorship-details %} +{% data reusables.sponsors.no-fees %} + {% data reusables.dotcom_billing.view-all-subscriptions %} ### Further reading diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md index 5ec6dafb61..4d9595814c 100644 --- a/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md +++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md @@ -7,25 +7,24 @@ versions: free-pro-team: '*' --- +{% data reusables.sponsors.org-sponsors-release-phase %} + +### About sponsorship downgrades + +When you downgrade or cancel a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %} + ### Downgrading a sponsorship -When you downgrade a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %} - -{% data reusables.user_settings.access_settings %} -{% data reusables.user_settings.billing %} -{% data reusables.user_settings.subscriptions-tab %} -{% data reusables.sponsors.change-tier %} -4. On the right side of the page, next to your selected tier, click **Edit**. - ![Edit tier button](/assets/images/help/billing/edit-tier-button.png) +{% data reusables.sponsors.navigate-to-sponsored-account %} +{% data reusables.sponsors.sponsorship-dashboard %} {% data reusables.sponsors.select-a-tier %} {% data reusables.sponsors.update-sponsorship %} ### Canceling a sponsorship -When you cancel a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %} - {% data reusables.user_settings.access_settings %} {% data reusables.user_settings.billing %} +{% data reusables.sponsors.billing-switcher %} {% data reusables.user_settings.subscriptions-tab %} 3. Under "{% data variables.product.prodname_sponsors %}", to the right of the sponsored open source contributor, click {% octicon "triangle-down" aria-label="The down triangle octicon" %} next to your sponsored amount, then click **Cancel sponsorship**. ![Cancel sponsorship button](/assets/images/help/billing/edit-sponsor-billing.png) diff --git a/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md b/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md index 7637a1e68b..cd65d50f26 100644 --- a/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md +++ b/content/github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md @@ -7,13 +7,15 @@ versions: free-pro-team: '*' --- +{% data reusables.sponsors.org-sponsors-release-phase %} + +### About sponsorship upgrades + When you upgrade your sponsorship tier, the change will become effective immediately. {% data reusables.sponsors.prorated-sponsorship %} -{% data reusables.user_settings.access_settings %} -{% data reusables.user_settings.billing %} -{% data reusables.user_settings.subscriptions-tab %} -{% data reusables.sponsors.change-tier %} -4. On the right side of the page, next to your selected tier, click **Edit**. - ![Edit tier button](/assets/images/help/billing/edit-tier-button.png) +### Upgrading a sponsorship + +{% data reusables.sponsors.navigate-to-sponsored-account %} +{% data reusables.sponsors.sponsorship-dashboard %} {% data reusables.sponsors.select-a-tier %} -{% data reusables.sponsors.update-sponsorship %} +{% data reusables.sponsors.update-sponsorship %} \ No newline at end of file diff --git a/content/github/setting-up-and-managing-organizations-and-teams/index.md b/content/github/setting-up-and-managing-organizations-and-teams/index.md index 7125ecac8d..d1c440e8c5 100644 --- a/content/github/setting-up-and-managing-organizations-and-teams/index.md +++ b/content/github/setting-up-and-managing-organizations-and-teams/index.md @@ -92,6 +92,7 @@ versions: {% link_in_list /managing-default-labels-for-repositories-in-your-organization %} {% link_in_list /changing-the-visibility-of-your-organizations-dependency-insights %} {% link_in_list /managing-the-display-of-member-names-in-your-organization %} + {% link_in_list /managing-updates-from-accounts-your-organization-sponsors %} {% link_in_list /disabling-publication-of-github-pages-sites-for-your-organization %} {% link_in_list /deleting-an-organization-account %} {% link_in_list /converting-an-organization-into-a-user %} diff --git a/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md b/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md new file mode 100644 index 0000000000..f60a664644 --- /dev/null +++ b/content/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md @@ -0,0 +1,25 @@ +--- +title: Managing updates from accounts your organization sponsors +intro: You can manage the email address that receives updates from accounts your organization sponsors. +versions: + free-pro-team: '*' +permissions: Organization owners can manage updates from accounts the organization sponsors. +--- + +{% data reusables.sponsors.org-sponsors-release-phase %} + +The developers and organizations that your organization sponsors can send you updates about their work. You can manage the email address that receives these updates. + +You can also disable updates from accounts your organization sponsors. For more information, see "[Managing your sponsorship](/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship#managing-email-updates-for-your-sponsorship)." + +{% data reusables.profile.access_profile %} +{% data reusables.profile.access_org %} +{% data reusables.organizations.org_settings %} +1. Under "Sponsors update email (Private)", type the email address you want to receive updates from accounts your organization sponsors. + ![Textbox to enter the email address to receive updates from sponsored accounts](/assets/images/help/sponsors/organization-update-email-textbox.png) +1. Click **Update profile**. + ![Update profile button](/assets/images/help/organizations/update-profile-button.png) + +### Further reading + +- "[Supporting the open source community with {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors)" \ No newline at end of file diff --git a/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md index 6b04032d74..8add77b2f3 100644 --- a/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md +++ b/content/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization.md @@ -55,6 +55,9 @@ Organization members can have *owner*{% if currentVersion == "free-pro-team@late | Disable team discussions for an organization (see "[Disabling team discussions for your organization](/articles/disabling-team-discussions-for-your-organization)" for details) | **X** | | |{% if currentVersion == "free-pro-team@latest" %} | Manage viewing of organization dependency insights (see "[Changing the visibility of your organization's dependency insights](/articles/changing-the-visibility-of-your-organizations-dependency-insights)" for details) | **X** | | |{% endif %} | Set a team profile picture in **all teams** (see "[Setting your team's profile picture](/articles/setting-your-team-s-profile-picture)" for details) | **X** | | | +| Sponsor accounts and manage the organization's sponsorships (see "[Sponsoring open-source contributors](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-open-source-contributors)" for details) | **X** | **X** | | +| Manage email updates from sponsored accounts (see "[Managing updates from accounts your organization's sponsors](/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors)" for details) | **X** | | | +| Attribute your sponsorships to another organization (see "[Attributing sponsorships to your organization](/github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization)" for details ) | **X** | | | | Disable publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see "[Disabling publication of {% data variables.product.prodname_pages %} sites for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-publication-of-github-pages-sites-for-your-organization)" for details) | **X** | | | | Manage security and analysis settings (see "[Managing security and analysis settings for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-security-and-analysis-settings-for-your-organization)" for details) | **X** | | | | Enable and enforce [SAML single sign-on](/articles/about-identity-and-access-management-with-saml-single-sign-on) | **X** | | | diff --git a/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md index f069a69113..fcb5bd5ba7 100644 --- a/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md +++ b/content/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md @@ -107,25 +107,53 @@ Using the qualifier `country`, you can filter events in the audit log based on t {% data reusables.audit_log.exported-log-keys-and-values %} {% endif %} -### Using the Audit log API +### Using the audit log API + +You can interact with the audit log using the GraphQL API{% if currentVersion == "free-pro-team@latest" %} or the REST API{% endif %}. + +{% if currentVersion == "free-pro-team@latest" %} + +#### Using the GraphQL API + +{% endif %} {% note %} -**Note**: The Audit log API is available for organizations using {% data variables.product.prodname_enterprise %}. {% data reusables.gated-features.more-info-org-products %} +**Note**: The audit log GraphQL API is available for organizations using {% data variables.product.prodname_enterprise %}. {% data reusables.gated-features.more-info-org-products %} {% endnote %} -To ensure a secure IP and maintain compliance for your organization, you can use the Audit log API to keep copies of your audit log data and monitor: -* Access to your organization or repository settings. -* Changes in permissions. -* Added or removed users in an organization, repository, or team. -* Users being promoted to admin. -* Changes to permissions of a GitHub App. +To ensure a secure IP and maintain compliance for your organization, you can use the audit log GraphQL API to keep copies of your audit log data and monitor: +{% data reusables.audit_log.audit-log-api-info %} + +{% if currentVersion == "free-pro-team@latest" %} +Note that you can't retrieve Git events using the GraphQL API. +{% endif %} The GraphQL response can include data for up to 90 to 120 days. For example, you can make a GraphQL request to see all the new organization members added to your organization. For more information, see the "[GraphQL API Audit Log](/graphql/reference/interfaces#auditentry/)." +{% if currentVersion == "free-pro-team@latest" %} + +#### Using the REST API + +{% note %} + +**Note**: The audit log REST API is available as a limited beta for users of {% data variables.product.prodname_ghe_cloud %} only. To join the beta, talk to your services or sales contact at {% data variables.product.company_short %}. + +{% endnote %} + +To ensure a secure IP and maintain compliance for your organization, you can use the audit log REST API to keep copies of your audit log data and monitor: +{% data reusables.audit_log.audit-log-api-info %} +* Git events, such as cloning, fetching, and pushing + +{% data reusables.audit_log.audit-log-git-events-retention %} + +For more information about the audit log REST API, see "[Organizations](/rest/reference/orgs#get-the-audit-log-for-an-organization)" in the REST API documentation. + +{% endif %} + ### Audit log actions An overview of some of the most common actions that are recorded as events in the audit log. @@ -215,6 +243,28 @@ An overview of some of the most common actions that are recorded as events in th | `update` | Triggered when [a reply to a team discussion post is edited](/articles/managing-disruptive-comments/#editing-a-comment). | `destroy` | Triggered when [a reply to a team discussion post is deleted](/articles/managing-disruptive-comments/#deleting-a-comment). +{% if currentVersion == "free-pro-team@latest" %} + +#### `git` category actions + +{% note %} + +**Note:** To access Git events in the audit log, you must use the audit log REST API. This functionality is available as a limited beta for users of {% data variables.product.prodname_ghe_cloud %} only. To join the beta, talk to your services or sales contact at {% data variables.product.company_short %}. + +For more information about the audit log REST API, see "[Organizations](/rest/reference/orgs#get-the-audit-log-for-an-organization)" in the REST API documentation. + +{% endnote %} + +{% data reusables.audit_log.audit-log-git-events-retention %} + +| Action | Description +|---------|---------------------------- +| `clone` | Triggered when a repository is cloned. +| `fetch` | Triggered when changes are fetched from a repository. +| `push` | Triggered when changes are pushed to a repository. + +{% endif %} + #### `hook` category actions | Action | Description @@ -502,8 +552,20 @@ For more information, see "[Restricting publication of {% data variables.product | Action | Description |------------------|------------------- -| repo_funding_link_button_toggle | Triggered when you enable or disable a sponsor button in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") -| repo_funding_links_file_action | Triggered when you change the FUNDING file in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") +| `repo_funding_link_button_toggle` | Triggered when you enable or disable a sponsor button in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") +| `repo_funding_links_file_action` | Triggered when you change the FUNDING file in your repository (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)") +| `sponsor_sponsorship_cancel` | Triggered when you cancel a sponsorship (see "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)") +| `sponsor_sponsorship_create` | Triggered when you sponsor an account (see "[Sponsoring an open source contributor](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor)") +| `sponsor_sponsorship_preference_change` | Triggered when you change whether you receive email updates from a sponsored account (see "[Managing your sponsorship](/articles/managing-your-sponsorship)") +| `sponsor_sponsorship_tier_change` | Triggered when you upgrade or downgrade your sponsorship (see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)") +| `sponsored_developer_approve` | Triggered when your {% data variables.product.prodname_sponsors %} account is approved (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)") +| `sponsored_developer_create` | Triggered when your {% data variables.product.prodname_sponsors %} account is created (see "[Setting up {% data variables.product.prodname_sponsors %} for your organizaion](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)") +| `sponsored_developer_profile_update` | Triggered when you edit your sponsored organization profile (see "[Editing your profile details for {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors)") +| `sponsored_developer_request_approval` | Triggered when you submit your application for {% data variables.product.prodname_sponsors %} for approval (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)") +| `sponsored_developer_tier_description_update` | Triggered when you change the description for a sponsorship tier (see "[Changing your sponsorship tiers](/articles/changing-your-sponsorship-tiers)") +| sponsored_developer_update_newsletter_send | Triggered when you send an email update to your sponsors (see "[Contacting your sponsors](/articles/contacting-your-sponsors)") +| `waitlist_invite_sponsored_developer` | Triggered when you are invited to join {% data variables.product.prodname_sponsors %} from the waitlist (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)") +| `waitlist_join` | Triggered when you join the waitlist to become a sponsored organization (see "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)") {% endif %} {% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} diff --git a/content/github/setting-up-and-managing-your-github-user-account/index.md b/content/github/setting-up-and-managing-your-github-user-account/index.md index 6ce7743d9f..352849bd57 100644 --- a/content/github/setting-up-and-managing-your-github-user-account/index.md +++ b/content/github/setting-up-and-managing-your-github-user-account/index.md @@ -14,6 +14,7 @@ versions: {% topic_link_in_list /managing-user-account-settings %} {% link_in_list /about-your-personal-dashboard %} + {% link_in_list /managing-your-theme-settings %} {% link_in_list /changing-your-github-username %} {% link_in_list /merging-multiple-user-accounts %} {% link_in_list /converting-a-user-into-an-organization %} diff --git a/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md b/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md new file mode 100644 index 0000000000..37f6c58643 --- /dev/null +++ b/content/github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings.md @@ -0,0 +1,24 @@ +--- +title: Managing your theme settings +intro: You can manage how {% data variables.product.product_name %} looks to you by setting a theme preference that either follows your system settings or always uses light mode or dark mode. +versions: + free-pro-team: '*' +--- + +{% note %} + +**Note:** Theme settings is currently in beta and subject to change. + +{% endnote %} + +For choice and flexibility in how and when you use {% data variables.product.product_name %}, you can configure theme settings to change how {% data variables.product.product_name %} looks to you. You can choose from two themes, light and dark, or you can configure {% data variables.product.product_name %} to follow your system settings. Some developers use dark theme for personal preference, to reduce power consumption on certain devices, or to reduce eye strain in low-light conditions. + +{% data reusables.user_settings.access_settings %} +1. In the user settings sidebar, click **Appearance**. + !["Apperance" tab in user settings sidebar](/assets/images/help/settings/appearance-tab.png) +1. Under "Theme", select a theme preference. + ![Radio buttons for theme settings](/assets/images/help/settings/theme-settings-radio-buttons.png) + +### Further reading + +- "[Setting a theme for {% data variables.product.prodname_desktop %}](/desktop/installing-and-configuring-github-desktop/setting-a-theme-for-github-desktop)" diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors.md b/content/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors.md index f3297bfd7e..b3bb5af8c9 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors.md @@ -9,7 +9,9 @@ versions: ### About {% data variables.product.prodname_sponsors %} -{% data reusables.sponsors.sponsorship-details %} {% data reusables.sponsors.no-fees %} For more information, see "[About billing for {% data variables.product.prodname_sponsors %}](/articles/about-billing-for-github-sponsors)." +{% data reusables.sponsors.sponsorship-details %} + +{% data reusables.sponsors.no-fees %} For more information, see "[About billing for {% data variables.product.prodname_sponsors %}](/articles/about-billing-for-github-sponsors)." {% data reusables.sponsors.you-can-be-a-sponsored-developer %} For more information, see "[About {% data variables.product.prodname_sponsors %} for open source contributors](/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors-for-open-source-contributors)" and "[Setting up {% data variables.product.prodname_sponsors %} for your user account](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account)." @@ -25,7 +27,7 @@ When you become a sponsored developer or sponsored organization, additional term {% endnote %} -The {% data variables.product.prodname_matching_fund %} aims to benefit members of the {% data variables.product.prodname_dotcom %} community who develop open source software that promotes the [{% data variables.product.prodname_dotcom %} Community Guidelines](/github/site-policy/github-community-guidelines). Sponsored organizations are not eligible for {% data variables.product.prodname_matching_fund %}. +The {% data variables.product.prodname_matching_fund %} aims to benefit members of the {% data variables.product.prodname_dotcom %} community who develop open source software that promotes the [{% data variables.product.prodname_dotcom %} Community Guidelines](/github/site-policy/github-community-guidelines). Payments to sponsored organizations and payments from organizations are not eligible for {% data variables.product.prodname_matching_fund %}. To be eligible for the {% data variables.product.prodname_matching_fund %}, you must create a profile that will attract a community that will sustain you for the long term. For more information about creating a strong profile, see "[Editing your profile details for {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors)." @@ -35,8 +37,6 @@ To be eligible for the {% data variables.product.prodname_matching_fund %}, you This is just the beginning — we'd love your input to make sure {% data variables.product.prodname_sponsors %} serves your needs into the future. Please send us your feedback or suggestions by contacting [{% data variables.contact.github_support %}](https://support.github.com/contact?form%5Bsubject%5D=GitHub+Sponsors). -Currently, only individual users can sponsor developers and organizations. If your organization is interested in sponsoring developers, please let us know by contacting [{% data variables.contact.github_support %}](https://support.github.com/contact?form%5Bsubject%5D=GitHub+Sponsors). - ### Further reading - "[Sponsoring open source contributors](/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-open-source-contributors)" - "[Receiving sponsorships through {% data variables.product.prodname_sponsors %}](/github/supporting-the-open-source-community-with-github-sponsors/receiving-sponsorships-through-github-sponsors)" diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization.md b/content/github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization.md new file mode 100644 index 0000000000..993701f37c --- /dev/null +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization.md @@ -0,0 +1,17 @@ +--- +title: Attributing sponsorships to your organization +intro: 'You can attribute the sponsorships paid by one of your organizations to another organization.' +versions: + free-pro-team: '*' +permissions: People who are organization owners of both organizations can attribute one organization's sponsorships to another organization. +--- + +1. Navigate to the organization whose sponsorships you want to attribute to another organization. +1. Under your organization name, click {% octicon "heart" aria-label="The heart icon" %} **Sponsoring**. + !["Sponsoring" tab](/assets/images/help/sponsors/sponsoring-tab.png) +1. In the upper-right corner, click {% octicon "gear" aria-label="The gear icon" %} **Settings**. + !["Settings" button](/assets/images/help/sponsors/sponsoring-settings-button.png) +1. Under "Link sponsorships to another account", use the drop-down menu, then click the organization you want this organization's sponsorships to be attributed to. + ![Drop-down menu to select account](/assets/images/help/sponsors/select-an-account-drop-down.png) +1. Click **Link account**. + !["Link account" button](/assets/images/help/sponsors/link-account-button.png) \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers.md b/content/github/supporting-the-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers.md index 4bed524e3c..f9b176f55d 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers.md @@ -13,38 +13,20 @@ versions: {% data reusables.sponsors.maximum-tier %} -### Adding a tier for your sponsored developer profile +### Adding a tier -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} {% data reusables.sponsors.click-add-tier %} {% data reusables.sponsors.tier-price-description %} {% data reusables.sponsors.save-tier-draft %} {% data reusables.sponsors.review-and-publish-tier %} -### Adding a tier for your sponsored organization profile +### Editing or retiring a tier -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.click-add-tier %} -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.save-tier-draft %} -{% data reusables.sponsors.review-and-publish-tier %} - -### Editing or retiring a tier for your sponsored developer profile - -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} {% data reusables.sponsors.edit-tier %} {% data reusables.sponsors.tier-price-description %} {% data reusables.sponsors.tier-update %} -{% data reusables.sponsors.retire-tier %} - -### Editing or retiring a tier for your sponsored organization profile - -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.edit-tier %} -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.tier-update %} -{% data reusables.sponsors.retire-tier %} +{% data reusables.sponsors.retire-tier %} \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md b/content/github/supporting-the-open-source-community-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md index f73cfc6f93..0cae836a8f 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md @@ -5,11 +5,13 @@ versions: free-pro-team: '*' --- -To monitor changes to your sponsorships, such as cancellations at the end of a pay period, you can create webhooks for your sponsored user or organization account. When you set up a webhook for your sponsored user or organization account, you'll receive updates when sponsorships are created, edited, or deleted. For more information, see the [`sponsorship` webhook event](/webhooks/event-payloads/#sponsorship). +### About webhooks for events in your sponsored account -### Managing webhooks for your sponsored user account +To monitor changes to your sponsorships, such as cancellations at the end of a pay period, you can create webhooks for your sponsored user or organization account. When you set up a webhook for your sponsored account, you'll receive updates when sponsorships are created, edited, or deleted. For more information, see the [`sponsorship` webhook event](/webhooks/event-payloads/#sponsorship). -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +### Managing webhooks for events in your sponsored account + +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-webhooks-tab %} {% data reusables.sponsors.add-webhook %} {% data reusables.sponsors.add-payload-url %} @@ -17,18 +19,4 @@ To monitor changes to your sponsorships, such as cancellations at the end of a p {% data reusables.sponsors.webhook-secret-token %} {% data reusables.sponsors.add-active-triggers %} {% data reusables.sponsors.confirm-add-webhook %} -{% data reusables.sponsors.manage-existing-webhooks %} - -### Managing webhooks for your sponsored organization - -Organization owners can configure webhooks for a sponsored organization. - -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-webhooks-tab %} -{% data reusables.sponsors.add-webhook %} -{% data reusables.sponsors.add-payload-url %} -{% data reusables.sponsors.webhook-content-formatting %} -{% data reusables.sponsors.webhook-secret-token %} -{% data reusables.sponsors.add-active-triggers %} -{% data reusables.sponsors.confirm-add-webhook %} -{% data reusables.sponsors.manage-existing-webhooks %} +{% data reusables.sponsors.manage-existing-webhooks %} \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/contacting-your-sponsors.md b/content/github/supporting-the-open-source-community-with-github-sponsors/contacting-your-sponsors.md index 80e23f3cf5..640d965448 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/contacting-your-sponsors.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/contacting-your-sponsors.md @@ -7,22 +7,15 @@ versions: free-pro-team: '*' --- +### About sponsorship updates + Your sponsors can choose whether they receive email updates about your work. For more information, see "[Managing your sponsorship](/articles/managing-your-sponsorship)." -The update will come from your user account's primary email address or organization account's `noreply@github.com` email address. If you've enabled email address privacy on your user account, the update will come from `noreply@github.com` instead. For more information, see "[Setting your commit email address](/articles/setting-your-commit-email-address)." +For sponsored developer accounts, the update will come from your user account's primary email address. If you've enabled email address privacy on your user account, the update will come from `noreply@github.com` instead. For sponsored organizations, the update will come from the organization's `noreply@github.com` email address. For more information, see "[Setting your commit email address](/articles/setting-your-commit-email-address)." -### Contacting your user account's sponsors +### Contacting your sponsors -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} -{% data reusables.sponsors.sponsors-updates-tab %} -{% data reusables.sponsors.draft-new-update %} -{% data reusables.sponsors.send-update-to-sponsors %} -{% data reusables.sponsors.write-sponsor-update %} -{% data reusables.sponsors.publish-sponsor-update %} - -### Contacting your organization's sponsors - -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.sponsors-updates-tab %} {% data reusables.sponsors.draft-new-update %} {% data reusables.sponsors.send-update-to-sponsors %} diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors.md b/content/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors.md index e841276f04..53004b7463 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors.md @@ -10,30 +10,17 @@ versions: ### About sponsor profiles -Your {% data variables.product.prodname_sponsors %} profile tells potential sponsors why they should support you. People see your sponsor profile when they click the **Sponsor** button on your personal or organization profile. We recommend including the following information. +Your {% data variables.product.prodname_sponsors %} profile tells potential sponsors why they should support you. People see your sponsor profile when they click the **Sponsor** button on your profile. We recommend including the following information. -- Open source work that you contribute to. -- Why you are committed to open source development. +- Open source work that you contribute to +- Why you are committed to open source development -You can also set goals to explain what different of levels of sponsorship will allow you to do for the community. +### Editing your profile details -### Editing your sponsored developer profile - -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-profile-tab %} {% data reusables.sponsors.short-bio %} {% data reusables.sponsors.add-introduction %} {% data reusables.sponsors.edit-featured-work %} {% data reusables.sponsors.opt-in-to-being-featured %} -{% data reusables.sponsors.save-profile %} - -### Editing your sponsored organization profile - -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-profile-tab %} -{% data reusables.sponsors.short-bio %} -{% data reusables.sponsors.add-introduction %} -{% data reusables.sponsors.meet-the-team %} -{% data reusables.sponsors.edit-featured-work %} -{% data reusables.sponsors.opt-in-to-being-featured %} -{% data reusables.sponsors.save-profile %} +{% data reusables.sponsors.save-profile %} \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/index.md b/content/github/supporting-the-open-source-community-with-github-sponsors/index.md index def51bcb47..48892ef8f2 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/index.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/index.md @@ -16,6 +16,7 @@ versions: {% topic_link_in_list /sponsoring-open-source-contributors %} {% link_in_list /sponsoring-an-open-source-contributor %} {% link_in_list /managing-your-sponsorship %} + {% link_in_list /attributing-sponsorships-to-your-organization %} {% topic_link_in_list /receiving-sponsorships-through-github-sponsors %} {% link_in_list /about-github-sponsors-for-open-source-contributors %} {% link_in_list /setting-up-github-sponsors-for-your-user-account %} diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-payouts-from-github-sponsors.md b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-payouts-from-github-sponsors.md index 295daca888..abfed9bd2c 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-payouts-from-github-sponsors.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-payouts-from-github-sponsors.md @@ -13,14 +13,8 @@ You can only manage your payouts from {% data variables.product.prodname_sponsor {% data reusables.sponsors.payout-info %} -### Viewing and editing payout information for your sponsored user account +### Viewing and editing payout information -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-payouts-tab %} -{% data reusables.sponsors.edit-bank-information %} - -### Viewing and editing payout information for your sponsored organization - -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-payouts-tab %} -{% data reusables.sponsors.edit-bank-information %} +{% data reusables.sponsors.edit-bank-information %} \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-goal.md b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-goal.md index 07a67e1a88..a4d3bdc206 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-goal.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-goal.md @@ -1,27 +1,19 @@ --- title: Managing your sponsorship goal -intro: You can set a goal for your sponsored developer or sponsored organization profile to help the community understand the impact of sponsoring you. +intro: You can set a goal for your sponsored developer or sponsored organization account to help the community understand the impact of sponsoring you. versions: free-pro-team: '*' --- ### About sponsorship goals -You can set a funding goal for your sponsored developer or organization profile and share the goal with your community. Goals help you understand the impact you have in the open source community and build up your presence in the {% data variables.product.prodname_sponsors %} program. +You can set a funding goal for your sponsored account and share the goal with your community. Goals help you understand the impact you have in the open source community and build up your presence in the {% data variables.product.prodname_sponsors %} program. Your goal can set a target for the number of sponsors you want to have or the amount of money you want to earn each month. You can only set one goal up at a time. After you reach a goal, you can set another goal. -### Setting a goal for a sponsored organization +### Setting a goal -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-your-goals-tab %} -{% data reusables.sponsors.set-a-goal %} -{% data reusables.sponsors.select-goal-type %} -{% data reusables.sponsors.publish-goal %} - -### Setting a goal for a sponsored developer - -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-your-goals-tab %} {% data reusables.sponsors.set-a-goal %} {% data reusables.sponsors.select-goal-type %} @@ -31,6 +23,7 @@ Your goal can set a target for the number of sponsors you want to have or the am When you edit a goal, you can't choose a goal you've already achieved. For example, if you already have 5 sponsors, you can't edit your goal so that you're aiming for 4 sponsors. +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-your-goals-tab %} {% data reusables.sponsors.edit-goal %} {% data reusables.sponsors.select-goal-type %} @@ -40,6 +33,7 @@ When you edit a goal, you can't choose a goal you've already achieved. For examp After you retire a goal, you won't be able to reactivate the goal. You must create a new goal instead. +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-your-goals-tab %} {% data reusables.sponsors.edit-goal %} {% data reusables.sponsors.retire-goal %} diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship.md b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship.md index 17c1100ced..ad0e8d461d 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship.md @@ -1,42 +1,35 @@ --- title: Managing your sponsorship -intro: You can manage who can see your sponsorship and whether you receive email updates from the sponsored open source contributor. +intro: You can manage who can see your sponsorship and whether you receive email updates from the sponsored account. redirect_from: - /articles/managing-your-sponsorship versions: free-pro-team: '*' --- -For information about changing your sponsorship tier, see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)." +{% data reusables.sponsors.org-sponsors-release-phase %} -### Managing the privacy setting for your developer sponsorship +### Managing the privacy setting for your sponsorship -{% data reusables.sponsors.navigate-to-sponsored-developer %} -{% data reusables.sponsors.manage-developer-sponsorship %} +{% data reusables.sponsors.navigate-to-sponsored-account %} +{% data reusables.sponsors.sponsorship-dashboard %} +{% data reusables.sponsors.manage-sponsorship %} {% data reusables.sponsors.who-can-see-your-sponsorship %} {% data reusables.sponsors.update-sponsorship %} -### Managing the privacy setting for your organization sponsorship +### Managing email updates for your sponsorship -{% data reusables.sponsors.navigate-to-sponsored-org %} -{% data reusables.sponsors.manage-org-sponsorship %} -{% data reusables.sponsors.who-can-see-your-sponsorship %} +You can choose whether an account you sponsor can send you email updates about their work. The sponsored account will not have access to your email address. + +{% data reusables.sponsors.manage-updates-for-orgs %} + +{% data reusables.sponsors.navigate-to-sponsored-account %} +{% data reusables.sponsors.sponsorship-dashboard %} +{% data reusables.sponsors.manage-sponsorship %} +{% data reusables.sponsors.choose-updates %} {% data reusables.sponsors.update-sponsorship %} -### Managing email updates from a sponsored developer +### Further reading -You can choose whether a sponsored developer can send you email updates about their work. The sponsored developer will not have access to your email address. - -{% data reusables.sponsors.navigate-to-sponsored-developer %} -{% data reusables.sponsors.manage-developer-sponsorship %} -{% data reusables.sponsors.developer-sponsored-choose-updates %} -{% data reusables.sponsors.update-sponsorship %} - -### Managing email updates from a sponsored organization - -You can choose whether a sponsored organization can send you email updates about their work. The sponsored organization will not have access to your email address. - -{% data reusables.sponsors.navigate-to-sponsored-org %} -{% data reusables.sponsors.manage-org-sponsorship %} -{% data reusables.sponsors.org-sponsored-choose-updates %} -{% data reusables.sponsors.update-sponsorship %} +- "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" +- "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)" \ No newline at end of file diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization.md b/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization.md index 41edca34c2..3d15b43662 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization.md @@ -25,7 +25,7 @@ To join {% data variables.product.prodname_sponsors %} as an individual contribu ### Completing your sponsored organization profile -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-profile-tab %} {% data reusables.sponsors.short-bio %} {% data reusables.sponsors.add-introduction %} @@ -40,7 +40,7 @@ To join {% data variables.product.prodname_sponsors %} as an individual contribu {% data reusables.sponsors.maximum-tier %} -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} {% data reusables.sponsors.click-add-tier %} {% data reusables.sponsors.tier-price-description %} @@ -54,7 +54,7 @@ As a sponsored organization, you must receive payouts to a dedicated bank accoun {% data reusables.sponsors.double-check-stripe-info %} -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.create-stripe-account %} For more information about setting up Stripe Connect using Open Collective, see [Setting up {% data variables.product.prodname_sponsors %}](https://docs.opencollective.com/help/collectives/github-sponsors) in the Open Collective Docs. @@ -63,7 +63,7 @@ For more information about setting up Stripe Connect using Open Collective, see {% data reusables.sponsors.tax-form-information-org %} -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.settings-tab %} {% data reusables.sponsors.country-of-residence %} {% data reusables.sponsors.overview-tab %} @@ -75,7 +75,7 @@ Before your organization can become a sponsored organization, you must enable 2F ### Submitting your application to {% data variables.product.prodname_dotcom %} for approval -{% data reusables.sponsors.navigate-to-org-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.request-approval %} {% data reusables.sponsors.github-review-app %} diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account.md b/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account.md index ac0981e336..5b14699adc 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account.md @@ -26,7 +26,7 @@ If you have a bank account in a supported region, {% data variables.product.prod After {% data variables.product.prodname_dotcom %} reviews your application, you can set up your sponsored developer profile so that people can start sponsoring you. -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-profile-tab %} {% data reusables.sponsors.short-bio %} {% data reusables.sponsors.add-introduction %} @@ -40,7 +40,7 @@ After {% data variables.product.prodname_dotcom %} reviews your application, you {% data reusables.sponsors.maximum-tier %} -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} {% data reusables.sponsors.click-add-tier %} {% data reusables.sponsors.tier-price-description %} @@ -54,14 +54,14 @@ If you live in a supported region, you can follow these instructions to submit y {% data reusables.sponsors.double-check-stripe-info %} -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.create-stripe-account %} ### Submitting your tax information {% data reusables.sponsors.tax-form-information-dev %} -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.settings-tab %} {% data reusables.sponsors.country-of-residence %} {% data reusables.sponsors.overview-tab %} @@ -73,7 +73,7 @@ Before you can become a sponsored developer, you must enable 2FA on your {% data ### Submitting your application to {% data variables.product.prodname_dotcom %} for approval -{% data reusables.sponsors.navigate-to-dev-sponsors-dashboard %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} 4. Click **Request approval**. ![Request approval button](/assets/images/help/sponsors/request-approval-button.png) diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor.md b/content/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor.md index 05d3f4c105..b985f949c2 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor.md @@ -7,17 +7,32 @@ redirect_from: - /github/supporting-the-open-source-community-with-github-sponsors/sponsoring-a-developer versions: free-pro-team: '*' +permissions: Anyone can sponsor accounts on behalf of their own user account. Organization owners and billing managers can sponsor accounts on behalf of their organization. --- -### About sponsoring developers and organizations +{% data reusables.sponsors.org-sponsors-release-phase %} -{% data reusables.sponsors.sponsorship-details %} {% data reusables.sponsors.no-fees %} For more information, see "[About billing for {% data variables.product.prodname_sponsors %}](/articles/about-billing-for-github-sponsors)." +### About sponsorships -When you sponsor an open source contributor, the change will become effective immediately. {% data reusables.sponsors.prorated-sponsorship %} +{% data reusables.sponsors.sponsorship-details %} -If the sponsored open source contributor retires your tier, the tier will remain in place for you until you choose a different tier or cancel your subscription. For more information, see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)." +You can sponsor an account on behalf of your user account to invest in projects that you personally benefit from. You can sponsor an account on behalf of your organization for many reasons. +- Sustaining specific libraries that your organization's work depends on +- Investing in the ecosystem you rely on as a organization (such as blockchain) +- Developing brand awareness as an organization that values open source +- Thanking open source developers for building libraries that complement the product your organization offers -If the open source contributor you want to sponsor does not have a sponsored developer or organization profile, you can encourage the contributor to create a sponsored developer or organization profile. For more information, see "[Setting up {% data variables.product.prodname_sponsors %} for your user account](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account)" and "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)." +You can use a credit card to sponsor an account on {% data variables.product.product_name %}. If your organization wants to be invoiced, [contact us](https://support.github.com/contact/org-sponsors-waitlist). + +{% data reusables.sponsors.no-fees %} For more information, see "[About billing for {% data variables.product.prodname_sponsors %}](/articles/about-billing-for-github-sponsors)." + +When you sponsor an account using a credit card, the change will become effective immediately. {% data reusables.sponsors.prorated-sponsorship %} + +{% data reusables.sponsors.manage-updates-for-orgs %} + +If the sponsored account retires your tier, the tier will remain in place for you until you choose a different tier or cancel your subscription. For more information, see "[Upgrading a sponsorship](/articles/upgrading-a-sponsorship)" and "[Downgrading a sponsorship](/articles/downgrading-a-sponsorship)." + +If the account you want to sponsor does not have a profile on {% data variables.product.prodname_sponsors %}, you can encourage the account to join. For more information, see "[Setting up {% data variables.product.prodname_sponsors %} for your user account](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account)" and "[Setting up {% data variables.product.prodname_sponsors %} for your organization](/github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization)." {% data reusables.sponsors.sponsorships-not-tax-deductible %} @@ -27,34 +42,23 @@ If the open source contributor you want to sponsor does not have a sponsored dev {% endnote %} -### Sponsoring a developer +### Sponsoring an account -Before you can sponsor a developer, you must have a verified email address. For more information, see "[Verifying your email address](/github/getting-started-with-github/verifying-your-email-address)." +Before you can sponsor an account, you must have a verified email address. For more information, see "[Verifying your email address](/github/getting-started-with-github/verifying-your-email-address)." -1. On {% data variables.product.product_name %}, navigate to the profile of the person you want to sponsor. -2. Under the developer's name, click **Sponsor**. - ![Sponsor button](/assets/images/help/profile/sponsor-button.png) +1. On {% data variables.product.product_name %}, navigate to the profile of the user or organization you want to sponsor. +1. Navigate to your sponsorship dashboard for the account. + - To sponsor a developer, under the developer's name, click **Sponsor**. + ![Sponsor button](/assets/images/help/profile/sponsor-button.png) + - To sponsor an organization, to the right of the the organization's name, click **Sponsor**. + ![Sponsor button](/assets/images/help/sponsors/sponsor-org-button.png) +1. Optionally, on the right side of the page, to sponsor the account on behalf of your organization, use the **Sponsor as** drop-down menu, and click the organization. + ![Drop-down menu to choose the account you'll sponsor as](/assets/images/help/sponsors/sponsor-as-drop-down-menu.png) {% data reusables.sponsors.select-a-tier %} +{% data reusables.sponsors.pay-prorated-amount %} {% data reusables.sponsors.select-sponsorship-billing %} ![Edit payment button](/assets/images/help/sponsors/edit-sponsorship-payment-button.png) {% data reusables.sponsors.who-can-see-your-sponsorship %} ![Radio buttons to choose who can see your sponsorship](/assets/images/help/sponsors/who-can-see-sponsorship.png) -{% data reusables.sponsors.developer-sponsored-choose-updates %} -7. Click **Sponsor _DEVELOPER_**. - ![Sponsor developer button](/assets/images/help/sponsors/sponsor-developer-button.png) - -### Sponsoring an organization - -Before you can sponsor an organization, you must have a verified email address. For more information, see "[Verifying your email address](/github/getting-started-with-github/verifying-your-email-address)." - -1. On {% data variables.product.product_name %}, navigate to the page of the organization you want to sponsor. -2. Next to the organization's name, click **Sponsor**. - ![Sponsor button](/assets/images/help/sponsors/sponsor-org-button.png) -{% data reusables.sponsors.select-a-tier %} -{% data reusables.sponsors.select-sponsorship-billing %} - ![Edit payment button](/assets/images/help/sponsors/edit-org-sponsorship-payment-button.png) -{% data reusables.sponsors.who-can-see-your-sponsorship %} - ![Radio buttons to choose who can see your sponsorship](/assets/images/help/sponsors/who-can-see-org-sponsorship.png) -{% data reusables.sponsors.org-sponsored-choose-updates %} -7. Click **Sponsor _ORGANIZATION_**. - ![Sponsor organization button](/assets/images/help/sponsors/sponsor-org-confirm-button.png) +{% data reusables.sponsors.choose-updates %} +{% data reusables.sponsors.sponsor-account %} diff --git a/content/github/supporting-the-open-source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships.md b/content/github/supporting-the-open-source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships.md index c00a06bca1..3eab334503 100644 --- a/content/github/supporting-the-open-source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships.md +++ b/content/github/supporting-the-open-source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships.md @@ -7,40 +7,29 @@ versions: free-pro-team: '*' --- +### About sponsors and sponsorships + You can view analytics on your current and past sponsorships, the payments you've received from sponsors, and events, such as cancellations and sponsor tier changes for your sponsorships. You can also view activity such as new sponsorships, changes to sponsorships, and canceled sponsorships. You can filter the list of activities by date. You can also export sponsorship data for the account you're viewing in CSV or JSON format. -You access all of this information from your Sponsors dashboard. - -### Viewing your Sponsors dashboard - -1. In the upper-right corner of any page, click your profile photo, then click **{% data variables.product.prodname_sponsors %}**. -![{% data variables.product.prodname_sponsors %} button](/assets/images/help/sponsors/access-github-sponsors-dashboard.png) -2. In the list that's displayed, to the right of the account or organization whose Sponsors dashboard you want to view, click **Dashboard**. -![Developer sponsors dashboard button](/assets/images/help/sponsors/dev-sponsors-dashboard-button.png) - ### Viewing your sponsors and sponsorships -1. Go to your Sponsors dashboard, see [Viewing your Sponsors dashboard](#viewing-your-sponsors-dashboard). -{% data reusables.sponsors.navigate-to-sponsors-tab %} +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} 1. Optionally, to filter your sponsors by tier, use the **Filter** drop-down menu, click **Active tiers** or **Retired tiers**, and select a tier. ![Drop-down menu to filter by tier](/assets/images/help/sponsors/filter-drop-down.png) ### Viewing recent sponsorship activity -1. Go to your Sponsors dashboard, see [Viewing your Sponsors dashboard](#viewing-your-sponsors-dashboard). +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} 1. In the left sidebar, click **Activity**. ![Activity tab](/assets/images/help/sponsors/activity-tab.png) ### Exporting your sponsorship data -1. Go to your Sponsors dashboard, see [Viewing your Sponsors dashboard](#viewing-your-sponsors-dashboard). +If you have sponsors, you can export your sponsorship data. {% data variables.product.prodname_dotcom %} will send you an email with export data for all of your sponsors for the month you select. After the export is complete, you can export another month of data. You can export up to 10 sets of data per hour for any of your sponsored accounts. + +{% data reusables.sponsors.navigate-to-sponsors-dashboard %} {% data reusables.sponsors.navigate-to-sponsors-tab %} 1. Click **Export all**. ![Export all button](/assets/images/help/sponsors/export-all.png) - - This button is not displayed if you don't have any sponsors. - 1. Choose a timeframe and a format for the data you'd like to export, then click **Start export**. - ![Options for data export](/assets/images/help/sponsors/export-your-sponsors.png) - - {% data variables.product.prodname_dotcom %} starts exporting data for all of your sponsors for the month you selected. You'll be emailed shortly with an attachment containing the data. After the export is complete you can export another month of data. You can export up to 10 sets of data an hour for any of your sponsored organizations or user accounts. + ![Options for data export](/assets/images/help/sponsors/export-your-sponsors.png) \ No newline at end of file diff --git a/content/github/visualizing-repository-data-with-graphs/about-the-dependency-graph.md b/content/github/visualizing-repository-data-with-graphs/about-the-dependency-graph.md index ee6e10f5bc..1a66878f1a 100644 --- a/content/github/visualizing-repository-data-with-graphs/about-the-dependency-graph.md +++ b/content/github/visualizing-repository-data-with-graphs/about-the-dependency-graph.md @@ -21,6 +21,10 @@ The dependency graph is a summary of the manifest and lock files stored in a rep When you push a commit to {% data variables.product.product_name %} that changes or adds a supported manifest or lock file to the default branch, the dependency graph is automatically updated.{% if currentVersion == "free-pro-team@latest" %} In addition, the graph is updated when anyone pushes a change to the repository of one of your dependencies.{% endif %} For information on the supported ecosystems and manifest files, see "[Supported package ecosystems](#supported-package-ecosystems)" below. +{% if currentVersion == "free-pro-team@latest" %} +When you create a pull request containing changes to dependencies that targets the default branch, {% data variables.product.prodname_dotcom %} uses the dependency graph to add dependency reviews to the pull request. These indicate whether the dependencies contain vulnerabilities and, if so, the version of the dependency in which the vulnerability was fixed. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)." +{% endif %} + ### Dependencies included The dependency graph includes all the dependencies of a repository that are detailed in the manifest and lock files, or their equivalent, for supported ecosystems. This includes: @@ -41,7 +45,8 @@ You can use the dependency graph to: - Explore the repositories your code depends on{% if currentVersion == "free-pro-team@latest" %}, and those that depend on it{% endif %}. For more information, see "[Exploring the dependencies of a repository](/github/visualizing-repository-data-with-graphs/exploring-the-dependencies-of-a-repository)." {% if currentVersion == "free-pro-team@latest" %} - View a summary of the dependencies used in your organization's repositories in a single dashboard. For more information, see "[Viewing insights for your organization](/articles/viewing-insights-for-your-organization#viewing-organization-dependency-insights)."{% endif %} -- View and update vulnerable dependencies for your repository. The dependency graph lists vulnerable dependencies before other dependencies. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." +- View and update vulnerable dependencies for your repository. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)."{% if currentVersion == "free-pro-team@latest" %} +- See information about vulnerable dependencies in pull requests. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."{% endif %} ### Enabling the dependency graph diff --git a/content/github/working-with-github-support/index.md b/content/github/working-with-github-support/index.md index 176ea10515..1ea83fac6b 100644 --- a/content/github/working-with-github-support/index.md +++ b/content/github/working-with-github-support/index.md @@ -2,6 +2,7 @@ title: Working with GitHub Support redirect_from: - /categories/working-with-github-support + - /forum versions: free-pro-team: '*' --- diff --git a/content/packages/getting-started-with-github-container-registry/about-github-container-registry.md b/content/packages/getting-started-with-github-container-registry/about-github-container-registry.md deleted file mode 100644 index 15721dd10b..0000000000 --- a/content/packages/getting-started-with-github-container-registry/about-github-container-registry.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About GitHub Container Registry -intro: 'The {% data variables.product.prodname_github_container_registry %} allows you to seamlessly host and manage Docker container images in your organization or personal user account on {% data variables.product.prodname_dotcom %}. {% data variables.product.prodname_github_container_registry %} allows you to configure who can manage and access packages using fine-grained permissions.' -product: '{% data reusables.gated-features.packages %}' -versions: - free-pro-team: '*' ---- - -{% note %} - -**Note:** {% data variables.product.prodname_github_container_registry %} is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use {% data variables.product.prodname_github_container_registry %}, you must enable the feature for your account. For more information, see "[Enabling improved container support](/packages/getting-started-with-github-container-registry/enabling-improved-container-support)." - -{% endnote %} - -{% data reusables.package_registry.container-registry-feature-highlights %} - -To share context about your package's use, you can link a repository to your container image on {% data variables.product.prodname_dotcom %}. For more information, see "[Connecting a repository to a container image](/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image)." - -### Supported formats - -The {% data variables.product.prodname_container_registry %} currently supports the following container image formats: - -* [Docker Image Manifest V2, Schema 2](https://docs.docker.com/registry/spec/manifest-v2-2/) -* [Open Container Initiative (OCI) Specifications](https://github.com/opencontainers/image-spec) - -#### Manifest Lists/Image Indexes - -{% data variables.product.prodname_github_container_registry %} also supports [Docker Manifest List](https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list)/[OCI Image Index](https://github.com/opencontainers/image-spec/blob/79b036d80240ae530a8de15e1d21c7ab9292c693/image-index.md) formats which are defined in the Docker V2, Schema 2 and OCI image specifications. - -### Visibility and access permissions for container images - -If you have admin permissions to a container image, you can set the container image to private or public. Public images allow anonymous access and can be pulled without authentication or signing in via the CLI. - -As an admin, you can also grant access permissions for a container image that are separate from the permissions you've set at the organization and repository levels. - -For container images published and owned by a user account, you can give any person an access role. For container images published and owned by an organization, you can give any person or team in the organization an access role. - -| Permission role | Access description | -|-----|----| -| Read | Can download package.
Can read package metadata. | -| Write | Can upload and download this package.
Can read and write package metadata. | -| Admin | Can upload, download, delete, and manage this package.
Can read and write package metadata.
Can grant package permissions. - -For more information, see "[Configuring access control and visibility for container images](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -### About billing for {% data variables.product.prodname_github_container_registry %} - -{% data reusables.package_registry.billing-for-container-registry %} - -### Contacting support - -If you have feedback or feature requests for {% data variables.product.prodname_github_container_registry %}, use the [feedback form](https://support.github.com/contact/feedback?contact%5Bcategory%5D=packages). - -Contact {% data variables.contact.github_support %} about {% data variables.product.prodname_github_container_registry %} using [our contact form](https://support.github.com/contact?form%5Bsubject%5D=Re:%20GitHub%20Packages) if: - -* You experience anything that contradicts the documentation. -* You encounter vague or unclear errors. -* Your published package contains sensitive data, such as GDPR violations, API Keys, or personally-identifying information. diff --git a/content/packages/getting-started-with-github-container-registry/index.md b/content/packages/getting-started-with-github-container-registry/index.md deleted file mode 100644 index f07fd0941c..0000000000 --- a/content/packages/getting-started-with-github-container-registry/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Getting started with GitHub Container Registry -intro: 'Learn about {% data variables.product.prodname_container_registry %} concepts and how to migrate your Docker images from {% data variables.product.prodname_registry %}.' -versions: - free-pro-team: '*' ---- - -{% data reusables.package_registry.container-registry-beta %} - -{% link_in_list /about-github-container-registry %} -{% link_in_list /enabling-improved-container-support %} -{% link_in_list /core-concepts-for-github-container-registry %} -{% link_in_list /migrating-to-github-container-registry-for-docker-images %} - -For more information about configuring, deleting, pushing, or pulling container images, see "[Managing container images with {% data variables.product.prodname_github_container_registry %}](/packages/managing-container-images-with-github-container-registry)." diff --git a/content/packages/guides/about-github-container-registry.md b/content/packages/guides/about-github-container-registry.md new file mode 100644 index 0000000000..7a6984309c --- /dev/null +++ b/content/packages/guides/about-github-container-registry.md @@ -0,0 +1,95 @@ +--- +title: About GitHub Container Registry +intro: 'You can use {% data variables.product.prodname_github_container_registry %} to seamlessly host and manage Docker container images in your organization or personal user account on {% data variables.product.prodname_dotcom %}. {% data variables.product.prodname_github_container_registry %} allows you to configure who can manage and access packages using fine-grained permissions.' +product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/about-github-container-registry + - /packages/managing-container-images-with-github-container-registry +versions: + free-pro-team: '*' +--- + +{% note %} + +**Note:** {% data variables.product.prodname_github_container_registry %} is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use {% data variables.product.prodname_github_container_registry %}, you must enable the feature for your account. For more information, see "[Enabling improved container support](/packages/guides/enabling-improved-container-support)." + +{% endnote %} + +### About {% data variables.product.prodname_github_container_registry %} + +{% data reusables.package_registry.container-registry-feature-highlights %} + +To share context about your package's use, you can link a repository to your container image on {% data variables.product.prodname_dotcom %}. For more information, see "[Connecting a repository to a container image](/packages/guides/connecting-a-repository-to-a-container-image)." + +{% data variables.product.prodname_github_container_registry %} has different hosting locations, permission, and visibility than other package registries. + +| | Package registries | {% data variables.product.prodname_github_container_registry %} | +|----|----|----| +| Hosting locations | You can host multiple packages in one repository. | You can host multiple container images in one organization or user account. | +| Permissions | Each package inherits the permissions of the repository where the package is hosted.

For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | For each container image, you can choose the access level that others have. The permissions for container image access are separate from your organization and repository permissions. +Visibility | {% data reusables.package_registry.public-or-private-packages %} | You can set the visibility of each of your container images. A private container image is only visible to people and teams who are given access within your organization. A public container image is visible to anyone. | +Anonymous access | N/A | You can access public container images anonymously. + +For more information, see "[About scopes and permissions for {% data variables.product.prodname_github_container_registry %}](#about-scopes-and-permissions-for-github-container-registry)." + +### Supported formats + +The {% data variables.product.prodname_container_registry %} currently supports the following container image formats: + +* [Docker Image Manifest V2, Schema 2](https://docs.docker.com/registry/spec/manifest-v2-2/) +* [Open Container Initiative (OCI) Specifications](https://github.com/opencontainers/image-spec) + +The {% data variables.product.prodname_github_container_registry %} hosts containers at `ghcr.io/OWNER/IMAGE-NAME`. + +| Package client | Language | Package format | Description | +| --- | --- | --- | --- | +| Docker CLI | N/A | `Dockerfile` | Docker container support. | + + +#### Manifest Lists/Image Indexes + +{% data variables.product.prodname_github_container_registry %} also supports [Docker Manifest List](https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list)/[OCI Image Index](https://github.com/opencontainers/image-spec/blob/79b036d80240ae530a8de15e1d21c7ab9292c693/image-index.md) formats which are defined in the Docker V2, Schema 2 and OCI image specifications. + +### Visibility and access permissions for container images + +If you have admin permissions to a container image, you can set the container image to private or public. Public images allow anonymous access and can be pulled without authentication or signing in via the CLI. + +As an admin, you can also grant access permissions for a container image that are separate from the permissions you've set at the organization and repository levels. + +For container images published and owned by a user account, you can give any person an access role. For container images published and owned by an organization, you can give any person or team in the organization an access role. + +| Permission role | Access description | +|-----|----| +| Read | Can download package.
Can read package metadata. | +| Write | Can upload and download this package.
Can read and write package metadata. | +| Admin | Can upload, download, delete, and manage this package.
Can read and write package metadata.
Can grant package permissions. + +For more information, see "[Configuring access control and visibility for container images](/packages/guides/configuring-access-control-and-visibility-for-container-images)." + +### About scopes and permissions for {% data variables.product.prodname_github_container_registry %} + +To use or manage a package hosted by a package registry, you must use a token with the appropriate scope, and your user account must have appropriate permissions for that repository. + +| Scope | Description | +| --- | --- | +|`read:packages`| Download and install container images from {% data variables.product.prodname_github_container_registry %} | +|`write:packages`| Upload and publish container images to {% data variables.product.prodname_github_container_registry %} | +| `delete:packages` | Delete specified versions of private or public container images from {% data variables.product.prodname_github_container_registry %}. For more information, see "[Deleting a container image](/packages/guides/deleting-a-container-image)." | + +To learn about available scopes and permissions for container images, see "[Configuring access control and visibility for container images](/packages/guides/configuring-access-control-and-visibility-for-container-images)." + +For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token/)" and "[Available scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)." + +### About billing for {% data variables.product.prodname_github_container_registry %} + +{% data reusables.package_registry.billing-for-container-registry %} + +### Contacting support + +If you have feedback or feature requests for {% data variables.product.prodname_github_container_registry %}, use the [feedback form](https://support.github.com/contact/feedback?contact%5Bcategory%5D=packages). + +Contact {% data variables.contact.github_support %} about {% data variables.product.prodname_github_container_registry %} using [our contact form](https://support.github.com/contact?form%5Bsubject%5D=Re:%20GitHub%20Packages) if: + +* You experience anything that contradicts the documentation. +* You encounter vague or unclear errors. +* Your published package contains sensitive data, such as GDPR violations, API Keys, or personally-identifying information. diff --git a/content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md b/content/packages/guides/configuring-access-control-and-visibility-for-container-images.md similarity index 97% rename from content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md rename to content/packages/guides/configuring-access-control-and-visibility-for-container-images.md index 8779fdf8ef..bff3dfee0c 100644 --- a/content/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images.md +++ b/content/packages/guides/configuring-access-control-and-visibility-for-container-images.md @@ -2,6 +2,8 @@ title: Configuring access control and visibility for container images intro: 'Choose who has read, write, or admin access to your container image and the visibility of your container images on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images versions: free-pro-team: '*' --- diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md b/content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md similarity index 96% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md rename to content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md index 0d8c2df1cc..62ffeb833c 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-apache-maven-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-apache-maven-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-apache-maven-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-apache-maven-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -188,5 +189,5 @@ To install an Apache Maven package from {% data variables.product.prodname_regis ### Further reading -- "[Configuring Gradle for use with {% data variables.product.prodname_registry %}](/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages)" -- "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package/)" +- "[Configuring Gradle for use with {% data variables.product.prodname_registry %}](/packages/guides/configuring-gradle-for-use-with-github-packages)" +- "[Deleting a package](/packages/manage-packages/deleting-a-package/)" diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md b/content/packages/guides/configuring-docker-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md rename to content/packages/guides/configuring-docker-for-use-with-github-packages.md index d31c4e2c4a..ce7cedc3e8 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-docker-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-docker-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-docker-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-docker-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md b/content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md rename to content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md index a5fa36cc7e..1c1369de9f 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-dotnet-cli-for-use-with-github-packages.md @@ -7,6 +7,7 @@ redirect_from: - /github/managing-packages-with-github-package-registry/configuring-nuget-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-nuget-for-use-with-github-packages - /github/managing-packages-with-github-packages/configuring-dotnet-cli-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md b/content/packages/guides/configuring-gradle-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md rename to content/packages/guides/configuring-gradle-for-use-with-github-packages.md index 73502d9a86..d84b907b01 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-gradle-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-gradle-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-gradle-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-gradle-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md b/content/packages/guides/configuring-npm-for-use-with-github-packages.md similarity index 99% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md rename to content/packages/guides/configuring-npm-for-use-with-github-packages.md index 3ecb00119f..f96a8d68c6 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-npm-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-npm-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-npm-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md b/content/packages/guides/configuring-rubygems-for-use-with-github-packages.md similarity index 98% rename from content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md rename to content/packages/guides/configuring-rubygems-for-use-with-github-packages.md index b0e21632a8..98ab1d6cb9 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages.md +++ b/content/packages/guides/configuring-rubygems-for-use-with-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/configuring-rubygems-for-use-with-github-package-registry - /github/managing-packages-with-github-package-registry/configuring-rubygems-for-use-with-github-package-registry - /github/managing-packages-with-github-packages/configuring-rubygems-for-use-with-github-packages + - /packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md b/content/packages/guides/connecting-a-repository-to-a-container-image.md similarity index 96% rename from content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md rename to content/packages/guides/connecting-a-repository-to-a-container-image.md index 36623b8ecf..051f92283a 100644 --- a/content/packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image.md +++ b/content/packages/guides/connecting-a-repository-to-a-container-image.md @@ -2,6 +2,8 @@ title: Connecting a repository to a container image intro: 'You can link a repository with a container image locally and on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image versions: free-pro-team: '*' --- diff --git a/content/packages/guides/container-guides-for-github-packages.md b/content/packages/guides/container-guides-for-github-packages.md new file mode 100644 index 0000000000..31b8f63889 --- /dev/null +++ b/content/packages/guides/container-guides-for-github-packages.md @@ -0,0 +1,10 @@ +--- +title: Container guides for GitHub Packages +shortTitle: Container guides for GitHub Packages +intro: 'You can publish and retrieve Docker images using {% data variables.product.prodname_registry %}.' +mapTopic: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + diff --git a/content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md b/content/packages/guides/deleting-a-container-image.md similarity index 94% rename from content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md rename to content/packages/guides/deleting-a-container-image.md index 1ca7bff3fb..11c6cabf81 100644 --- a/content/packages/managing-container-images-with-github-container-registry/deleting-a-container-image.md +++ b/content/packages/guides/deleting-a-container-image.md @@ -2,6 +2,8 @@ title: Deleting a container image intro: 'You can delete a version of a private container image using GraphQL or on {% data variables.product.prodname_dotcom %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/deleting-a-container-image versions: free-pro-team: '*' --- diff --git a/content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md b/content/packages/guides/enabling-improved-container-support.md similarity index 96% rename from content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md rename to content/packages/guides/enabling-improved-container-support.md index dbfccede7f..6b2aad74f0 100644 --- a/content/packages/getting-started-with-github-container-registry/enabling-improved-container-support.md +++ b/content/packages/guides/enabling-improved-container-support.md @@ -2,6 +2,8 @@ title: Enabling improved container support intro: 'To use {% data variables.product.prodname_github_container_registry %}, you must enable it for your user or organization account.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/enabling-improved-container-support versions: free-pro-team: '*' --- diff --git a/content/packages/guides/index.md b/content/packages/guides/index.md new file mode 100644 index 0000000000..fee5252736 --- /dev/null +++ b/content/packages/guides/index.md @@ -0,0 +1,33 @@ +--- +title: Guides +shortTitle: Guides +intro: 'These guides help you configure {% data variables.product.prodname_actions %} or your package client to work with {% data variables.product.prodname_registry %}.' +redirect_from: + - /github/managing-packages-with-github-packages/using-github-packages-with-your-projects-ecosystem + - /packages/using-github-packages-with-your-projects-ecosystem +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +{% data reusables.package_registry.packages-ghes-release-stage %} + +### Table of Contents + +{% topic_link_in_list /package-client-guides-for-github-packages %} + {% link_in_list /using-github-packages-with-github-actions %} + {% link_in_list /configuring-apache-maven-for-use-with-github-packages %} + {% link_in_list /configuring-gradle-for-use-with-github-packages %} + {% link_in_list /configuring-npm-for-use-with-github-packages %} + {% link_in_list /configuring-dotnet-cli-for-use-with-github-packages %} + {% link_in_list /configuring-rubygems-for-use-with-github-packages %} +{% topic_link_in_list /container-guides-for-github-packages %} + {% link_in_list /configuring-docker-for-use-with-github-packages %} + {% link_in_list /about-github-container-registry %} + {% link_in_list /migrating-to-github-container-registry-for-docker-images %} + {% link_in_list /enabling-improved-container-support %} + {% link_in_list /configuring-access-control-and-visibility-for-container-images %} + {% link_in_list /connecting-a-repository-to-a-container-image %} + {% link_in_list /pushing-and-pulling-docker-images %} + {% link_in_list /deleting-a-container-image %} + diff --git a/content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md b/content/packages/guides/migrating-to-github-container-registry-for-docker-images.md similarity index 98% rename from content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md rename to content/packages/guides/migrating-to-github-container-registry-for-docker-images.md index 8f647b4825..239f2d6ae2 100644 --- a/content/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images.md +++ b/content/packages/guides/migrating-to-github-container-registry-for-docker-images.md @@ -2,6 +2,8 @@ title: Migrating to GitHub Container Registry for Docker images intro: 'If you''ve used the GitHub Packages Docker registry to store Docker images, you can migrate to the new {% data variables.product.prodname_container_registry %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images versions: free-pro-team: '*' --- diff --git a/content/packages/guides/package-client-guides-for-github-packages.md b/content/packages/guides/package-client-guides-for-github-packages.md new file mode 100644 index 0000000000..6f77e8b9bd --- /dev/null +++ b/content/packages/guides/package-client-guides-for-github-packages.md @@ -0,0 +1,10 @@ +--- +title: Package client guides for GitHub Packages +shortTitle: Package client guides for GitHub Packages +intro: 'You can publish and retrieve package client images using {% data variables.product.prodname_registry %}.' +mapTopic: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + diff --git a/content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md b/content/packages/guides/pushing-and-pulling-docker-images.md similarity index 97% rename from content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md rename to content/packages/guides/pushing-and-pulling-docker-images.md index 5dd0f067e2..8e38906fbd 100644 --- a/content/packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images.md +++ b/content/packages/guides/pushing-and-pulling-docker-images.md @@ -2,6 +2,8 @@ title: Pushing and pulling Docker images intro: 'You can store and manage Docker images in {% data variables.product.prodname_github_container_registry %}.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images versions: free-pro-team: '*' --- diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md b/content/packages/guides/using-github-packages-with-github-actions.md similarity index 97% rename from content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md rename to content/packages/guides/using-github-packages-with-github-actions.md index 8875879a16..bb4ed48ec6 100644 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions.md +++ b/content/packages/guides/using-github-packages-with-github-actions.md @@ -4,6 +4,7 @@ intro: 'You can configure a workflow in {% data variables.product.prodname_actio product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/using-github-packages-with-github-actions + - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions versions: free-pro-team: '*' enterprise-server: '>=2.22' diff --git a/content/packages/index.md b/content/packages/index.md index e00d89f22a..da52606f5d 100644 --- a/content/packages/index.md +++ b/content/packages/index.md @@ -2,31 +2,43 @@ title: GitHub Packages Documentation shortTitle: GitHub Packages intro: 'Learn to safely publish and consume packages, store your packages alongside your code, and share your packages privately with your team or publicly with the open source community. You can also automate your packages with {% data variables.product.prodname_actions %}.' +introLinks: + quickstart: /packages/quickstart + reference: /packages/manage-packages featuredLinks: - gettingStarted: - - /packages/publishing-and-managing-packages/about-github-packages - - /packages/getting-started-with-github-container-registry/about-github-container-registry - - /packages/getting-started-with-github-container-registry - - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images - - /packages/publishing-and-managing-packages/publishing-a-package - - /packages/publishing-and-managing-packages/installing-a-package + guides: + - /packages/learn-github-packages + - /packages/guides/using-github-packages-with-github-actions + - /packages/manage-packages/installing-a-package popular: - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages - - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images - - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions + - /packages/guides/configuring-npm-for-use-with-github-packages + - /packages/learn-github-packages/about-github-packages + - /packages/guides/configuring-apache-maven-for-use-with-github-packages + guideCards: + - /packages/guides/configuring-npm-for-use-with-github-packages + - /packages/guides/enabling-improved-container-support + - /packages/guides/configuring-rubygems-for-use-with-github-packages +changelog: + - title: Packages container support is an opt-in beta + date: '2020-11-17' + href: https://docs.github.com/packages/getting-started-with-github-container-registry/enabling-improved-container-support + - title: Organization admins access to containers + date: '2020-11-16' + href: https://github.blog/changelog/2020-11-16-packages-organization-admins-access-to-containers/ + - title: Packages now respects IP allow list settings + date: '2020-11-12' + href: https://github.blog/changelog/2020-11-12-packages-now-respects-ip-allow-list-settings/ redirect_from: - /github/managing-packages-with-github-packages - /categories/managing-packages-with-github-package-registry - /github/managing-packages-with-github-package-registry +layout: product-landing versions: free-pro-team: '*' enterprise-server: '>=2.22' --- -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% link_with_intro /getting-started-with-github-container-registry %} -{% link_with_intro /managing-container-images-with-github-container-registry %} -{% link_with_intro /publishing-and-managing-packages %} -{% link_with_intro /using-github-packages-with-your-projects-ecosystem %} + + + + diff --git a/content/packages/publishing-and-managing-packages/about-github-packages.md b/content/packages/learn-github-packages/about-github-packages.md similarity index 72% rename from content/packages/publishing-and-managing-packages/about-github-packages.md rename to content/packages/learn-github-packages/about-github-packages.md index 433a30c1cf..1e2ef5b463 100644 --- a/content/packages/publishing-and-managing-packages/about-github-packages.md +++ b/content/packages/learn-github-packages/about-github-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/about-github-package-registry - /github/managing-packages-with-github-package-registry/about-github-package-registry - /github/managing-packages-with-github-packages/about-github-packages + - /packages/publishing-and-managing-packages/about-github-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -22,7 +23,7 @@ You can integrate {% data variables.product.prodname_registry %} with {% data va {% data variables.product.prodname_registry %} offers different package registries for commonly used packages, such as for Node, RubyGems, Apache Maven, Gradle, and Nuget. {% if currentVersion == "free-pro-team@latest" %} -{% data variables.product.prodname_registry %} also offers a {% data variables.product.prodname_container_registry %} designed to support the unique needs of container images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." +{% data variables.product.prodname_registry %} also offers a {% data variables.product.prodname_container_registry %} designed to support the unique needs of container images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/guides/about-github-container-registry)." {% data reusables.package_registry.container-registry-beta %} @@ -32,34 +33,16 @@ You can integrate {% data variables.product.prodname_registry %} with {% data va #### Viewing packages -You can review the package's README, some metadata like licensing, download statistics, version history, and more on {% data variables.product.product_name %}. For more information, see "[Viewing packages](/packages/publishing-and-managing-packages/viewing-packages)." +You can review the package's README, some metadata like licensing, download statistics, version history, and more on {% data variables.product.product_name %}. For more information, see "[Viewing packages](/packages/manage-packages/viewing-packages)." #### About package permissions and visibility -{% if currentVersion == "free-pro-team@latest" %} - -| | Package registries | {% data variables.product.prodname_github_container_registry %} | -|----|----|----| -| Hosting locations | You can host multiple packages in one repository. | You can host multiple container images in one organization or user account. | -| Permissions | Each package inherits the permissions of the repository where the package is hosted.

For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | For each container image, you can choose the access level that others have. The permissions for container image access are separate from your organization and repository permissions. -Visibility | {% data reusables.package_registry.public-or-private-packages %} | You can set the visibility of each of your container images. A private container image is only visible to people and teams who are given access within your organization. A public container image is visible to anyone. | -Anonymous access | N/A | You can access public container images anonymously. - -{% else %} | | Package registries | |----|----| | Hosting locations | You can host multiple packages in one repository. | | Permissions | Each package inherits the permissions of the repository where the package is hosted.

For example, anyone with read permissions for a repository can install a package as a dependency in a project, and anyone with write permissions can publish a new package version. | | Visibility | {% data reusables.package_registry.public-or-private-packages %} | -{% endif %} - -{% if currentVersion == "free-pro-team@latest" %} - -For more information about permissions and visibility for {% data variables.product.prodname_github_container_registry %}, see "[Configuring access control and visibility for containers](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -{% endif %} - {% if currentVersion == "free-pro-team@latest" %} ### About billing for {% data variables.product.prodname_registry %} @@ -71,19 +54,6 @@ For more information about permissions and visibility for {% data variables.prod ### Supported clients and formats {% data variables.product.prodname_registry %} uses the native package tooling commands you're already familiar with to publish and install package versions. - -{% if currentVersion == "free-pro-team@latest" %} -#### Support for {% data variables.product.prodname_github_container_registry %} - -The {% data variables.product.prodname_github_container_registry %} hosts containers at `ghcr.io/OWNER/IMAGE-NAME`. - -| Package client | Language | Package format | Description | -| --- | --- | --- | --- | -| Docker CLI | N/A | `Dockerfile` | Docker container support. | - -For more information about the container support offered by {% data variables.product.prodname_github_container_registry %}, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." -{% endif %} - #### Support for package registries {% if currentVersion == "free-pro-team@latest" %} @@ -142,34 +112,22 @@ For more information about subdomain isolation, see "[Enabling subdomain isolati {% endif %} -For more information about configuring your package client for use with {% data variables.product.prodname_registry %}, see "[Using {% data variables.product.prodname_registry %} with your project's ecosystem](/packages/using-github-packages-with-your-projects-ecosystem)." +For more information about configuring your package client for use with {% data variables.product.prodname_registry %}, see "[Package client guides for {% data variables.product.prodname_registry %}](/packages/guides/package-client-guides-for-github-packages)." +{% if currentVersion == "free-pro-team@latest" %} +For more information about Docker and {% data variables.product.prodname_github_container_registry %}, see "[Container guides for {% data variables.product.prodname_registry %}](/packages/guides/container-guides-for-github-packages)." +{% endif %} ### Authenticating to {% data variables.product.prodname_registry %} {% data reusables.package_registry.authenticate-packages %} -{% if currentVersion == "free-pro-team@latest" %} -### About scopes and permissions for {% data variables.product.prodname_github_container_registry %} - -| Scope | Description | -| --- | --- | -|`read:packages`| Download and install container images from {% data variables.product.prodname_github_container_registry %} | -|`write:packages`| Upload and publish container images to {% data variables.product.prodname_github_container_registry %} | -| `delete:packages` | Delete specified versions of private or public container images from {% data variables.product.prodname_github_container_registry %}. For more information, see "[Deleting a container image](/packages/managing-container-images-with-github-container-registry/deleting-a-container-image)." | - -To learn about available scopes and permissions for container images, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)" or "[Configuring access control and visibility for container images](/packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images)." - -For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token/)" and "[Available scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)." - -{% endif %} - ### About scopes and permissions for package registries To use or manage a package hosted by a package registry, you must use a token with the appropriate scope, and your user account must have appropriate permissions for that repository. For example: - To download and install packages from a repository, your token must have the `read:packages` scope, and your user account must have read permissions for the repository. -- To delete a specified version of a private package on {% data variables.product.product_name %}, your token must have the `delete:packages` and `repo` scope. Public packages cannot be deleted. For more information, see "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package)." +- To delete a specified version of a private package on {% data variables.product.product_name %}, your token must have the `delete:packages` and `repo` scope. Public packages cannot be deleted. For more information, see "[Deleting a package](/packages/manage-packages/deleting-a-package)." | Scope | Description | Repository permissions | | --- | --- | --- | @@ -187,7 +145,7 @@ For more information, see: ### Managing packages -You can delete a version of a private package on {% data variables.product.product_name %} or using the GraphQL API. When you use the GraphQL API to query and delete private packages, you must use the same token you use to authenticate to {% data variables.product.prodname_registry %}. For more information, see "[Deleting a package](/packages/publishing-and-managing-packages/deleting-a-package)" and "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)." +You can delete a version of a private package on {% data variables.product.product_name %} or using the GraphQL API. When you use the GraphQL API to query and delete private packages, you must use the same token you use to authenticate to {% data variables.product.prodname_registry %}. For more information, see "[Deleting a package](/packages/manage-packages/deleting-a-package)" and "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)." You can configure webhooks to subscribe to package-related events, such as when a package is published or updated. For more information, see the "[`package` webhook event](/webhooks/event-payloads/#package)." diff --git a/content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md b/content/packages/learn-github-packages/core-concepts-for-github-packages.md similarity index 77% rename from content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md rename to content/packages/learn-github-packages/core-concepts-for-github-packages.md index 0eb31c6327..07b7774cd7 100644 --- a/content/packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry.md +++ b/content/packages/learn-github-packages/core-concepts-for-github-packages.md @@ -1,16 +1,15 @@ --- -title: Core concepts for GitHub Container Registry -intro: 'Below is a list of common {% data variables.product.prodname_github_container_registry %} terms we use across our sites and documentation.' +title: Core concepts for GitHub Packages +intro: 'Below is a list of common {% data variables.product.prodname_registry %} terms we use across our sites and documentation.' product: '{% data reusables.gated-features.packages %}' +redirect_from: + - /packages/getting-started-with-github-container-registry/core-concepts-for-github-container-registry versions: free-pro-team: '*' + enterprise-server: '>=2.22' --- -{% data reusables.package_registry.container-registry-beta %} - -### {% data variables.product.prodname_github_container_registry %} - -The {% data variables.product.prodname_github_container_registry %} is a registry for containers with support for Docker images. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." +{% data reusables.package_registry.packages-ghes-release-stage %} ### Package diff --git a/content/packages/learn-github-packages/index.md b/content/packages/learn-github-packages/index.md new file mode 100644 index 0000000000..a21e10fe4c --- /dev/null +++ b/content/packages/learn-github-packages/index.md @@ -0,0 +1,16 @@ +--- +title: Learn GitHub Packages +shortTitle: Learn GitHub Packages +intro: 'You can find out more about GitHub Packages, including publishing new packages to {% data variables.product.prodname_registry %}.' +redirect_from: + - /packages/getting-started-with-github-container-registry +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +{% data reusables.package_registry.packages-ghes-release-stage %} + +{% link_in_list /about-github-packages %} +{% link_in_list /core-concepts-for-github-packages %} +{% link_in_list /publishing-a-package %} diff --git a/content/packages/publishing-and-managing-packages/publishing-a-package.md b/content/packages/learn-github-packages/publishing-a-package.md similarity index 97% rename from content/packages/publishing-and-managing-packages/publishing-a-package.md rename to content/packages/learn-github-packages/publishing-a-package.md index e44f7a9000..9294af45b6 100644 --- a/content/packages/publishing-and-managing-packages/publishing-a-package.md +++ b/content/packages/learn-github-packages/publishing-a-package.md @@ -4,6 +4,7 @@ intro: 'You can publish a package to {% data variables.product.prodname_registry product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/publishing-a-package + - /packages/publishing-and-managing-packages/publishing-a-package permissions: Anyone with write permissions for a repository can publish a package to that repository. versions: free-pro-team: '*' diff --git a/content/packages/publishing-and-managing-packages/deleting-a-package.md b/content/packages/manage-packages/deleting-a-package.md similarity index 96% rename from content/packages/publishing-and-managing-packages/deleting-a-package.md rename to content/packages/manage-packages/deleting-a-package.md index 3ac14a5879..b820d5f65a 100644 --- a/content/packages/publishing-and-managing-packages/deleting-a-package.md +++ b/content/packages/manage-packages/deleting-a-package.md @@ -4,6 +4,7 @@ intro: 'You can delete a version of a private package using GraphQL or on {% dat product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/deleting-a-package + - /packages/publishing-and-managing-packages/deleting-a-package versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -14,7 +15,7 @@ versions: {% if currentVersion == "free-pro-team@latest" %} ### About container image deletion -To delete a container image package on {% data variables.product.product_name %}, see "[Deleting a container image](/packages/managing-container-images-with-github-container-registry/deleting-a-container-image)." +To delete a container image package on {% data variables.product.product_name %}, see "[Deleting a container image](/packages/guides/deleting-a-container-image)." {% endif %} diff --git a/content/packages/publishing-and-managing-packages/index.md b/content/packages/manage-packages/index.md similarity index 75% rename from content/packages/publishing-and-managing-packages/index.md rename to content/packages/manage-packages/index.md index e69cc46f75..7f313028a1 100644 --- a/content/packages/publishing-and-managing-packages/index.md +++ b/content/packages/manage-packages/index.md @@ -1,9 +1,11 @@ --- -title: Publishing and managing packages -shortTitle: Publishing and managing packages +title: Managing GitHub packages +shortTitle: Managing GitHub packages intro: 'You can publish new packages to {% data variables.product.prodname_registry %}, view and install existing packages, and, in special circumstances, delete existing packages.' redirect_from: - /github/managing-packages-with-github-packages/publishing-and-managing-packages + - /github/packages/publishing-and-managing-packages + - /packages/publishing-and-managing-packages versions: free-pro-team: '*' enterprise-server: '>=2.22' @@ -11,8 +13,6 @@ versions: {% data reusables.package_registry.packages-ghes-release-stage %} -{% link_in_list /about-github-packages %} -{% link_in_list /publishing-a-package %} {% link_in_list /viewing-packages %} {% link_in_list /installing-a-package %} {% link_in_list /deleting-a-package %} diff --git a/content/packages/publishing-and-managing-packages/installing-a-package.md b/content/packages/manage-packages/installing-a-package.md similarity index 96% rename from content/packages/publishing-and-managing-packages/installing-a-package.md rename to content/packages/manage-packages/installing-a-package.md index cb2b1f16ad..007e344089 100644 --- a/content/packages/publishing-and-managing-packages/installing-a-package.md +++ b/content/packages/manage-packages/installing-a-package.md @@ -4,6 +4,7 @@ intro: 'You can install a package from {% data variables.product.prodname_regist product: '{% data reusables.gated-features.packages %}' redirect_from: - /github/managing-packages-with-github-packages/installing-a-package + - /packages/publishing-and-managing-packages/installing-a-package permissions: Anyone with read permissions for a repository can install a package from that repository. versions: free-pro-team: '*' diff --git a/content/packages/publishing-and-managing-packages/viewing-packages.md b/content/packages/manage-packages/viewing-packages.md similarity index 97% rename from content/packages/publishing-and-managing-packages/viewing-packages.md rename to content/packages/manage-packages/viewing-packages.md index 55ba29e418..d61604627e 100644 --- a/content/packages/publishing-and-managing-packages/viewing-packages.md +++ b/content/packages/manage-packages/viewing-packages.md @@ -6,6 +6,7 @@ redirect_from: - /articles/viewing-a-repositorys-packages - /github/managing-packages-with-github-packages/publishing-and-managing-packages/viewing-a-repositorys-packages - /github/managing-packages-with-github-packages/viewing-packages + - /packages/publishing-and-managing-packages/viewing-packages permissions: Anyone with read permissions to a repository can view the repository's packages. versions: free-pro-team: '*' diff --git a/content/packages/managing-container-images-with-github-container-registry/index.md b/content/packages/managing-container-images-with-github-container-registry/index.md deleted file mode 100644 index c556ba7b51..0000000000 --- a/content/packages/managing-container-images-with-github-container-registry/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Managing container images with GitHub Container Registry -intro: 'Learn how to manage container images using a supported CLI or on {% data variables.product.prodname_dotcom %}.' -versions: - free-pro-team: '*' ---- - -{% link_in_list /configuring-access-control-and-visibility-for-container-images %} -{% link_in_list /connecting-a-repository-to-a-container-image %} -{% link_in_list /pushing-and-pulling-docker-images %} -{% link_in_list /deleting-a-container-image %} diff --git a/content/packages/quickstart.md b/content/packages/quickstart.md new file mode 100644 index 0000000000..cf353a4d1b --- /dev/null +++ b/content/packages/quickstart.md @@ -0,0 +1,109 @@ +--- +title: Quickstart for GitHub Packages +intro: 'Publish to {% data variables.product.prodname_registry %} in 5 minutes or less with {% data variables.product.prodname_actions %}.' +allowTitleToDifferFromFilename: true +versions: + free-pro-team: '*' + enterprise-server: '>=2.22' +--- + +### Introduction + +You only need an existing {% data variables.product.prodname_dotcom %} repository to publish a package to {% data variables.product.prodname_registry %}. In this guide, you'll create a {% data variables.product.prodname_actions %} workflow to test your code and then publish it to {% data variables.product.prodname_registry %}. Feel free to create a new repository for this Quickstart. You can use it to test this and future {% data variables.product.prodname_actions %} workflows. + +### Publishing your package + +1. Create a new repository on {% data variables.product.prodname_dotcom %}, adding the `.gitignore` for Node. Create a private repository if you’d like to delete this package later, public packages cannot be deleted. For more information, see "[Creating a new repository](/github/creating-cloning-and-archiving-repositories/creating-a-new-repository)." +2. Clone the repository to your local machine. + {% raw %} + ```shell + $ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git + $ cd YOUR-REPOSITORY + ``` + {% endraw %} +3. Create an `index.js` file and add a basic alert to say "Hello world!" + {% raw %} + ```javascript{:copy} + alert("Hello, World!"); + ``` + {% endraw %} +4. Initialize an npm package. In the package initialization wizard, enter your package with the name: _`@YOUR-USERNAME/YOUR-REPOSITORY`_, and set the test script to `exit 0` if you do not have any tests. Commit your changes and push them to {% data variables.product.prodname_dotcom %}. + {% raw %} + ```shell + $ npm init + ... + package name: @YOUR-USERNAME/YOUR-REPOSITORY + ... + test command: exit 0 + ... + + $ npm install + $ git add index.js package.json package-lock.json + $ git commit -m "initialize npm package" + $ git push + ``` + {% endraw %} +5. From your repository on {% data variables.product.prodname_dotcom %}, create a new file in the `.github/workflows` directory named `release-package.yml`. For more information, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)." +6. Copy the following YAML content into the `release-package.yml` file. + {% raw %} + ```yaml{:copy} + name: Node.js Package + + on: + release: + types: [created] + + jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + with: + node-version: 12 + - run: npm ci + - run: npm test + + publish-gpr: + needs: build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + with: + node-version: 12 + registry-url: https://npm.pkg.github.com/ + - run: npm ci + - run: npm publish + env: + NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} + ``` + {% endraw %} +7. Scroll to the bottom of the page and select **Create a new branch for this commit and start a pull request**. Then, to create a pull request, click **Propose new file**. +8. **Merge** the pull request. +9. Navigate to the **Code** tab and create a new release to test the workflow. For more information, see "[Managing releases in a repository](/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release)." + +Creating a new release in your repository triggers the workflow to build and test your code. If the tests pass, then the package will be published to {% data variables.product.prodname_registry %}. + +### Viewing your published package + +Packages are published at the repository level. You can see all the packages in a repository and search for a specific package. + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.package_registry.packages-from-code-tab %} +{% data reusables.package_registry.navigate-to-packages %} + + +### Installing a published package + +Now that you've published the package, you'll want to use it as a dependency across your projects. For more information, see "[Configuring npm for use with {% data variables.product.prodname_registry %}](/packages/guides/configuring-npm-for-use-with-github-packages#installing-a-package)." + +### Next steps + +The basic workflow you just added runs any time a new release is created in your repository. But, this is only the beginning of what you can do with {% data variables.product.prodname_registry %}. You can publish your package to multiple registries with a single workflow, trigger the workflow to run on different events such as a merged pull request, manage containers, and more. + +Combining {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %} can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %}: + +- "[Learn {% data variables.product.prodname_registry %}](/packages/learn-github-packages)" for an in-depth tutorial on GitHub Packages +- "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)" for an in-depth tutorial on GitHub Actions +- "[Guides](/packages/guides)" for specific uses cases and examples diff --git a/content/packages/using-github-packages-with-your-projects-ecosystem/index.md b/content/packages/using-github-packages-with-your-projects-ecosystem/index.md deleted file mode 100644 index 02c88cf632..0000000000 --- a/content/packages/using-github-packages-with-your-projects-ecosystem/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Using GitHub Packages with your project's ecosystem -shortTitle: Using GitHub Packages with your project's ecosystem -intro: 'You can configure {% data variables.product.prodname_actions %} or your package client to work with {% data variables.product.prodname_registry %}.' -redirect_from: - - /github/managing-packages-with-github-packages/using-github-packages-with-your-projects-ecosystem -versions: - free-pro-team: '*' - enterprise-server: '>=2.22' ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% link_in_list /using-github-packages-with-github-actions %} -{% link_in_list /configuring-docker-for-use-with-github-packages %} -{% link_in_list /configuring-apache-maven-for-use-with-github-packages %} -{% link_in_list /configuring-gradle-for-use-with-github-packages %} -{% link_in_list /configuring-npm-for-use-with-github-packages %} -{% link_in_list /configuring-dotnet-cli-for-use-with-github-packages %} -{% link_in_list /configuring-rubygems-for-use-with-github-packages %} diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index 30cc142a97..0dce111619 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -301,18 +301,22 @@ gem: ### Pagination Requests that return multiple items will be paginated to 30 items by -default. You can specify further pages with the `?page` parameter. For some -resources, you can also set a custom page size up to 100 with the `?per_page` parameter. -Note that for technical reasons not all endpoints respect the `?per_page` parameter, +default. You can specify further pages with the `page` parameter. For some +resources, you can also set a custom page size up to 100 with the `per_page` parameter. +Note that for technical reasons not all endpoints respect the `per_page` parameter, see [events](/rest/reference/activity#events) for example. ```shell $ curl '{% data variables.product.api_url_pre %}/user/repos?page=2&per_page=100' ``` -Note that page numbering is 1-based and that omitting the `?page` +Note that page numbering is 1-based and that omitting the `page` parameter will return the first page. +Some endpoints use cursor-based pagination. A cursor is a string that points to a location in the result set. +With cursor-based pagination, there is no fixed concept of "pages" in the result set, so you can't navigate to a specific page. +Instead, you can traverse the results by using the `before` or `after` parameters. + For more information on pagination, check out our guide on [Traversing with Pagination][pagination-guide]. #### Link header @@ -323,13 +327,17 @@ For more information on pagination, check out our guide on [Traversing with Pagi {% endnote %} -The [Link header](http://tools.ietf.org/html/rfc5988) includes pagination information: +The [Link header](http://tools.ietf.org/html/rfc5988) includes pagination information. For example: Link: <{% data variables.product.api_url_code %}/user/repos?page=3&per_page=100>; rel="next", <{% data variables.product.api_url_code %}/user/repos?page=50&per_page=100>; rel="last" _The example includes a line break for readability._ +Or, if the endpoint uses cursor-based pagination: + + Link: <{% data variables.product.api_url_code %}/orgs/ORG/audit-log?after=MTYwMTkxOTU5NjQxM3xZbGI4VE5EZ1dvZTlla09uWjhoZFpR&before=>; rel="next", + This `Link` response header contains one or more [Hypermedia](/rest#hypermedia) link relations, some of which may require expansion as [URI templates](http://tools.ietf.org/html/rfc6570). The possible `rel` values are: diff --git a/content/rest/overview/troubleshooting.md b/content/rest/overview/troubleshooting.md index 0a22fab27b..a430cfd7be 100644 --- a/content/rest/overview/troubleshooting.md +++ b/content/rest/overview/troubleshooting.md @@ -63,7 +63,7 @@ curl -H 'Authorization: token my-oauth-token' https://api.github.com/user/repos #### Calls to OAuth Authorizations API -If you're making [OAuth Authorization API](/enterprise-server@2.22/rest/reference/oauth-authorizations) calls to manage your OAuth app's authorizations or to generate access tokens, similar to this example: +If you're making [OAuth Authorization API](/enterprise-server/rest/reference/oauth-authorizations) calls to manage your OAuth app's authorizations or to generate access tokens, similar to this example: ```bash curl -u my_username:my_password -X POST "https://api.github.com/authorizations" -d '{"scopes":["public_repo"], "note":"my token", "client_id":"my_client_id", "client_secret":"my_client_secret"}' diff --git a/content/rest/reference/enterprise-admin.md b/content/rest/reference/enterprise-admin.md index e95dc2be2a..a35266becc 100644 --- a/content/rest/reference/enterprise-admin.md +++ b/content/rest/reference/enterprise-admin.md @@ -60,6 +60,16 @@ You can also read the current version by calling the [meta endpoint](/rest/refer {% endif %} +{% if currentVersion == "free-pro-team@latest" %} + +## Audit log + +{% for operation in currentRestOperations %} + {% if operation.subcategory == 'audit-log' %}{% include rest_operation %}{% endif %} +{% endfor %} + +{% endif %} + {% if currentVersion == "free-pro-team@latest" %} ## Billing diff --git a/data/reusables/actions/actions-not-verified.md b/data/reusables/actions/actions-not-verified.md index 2ab85ce6c1..3107e5a79f 100644 --- a/data/reusables/actions/actions-not-verified.md +++ b/data/reusables/actions/actions-not-verified.md @@ -1 +1 @@ -Anyone can publish an action in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_dotcom %} verifies some partner organizations, but unlike verified apps, {% data variables.product.prodname_dotcom %} does not review or verify individual actions listed in {% data variables.product.prodname_marketplace %}. +Anyone can publish an action in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_dotcom %} verifies some partner organizations and these are shown as verified creators. diff --git a/data/reusables/actions/visualization-beta.md b/data/reusables/actions/visualization-beta.md new file mode 100644 index 0000000000..ee3ad11ef4 --- /dev/null +++ b/data/reusables/actions/visualization-beta.md @@ -0,0 +1,7 @@ +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +{% note %} + +**Note:** The workflow visualization graph for {% data variables.product.prodname_actions %} is currently in beta and subject to change. + +{% endnote %} +{% endif %} diff --git a/data/reusables/audit_log/audit-log-api-info.md b/data/reusables/audit_log/audit-log-api-info.md new file mode 100644 index 0000000000..55728a1692 --- /dev/null +++ b/data/reusables/audit_log/audit-log-api-info.md @@ -0,0 +1,5 @@ +* Access to your organization or repository settings +* Changes in permissions +* Added or removed users in an organization, repository, or team +* Users being promoted to admin +* Changes to permissions of a {% data variables.product.prodname_github_app %} diff --git a/data/reusables/audit_log/audit-log-git-events-retention.md b/data/reusables/audit_log/audit-log-git-events-retention.md new file mode 100644 index 0000000000..3f1584bf91 --- /dev/null +++ b/data/reusables/audit_log/audit-log-git-events-retention.md @@ -0,0 +1 @@ +The audit log retains Git events for 7 days. This is shorter than other audit log events, which can be retained for 90 days. diff --git a/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md b/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md index 343f6d8a22..2c1343c7f7 100644 --- a/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md +++ b/data/reusables/discussions/enabling-or-disabling-github-discussions-for-your-repository.md @@ -1,6 +1,8 @@ You can enable or disable discussions for a repository. {% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} +1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} +**Settings**. +![Repository settings button](/assets/images/help/discussions/public-repo-settings.png) 1. Under "Features", select **Discussions**. ![Checkbox under "Features" for enabling or disabling discussions for a repository](/assets/images/help/discussions/select-discussions-checkbox.png) diff --git a/data/reusables/marketplace/app-transfer-to-org-for-verification.md b/data/reusables/marketplace/app-transfer-to-org-for-verification.md new file mode 100644 index 0000000000..0621a9e6e9 --- /dev/null +++ b/data/reusables/marketplace/app-transfer-to-org-for-verification.md @@ -0,0 +1 @@ +If you want to sell an app that's owned by your user account, first you'll need to transfer the app to an organization, and then request verification for a listing created by the organization. diff --git a/data/reusables/marketplace/free-plan-note.md b/data/reusables/marketplace/free-plan-note.md new file mode 100644 index 0000000000..bf63caa53d --- /dev/null +++ b/data/reusables/marketplace/free-plan-note.md @@ -0,0 +1,5 @@ +{% note %} + +**Note:** If you're listing an app on {% data variables.product.prodname_marketplace %}, you can't list your app with a free pricing plan if you offer a paid service outside of {% data variables.product.prodname_marketplace %}. + +{% endnote %} diff --git a/data/reusables/marketplace/launch-with-free.md b/data/reusables/marketplace/launch-with-free.md index 15230e218b..2151c241cc 100644 --- a/data/reusables/marketplace/launch-with-free.md +++ b/data/reusables/marketplace/launch-with-free.md @@ -1 +1 @@ -You can submit both an unverified and verified app. This will allow you to launch with a free version of your app. Once GitHub verifies your app, your listing will change from unverified to verified in {% data variables.product.prodname_marketplace %} and GitHub will publish your new pricing plans. +You can request publication with or without verification. Requesting publication without verification allows you to launch a free version of your app quickly. If you then request publication with verification, your listing will be updated to include the verified creator badge and any paid pricing plans when you complete verification and financial onboarding. diff --git a/data/reusables/marketplace/marketplace-billing-ui-requirements.md b/data/reusables/marketplace/marketplace-billing-ui-requirements.md index 9c02badeae..5aa91ca839 100644 --- a/data/reusables/marketplace/marketplace-billing-ui-requirements.md +++ b/data/reusables/marketplace/marketplace-billing-ui-requirements.md @@ -1,7 +1,7 @@ -- Customers who cancel a paid plan purchased from {% data variables.product.prodname_marketplace %} must be automatically downgraded to the app's free plan if it exists. {% data reusables.marketplace.cancellation-clarification %} It's highly recommended to allow customers to re-enable their previous plan. -- Customers must be able to upgrade from your app's UI if you provide an [upgrade URL](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/#about-upgrade-urls) in this format: `https://www.github.com/marketplace//upgrade//` -- Customers must be able to modify which users have access to your app from your app's website if they purchased seats (per-unit pricing plan) or the plan offers unlimited collaborators. -- Customers must be able to see the following changes to their account immediately in the billing, profile, or account settings section of the app's website: +- Customers who cancel a paid plan purchased from {% data variables.product.prodname_marketplace %} should be automatically downgraded to the app's free plan if it exists. {% data reusables.marketplace.cancellation-clarification %} It's highly recommended to allow customers to re-enable their previous plan. +- Customers should be able to upgrade from your app's user interface if you provide an [upgrade URL](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/#about-upgrade-urls) in this format: `https://www.github.com/marketplace//upgrade//` +- Customers should be able to modify which users have access to your app from your app's website if they purchased seats (per-unit pricing plan) or the plan offers unlimited collaborators. +- Customers should be able to see the following changes to their account immediately in the billing, profile, or account settings section of the app's website: - Current plan and price. - New plans purchased. - Upgrades, downgrades, cancellations, and the number of remaining days in a free trial. diff --git a/data/reusables/package_registry/billing-for-container-registry.md b/data/reusables/package_registry/billing-for-container-registry.md index 7cf8e2459f..479e2d5b55 100644 --- a/data/reusables/package_registry/billing-for-container-registry.md +++ b/data/reusables/package_registry/billing-for-container-registry.md @@ -1,3 +1,3 @@ -During the {% data variables.product.prodname_github_container_registry %} beta, both the new {% data variables.product.prodname_container_registry %} and existing {% data variables.product.prodname_registry %} Docker registry will be free. For more information about the {% data variables.product.prodname_registry %} Docker registry, see "[Configuring Docker for use with {% data variables.product.prodname_registry %}](/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)." +During the {% data variables.product.prodname_github_container_registry %} beta, both the new {% data variables.product.prodname_container_registry %} and existing {% data variables.product.prodname_registry %} Docker registry will be free. For more information about the {% data variables.product.prodname_registry %} Docker registry, see "[Configuring Docker for use with {% data variables.product.prodname_registry %}](/packages/guides/configuring-docker-for-use-with-github-packages)." After the beta, the same billing and storage rates that other {% data variables.product.prodname_registry %} registries use will apply to the container registry. For more information, see "[About billing for {% data variables.product.prodname_registry %}](/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-packages)." diff --git a/data/reusables/package_registry/container-registry-beta-billing-note.md b/data/reusables/package_registry/container-registry-beta-billing-note.md index ccc4fc14f8..f588ab6f9b 100644 --- a/data/reusables/package_registry/container-registry-beta-billing-note.md +++ b/data/reusables/package_registry/container-registry-beta-billing-note.md @@ -1,5 +1,5 @@ {% note %} -**Billing update for container image storage:** During the beta phase of {% data variables.product.prodname_github_container_registry %}, Docker image storage and bandwidth are free for the old `docker.pkg.github.com` and new `ghcr.io` hosting services. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)." +**Billing update for container image storage:** During the beta phase of {% data variables.product.prodname_github_container_registry %}, Docker image storage and bandwidth are free for the old `docker.pkg.github.com` and new `ghcr.io` hosting services. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/guides/about-github-container-registry)." {% endnote %} diff --git a/data/reusables/package_registry/container-registry-beta.md b/data/reusables/package_registry/container-registry-beta.md index 24313880ba..6bd738198e 100644 --- a/data/reusables/package_registry/container-registry-beta.md +++ b/data/reusables/package_registry/container-registry-beta.md @@ -1,5 +1,5 @@ {% note %} -**Note:** {% data variables.product.prodname_github_container_registry %} is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use {% data variables.product.prodname_github_container_registry %}, you must enable the feature preview. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry/about-github-container-registry)" and "[Enabling improved container support](/packages/getting-started-with-github-container-registry/enabling-improved-container-support)." +**Note:** {% data variables.product.prodname_github_container_registry %} is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use {% data variables.product.prodname_github_container_registry %}, you must enable the feature preview. For more information, see "[About {% data variables.product.prodname_github_container_registry %}](/packages/guides/about-github-container-registry)" and "[Enabling improved container support](/packages/guides/enabling-improved-container-support)." {% endnote %} diff --git a/data/reusables/package_registry/docker_registry_deprecation_status.md b/data/reusables/package_registry/docker_registry_deprecation_status.md index 2df9364c31..a23fdc598b 100644 --- a/data/reusables/package_registry/docker_registry_deprecation_status.md +++ b/data/reusables/package_registry/docker_registry_deprecation_status.md @@ -1,5 +1,5 @@ {% warning %} -**Note:** The {% data variables.product.prodname_registry %} Docker registry will be superseded by {% data variables.product.prodname_github_container_registry %}{% if enterpriseServerVersions contains currentVersion %} in a future {% data variables.product.product_name %} release{% endif %}.{% if currentVersion == "free-pro-team@latest" %} To learn how to migrate your existing Docker images and any workflows using them, see "[Migrating to {% data variables.product.prodname_github_container_registry %} for Docker images](/packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images)" and "[Getting started with {% data variables.product.prodname_github_container_registry %}](/packages/getting-started-with-github-container-registry)."{% endif %} +**Note:** The {% data variables.product.prodname_registry %} Docker registry will be superseded by {% data variables.product.prodname_github_container_registry %}{% if enterpriseServerVersions contains currentVersion %} in a future {% data variables.product.product_name %} release{% endif %}.{% if currentVersion == "free-pro-team@latest" %} To learn how to migrate your existing Docker images and any workflows using them, see "[Migrating to {% data variables.product.prodname_github_container_registry %} for Docker images](/packages/guides/migrating-to-github-container-registry-for-docker-images)" and "[Container guides for {% data variables.product.prodname_registry %}](/packages/guides/container-guides-for-github-packages)."{% endif %} {% endwarning %} diff --git a/data/reusables/package_registry/feature-preview-for-container-registry.md b/data/reusables/package_registry/feature-preview-for-container-registry.md index b0cddc8bcb..3b74dd6c78 100644 --- a/data/reusables/package_registry/feature-preview-for-container-registry.md +++ b/data/reusables/package_registry/feature-preview-for-container-registry.md @@ -1,5 +1,5 @@ {% note %} -**Note:** Before you can use {% data variables.product.prodname_github_container_registry %}, you must enable the feature for your account. For more information, see "[Enabling improved container support](/packages/getting-started-with-github-container-registry/enabling-improved-container-support)." +**Note:** Before you can use {% data variables.product.prodname_github_container_registry %}, you must enable the feature for your account. For more information, see "[Enabling improved container support](/packages/guides/enabling-improved-container-support)." {% endnote %} \ No newline at end of file diff --git a/data/reusables/package_registry/required-scopes.md b/data/reusables/package_registry/required-scopes.md index ec9748d65a..364cdccaef 100644 --- a/data/reusables/package_registry/required-scopes.md +++ b/data/reusables/package_registry/required-scopes.md @@ -1 +1 @@ -You must use a personal access token with the appropriate scopes to publish and install packages in {% data variables.product.prodname_registry %}. For more information, see "[About {% data variables.product.prodname_registry %}](/packages/publishing-and-managing-packages/about-github-packages#authenticating-to-github-packages)." +You must use a personal access token with the appropriate scopes to publish and install packages in {% data variables.product.prodname_registry %}. For more information, see "[About {% data variables.product.prodname_registry %}](/packages/learn-github-packages/about-github-packages#authenticating-to-github-packages)." diff --git a/data/reusables/package_registry/viewing-packages.md b/data/reusables/package_registry/viewing-packages.md index 7a16420a97..131b04989a 100644 --- a/data/reusables/package_registry/viewing-packages.md +++ b/data/reusables/package_registry/viewing-packages.md @@ -1 +1 @@ -After you publish a package, you can view the package on {% data variables.product.prodname_dotcom %}. For more information, see "[Viewing packages](/packages/publishing-and-managing-packages/viewing-packages)." +After you publish a package, you can view the package on {% data variables.product.prodname_dotcom %}. For more information, see "[Viewing packages](/packages/manage-packages/viewing-packages)." diff --git a/data/reusables/repositories/dependency-review.md b/data/reusables/repositories/dependency-review.md new file mode 100644 index 0000000000..0d33834eec --- /dev/null +++ b/data/reusables/repositories/dependency-review.md @@ -0,0 +1,3 @@ +{% if currentVersion == "free-pro-team@latest" %} +Additionally, {% data variables.product.prodname_dotcom %} can review any dependencies added, updated, or removed in a pull request made against the default branch of a repository, and flag any changes that would introduce a vulnerability into your project. This allows you to spot and deal with vulnerable dependencies before, rather than after, they reach your codebase. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)." +{% endif %} \ No newline at end of file diff --git a/data/reusables/repositories/navigate-to-job-superlinter.md b/data/reusables/repositories/navigate-to-job-superlinter.md index d61e61031b..29a8d2e6f6 100644 --- a/data/reusables/repositories/navigate-to-job-superlinter.md +++ b/data/reusables/repositories/navigate-to-job-superlinter.md @@ -1,7 +1,10 @@ -{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} +1. Under **Jobs** or in the visualization graph, click the job you want to see. + ![Lint code base job](/assets/images/help/repository/superlinter-lint-code-base-job-updated.png) +{% elsif currentVersion ver_gt "enterprise-server@2.22" %} 1. In the left sidebar, click the job you want to see. ![Lint code base job](/assets/images/help/repository/superlinter-lint-code-base-job.png) {% else %} 1. In the left sidebar, click the job you want to see. ![Select a workflow job](/assets/images/help/repository/workflow-job.png) -{% endif %} \ No newline at end of file +{% endif %} diff --git a/data/reusables/repositories/view-failed-job-results-superlinter.md b/data/reusables/repositories/view-failed-job-results-superlinter.md index 6243061689..c8c23f7677 100644 --- a/data/reusables/repositories/view-failed-job-results-superlinter.md +++ b/data/reusables/repositories/view-failed-job-results-superlinter.md @@ -1,6 +1,8 @@ {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. Any failed steps are automatically expanded to display the results. - ![Super linter workflow results](/assets/images/help/repository/super-linter-workflow-results-updated.png) + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Super linter workflow results](/assets/images/help/repository/super-linter-workflow-results-updated-2.png){% else %} + ![Super linter workflow results](/assets/images/help/repository/super-linter-workflow-results-updated.png){% endif %} {% else %} 1. Expand the **Run Super-Linter** step to view the results. ![Super linter workflow results](/assets/images/help/repository/super-linter-workflow-results.png) diff --git a/data/reusables/repositories/view-specific-line-superlinter.md b/data/reusables/repositories/view-specific-line-superlinter.md index bfffe68a94..3dd5af281d 100644 --- a/data/reusables/repositories/view-specific-line-superlinter.md +++ b/data/reusables/repositories/view-specific-line-superlinter.md @@ -1,6 +1,10 @@ {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. Optionally, to get a link to a specific line in the logs, click on the step's line number. You can then copy the link from the address bar of your web browser. + {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} + ![Button to copy link](/assets/images/help/repository/copy-link-button-updated-2.png) + {% else %} ![Button to copy link](/assets/images/help/repository/copy-link-button-updated.png) + {% endif %} {% else %} 1. Optionally, to get a link to a specific line in the logs, click on the step's line number. You can then copy the link from the address bar of your web browser. ![Button to copy link](/assets/images/help/repository/copy-link-button.png) diff --git a/data/reusables/sponsors/billing-switcher.md b/data/reusables/sponsors/billing-switcher.md new file mode 100644 index 0000000000..0388b53d7f --- /dev/null +++ b/data/reusables/sponsors/billing-switcher.md @@ -0,0 +1,2 @@ +1. Optionally, to manage your sponsorship on behalf of an organization, in the upper-left corner, use the **Personal settings** drop-down menu, and click the organization. + ![Drop-down menu to switch accounts for settings](/assets/images/help/sponsors/billing-account-switcher.png) diff --git a/data/reusables/sponsors/change-tier.md b/data/reusables/sponsors/change-tier.md index 6843e3f196..9f4b7be31e 100644 --- a/data/reusables/sponsors/change-tier.md +++ b/data/reusables/sponsors/change-tier.md @@ -1,2 +1,2 @@ -1. Under "{% data variables.product.prodname_sponsors %}", to the right of the sponsored open source contributor, click {% octicon "triangle-down" aria-label="The down triangle octicon" %} next to your sponsored amount, then click **Change tier**. +1. Under "{% data variables.product.prodname_sponsors %}", to the right of the sponsored account, click {% octicon "triangle-down" aria-label="The down triangle octicon" %} next to your tier amount, then click **Change tier**. ![Change tier button](/assets/images/help/billing/edit-sponsor-billing.png) diff --git a/data/reusables/sponsors/choose-updates.md b/data/reusables/sponsors/choose-updates.md new file mode 100644 index 0000000000..0fbb1010cf --- /dev/null +++ b/data/reusables/sponsors/choose-updates.md @@ -0,0 +1,2 @@ +4. Decide whether you want to receive email updates from the sponsored account, then select or unselect "Receive updates from _ACCOUNT_." + ![Checkbox to receive updates from sponsored account](/assets/images/help/sponsors/updates-checkbox-manage.png) diff --git a/data/reusables/sponsors/developer-sponsored-choose-updates.md b/data/reusables/sponsors/developer-sponsored-choose-updates.md deleted file mode 100644 index 5fcd5548e6..0000000000 --- a/data/reusables/sponsors/developer-sponsored-choose-updates.md +++ /dev/null @@ -1,2 +0,0 @@ -4. Decide whether you want to receive email updates from the sponsored developer, then select or unselect "Receive updates from _DEVELOPER_." - ![Checkbox to receive updates from sponsored developer](/assets/images/help/sponsors/updates-checkbox-manage.png) diff --git a/data/reusables/sponsors/manage-developer-sponsorship.md b/data/reusables/sponsors/manage-developer-sponsorship.md deleted file mode 100644 index a0aa746339..0000000000 --- a/data/reusables/sponsors/manage-developer-sponsorship.md +++ /dev/null @@ -1,4 +0,0 @@ -1. Under the developer's name, click **Sponsoring**. - ![Sponsoring button](/assets/images/help/profile/sponsoring-button.png) -2. On the right side of the page, click **Manage your sponsorship**. - ![Manage your sponsorship button](/assets/images/help/sponsors/manage-your-sponsorship-button.png) diff --git a/data/reusables/sponsors/manage-org-sponsorship.md b/data/reusables/sponsors/manage-org-sponsorship.md deleted file mode 100644 index 9d79bfca65..0000000000 --- a/data/reusables/sponsors/manage-org-sponsorship.md +++ /dev/null @@ -1,4 +0,0 @@ -1. Next to the organization's name, click **Sponsoring**. - ![Sponsoring button](/assets/images/help/sponsors/org-sponsoring-button.png) -2. On the right side of the page, click **Manage your sponsorship**. - ![Manage your sponsorship button](/assets/images/help/sponsors/manage-your-sponsorship-button.png) diff --git a/data/reusables/sponsors/manage-sponsorship.md b/data/reusables/sponsors/manage-sponsorship.md new file mode 100644 index 0000000000..f977c24446 --- /dev/null +++ b/data/reusables/sponsors/manage-sponsorship.md @@ -0,0 +1,2 @@ +1. To the right of your current tier, click **Manage**. + ![Manage your sponsorship button](/assets/images/help/sponsors/manage-your-sponsorship-button.png) \ No newline at end of file diff --git a/data/reusables/sponsors/manage-updates-for-orgs.md b/data/reusables/sponsors/manage-updates-for-orgs.md new file mode 100644 index 0000000000..0cd08d5382 --- /dev/null +++ b/data/reusables/sponsors/manage-updates-for-orgs.md @@ -0,0 +1 @@ +You can designate which email address receives updates from the accounts your organization sponsors. For more information, see "[Managing updates from accounts your organization sponsors](/github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors)." diff --git a/data/reusables/sponsors/maximum-tier.md b/data/reusables/sponsors/maximum-tier.md index a787f1dd0a..803658fba4 100644 --- a/data/reusables/sponsors/maximum-tier.md +++ b/data/reusables/sponsors/maximum-tier.md @@ -1 +1 @@ -The maximum price is US$6000 per month. +The maximum price is US$12,000 per month. diff --git a/data/reusables/sponsors/navigate-to-org-sponsors-dashboard.md b/data/reusables/sponsors/navigate-to-org-sponsors-dashboard.md deleted file mode 100644 index 412a13fa24..0000000000 --- a/data/reusables/sponsors/navigate-to-org-sponsors-dashboard.md +++ /dev/null @@ -1,4 +0,0 @@ -1. In the upper-right corner of any page, click your profile photo, then click **{% data variables.product.prodname_sponsors %}**. -![{% data variables.product.prodname_sponsors %} button](/assets/images/help/sponsors/access-github-sponsors-dashboard.png) -2. In the list of your sponsored and eligible accounts, to the right of the organization, click **Dashboard**. -![Organization sponsors dashboard button](/assets/images/help/sponsors/org-sponsors-dashboard-button.png) diff --git a/data/reusables/sponsors/navigate-to-sponsored-developer.md b/data/reusables/sponsors/navigate-to-sponsored-account.md similarity index 66% rename from data/reusables/sponsors/navigate-to-sponsored-developer.md rename to data/reusables/sponsors/navigate-to-sponsored-account.md index e983650eb5..def70f43f1 100644 --- a/data/reusables/sponsors/navigate-to-sponsored-developer.md +++ b/data/reusables/sponsors/navigate-to-sponsored-account.md @@ -1 +1 @@ -1. On {% data variables.product.product_name %}, navigate to the sponsored developer's profile. +1. On {% data variables.product.product_name %}, navigate to the sponsored account's profile. diff --git a/data/reusables/sponsors/navigate-to-sponsored-org.md b/data/reusables/sponsors/navigate-to-sponsored-org.md deleted file mode 100644 index 6acd162cfd..0000000000 --- a/data/reusables/sponsors/navigate-to-sponsored-org.md +++ /dev/null @@ -1 +0,0 @@ -1. On {% data variables.product.product_name %}, navigate to the sponsored organization's profile. diff --git a/data/reusables/sponsors/navigate-to-dev-sponsors-dashboard.md b/data/reusables/sponsors/navigate-to-sponsors-dashboard.md similarity index 86% rename from data/reusables/sponsors/navigate-to-dev-sponsors-dashboard.md rename to data/reusables/sponsors/navigate-to-sponsors-dashboard.md index 8ed7f17a33..6391060874 100644 --- a/data/reusables/sponsors/navigate-to-dev-sponsors-dashboard.md +++ b/data/reusables/sponsors/navigate-to-sponsors-dashboard.md @@ -1,4 +1,4 @@ 1. In the upper-right corner of any page, click your profile photo, then click **{% data variables.product.prodname_sponsors %}**. ![{% data variables.product.prodname_sponsors %} button](/assets/images/help/sponsors/access-github-sponsors-dashboard.png) -2. If a list of your sponsored and eligible accounts is shown, to the right of your account name, click **Dashboard**. +2. If a list of your sponsored and eligible accounts is shown, to the right of the account you want to manage, click **Dashboard**. ![Developer sponsors dashboard button](/assets/images/help/sponsors/dev-sponsors-dashboard-button.png) diff --git a/data/reusables/sponsors/no-fees.md b/data/reusables/sponsors/no-fees.md index a122d94bbb..dd829bafdc 100644 --- a/data/reusables/sponsors/no-fees.md +++ b/data/reusables/sponsors/no-fees.md @@ -1 +1 @@ -{% data variables.product.prodname_sponsors %} does not charge any fees for sponsorships from user accounts, so 100% of these sponsorships go to the sponsored developer or organization. +{% data variables.product.prodname_sponsors %} does not charge any fees for sponsorships from user accounts, so 100% of these sponsorships go to the sponsored developer or organization. The 10% fee for sponsorships from organizations is waived during the beta. diff --git a/data/reusables/sponsors/org-sponsors-release-phase.md b/data/reusables/sponsors/org-sponsors-release-phase.md new file mode 100644 index 0000000000..75983073a4 --- /dev/null +++ b/data/reusables/sponsors/org-sponsors-release-phase.md @@ -0,0 +1,5 @@ +{% note %} + +**Note:** Sponsoring on behalf of an organization is currently in beta and subject to change. + +{% endnote %} \ No newline at end of file diff --git a/data/reusables/sponsors/pay-prorated-amount.md b/data/reusables/sponsors/pay-prorated-amount.md new file mode 100644 index 0000000000..969f672e64 --- /dev/null +++ b/data/reusables/sponsors/pay-prorated-amount.md @@ -0,0 +1,2 @@ +1. Optionally, if you're sponsoring as an organization, to pay a prorated amount instead of making the full monthly payment, under "Due today", click **Pay prorated $X.XX today**. + ![Link to pay prorated amount](/assets/images/help/sponsors/pay-prorated-amount-link.png) \ No newline at end of file diff --git a/data/reusables/sponsors/prorated-sponsorship.md b/data/reusables/sponsors/prorated-sponsorship.md index f63d25e339..56a047d867 100644 --- a/data/reusables/sponsors/prorated-sponsorship.md +++ b/data/reusables/sponsors/prorated-sponsorship.md @@ -1 +1 @@ -You will immediately be charged a prorated amount for the time until your next regular billing date. +If you're sponsoring on behalf of your user account, you will immediately be charged a prorated amount for the time until your next regular billing date. If you're sponsoring on behalf of an organization, you can choose to pay the prorated amount or make the full monthly payment. diff --git a/data/reusables/sponsors/sponsor-account.md b/data/reusables/sponsors/sponsor-account.md new file mode 100644 index 0000000000..9c91a25539 --- /dev/null +++ b/data/reusables/sponsors/sponsor-account.md @@ -0,0 +1,2 @@ +1. Click **Sponsor _ACCOUNT_**. + ![Sponsor button](/assets/images/help/sponsors/sponsor-developer-button.png) \ No newline at end of file diff --git a/data/reusables/sponsors/sponsorship-dashboard.md b/data/reusables/sponsors/sponsorship-dashboard.md new file mode 100644 index 0000000000..20dc887fbe --- /dev/null +++ b/data/reusables/sponsors/sponsorship-dashboard.md @@ -0,0 +1,7 @@ +1. Navigate to your sponsorship dashboard for the account. + - If you're sponsoring a user account, under the user's name, click **Sponsoring**. + ![Sponsoring button](/assets/images/help/profile/sponsoring-button.png) + - If you're sponsoring an organization, to the right of the organization's name, click **Sponsoring**. + ![Sponsoring button](/assets/images/help/sponsors/org-sponsoring-button.png) +1. Optionally, to manage a sponsorship on behalf of an organization, on the right side of the page, use the **Sponsoring as** drop-down menu, and click the organization. + ![Drop-down menu to choose the account you're sponsoring as](/assets/images/help/sponsors/sponsoring-as-drop-down-menu.png) diff --git a/data/reusables/sponsors/sponsorship-details.md b/data/reusables/sponsors/sponsorship-details.md index 55425b5c0a..6542580736 100644 --- a/data/reusables/sponsors/sponsorship-details.md +++ b/data/reusables/sponsors/sponsorship-details.md @@ -1 +1 @@ -Anyone with a {% data variables.product.product_name %} account can sponsor anyone with a sponsored developer profile or sponsored organization profile through a recurring monthly payment. You can choose from multiple sponsorship tiers, with monthly payment amounts and benefits that are set by the sponsored developer or organization. Your sponsorship will share your account's existing billing date, payment method, and receipt. +You can sponsor anyone with a sponsored developer profile or sponsored organization profile on behalf of your user account or an organization. You can choose from multiple sponsorship tiers, with monthly payment amounts and benefits that are set by the sponsored account. Your sponsorship will share your account's existing billing date, payment method, and receipt. diff --git a/data/variables/action_code_examples.yml b/data/variables/action_code_examples.yml index 8b2cfe23e4..a098626e04 100644 --- a/data/variables/action_code_examples.yml +++ b/data/variables/action_code_examples.yml @@ -1,10 +1,3 @@ -- title: Starter workflows - description: Workflow files for helping people get started with GitHub Actions - languages: TypeScript - href: actions/starter-workflows - tags: - - official - - workflow - title: Example services description: Example workflows using service containers languages: JavaScript diff --git a/includes/all-articles.html b/includes/all-articles.html index 0754fef282..d0cfe2054c 100644 --- a/includes/all-articles.html +++ b/includes/all-articles.html @@ -1,8 +1,8 @@ {% assign product = siteTree[currentLanguage][currentVersion].products[currentProduct] %} {% assign maxArticles = 10 %} -
-

All {{ product.title }} docs

+
+

All {{ product.title }} docs

{% for category in product.categories %} diff --git a/lib/data-directory.js b/lib/data-directory.js new file mode 100644 index 0000000000..d72abcbf55 --- /dev/null +++ b/lib/data-directory.js @@ -0,0 +1,68 @@ +const assert = require('assert') +const fs = require('fs').promises +const path = require('path') +const walk = require('walk-sync') +const yaml = require('js-yaml') +const { isRegExp, set } = require('lodash') +const filenameToKey = require('./filename-to-key') + +module.exports = async function dataDirectory (dir, opts = {}) { + const defaultOpts = { + preprocess: (content) => { return content }, + ignorePatterns: [/README\.md$/i], + extensions: [ + '.json', + '.md', + '.markdown', + '.yaml', + '.yml' + ] + } + + opts = Object.assign({}, defaultOpts, opts) + + // validate input + assert(Array.isArray(opts.ignorePatterns)) + assert(opts.ignorePatterns.every(isRegExp)) + assert(Array.isArray(opts.extensions)) + assert(opts.extensions.length) + + // start with an empty data object + const data = {} + + // find YAML and Markdown files in the given directory, recursively + await Promise.all(walk(dir, { includeBasePath: true }) + .filter(filename => { + // ignore files that match any of ignorePatterns regexes + if (opts.ignorePatterns.some(pattern => pattern.test(filename))) return false + + // ignore files that don't have a whitelisted file extension + return opts.extensions.includes(path.extname(filename).toLowerCase()) + }) + .map(async filename => { + // derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename + const key = filenameToKey(path.relative(dir, filename)) + const extension = path.extname(filename).toLowerCase() + + let fileContent = await fs.readFile(filename, 'utf8') + + if (opts.preprocess) fileContent = opts.preprocess(fileContent) + + // add this file's data to the global data object + switch (extension) { + case '.json': + set(data, key, JSON.parse(fileContent)) + break + case '.yaml': + case '.yml': + set(data, key, yaml.safeLoad(fileContent, { filename })) + break + case '.md': + case '.markdown': + set(data, key, fileContent) + break + } + })) + + return data +} diff --git a/lib/filename-to-key.js b/lib/filename-to-key.js new file mode 100644 index 0000000000..568552285b --- /dev/null +++ b/lib/filename-to-key.js @@ -0,0 +1,28 @@ +/* eslint-disable prefer-regex-literals */ +const path = require('path') +const { escapeRegExp } = require('lodash') + +// slash at the beginning of a filename +const leadingPathSeparator = new RegExp(`^${escapeRegExp(path.sep)}`) +const windowsLeadingPathSeparator = new RegExp('^/') + +// all slashes in the filename. path.sep is OS agnostic (windows, mac, etc) +const pathSeparator = new RegExp(escapeRegExp(path.sep), 'g') +const windowsPathSeparator = new RegExp('/', 'g') + +// handle MS Windows style double-backslashed filenames +const windowsDoubleSlashSeparator = new RegExp('\\\\', 'g') + +// derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename +module.exports = function filenameToKey (filename) { + const extension = new RegExp(`${path.extname(filename)}$`) + const key = filename + .replace(extension, '') + .replace(leadingPathSeparator, '') + .replace(windowsLeadingPathSeparator, '') + .replace(pathSeparator, '.') + .replace(windowsPathSeparator, '.') + .replace(windowsDoubleSlashSeparator, '.') + + return key +} diff --git a/lib/liquid-tags/data.js b/lib/liquid-tags/data.js index 23abc89352..af500dc6e8 100644 --- a/lib/liquid-tags/data.js +++ b/lib/liquid-tags/data.js @@ -1,6 +1,6 @@ const Liquid = require('liquid') -const Syntax = /([a-z0-9/\\_.-]+)/i +const Syntax = /([a-z0-9/\\_.\-[\]]+)/i const SyntaxHelp = "Syntax Error in 'data' - Valid syntax: data [path]" module.exports = class Data extends Liquid.Tag { diff --git a/lib/page.js b/lib/page.js index c282f1792f..f9274f0119 100644 --- a/lib/page.js +++ b/lib/page.js @@ -1,5 +1,5 @@ const assert = require('assert') -const fs = require('fs') +const fs = require('fs').promises const path = require('path') const cheerio = require('cheerio') const patterns = require('./patterns') @@ -23,15 +23,30 @@ const slash = require('slash') const statsd = require('./statsd') class Page { - constructor (opts) { + static async init (opts) { assert(opts.relativePath, 'relativePath is required') assert(opts.basePath, 'basePath is required') + + const relativePath = slash(opts.relativePath) + const fullPath = slash(path.join(opts.basePath, relativePath)) + const raw = await fs.readFile(fullPath, 'utf8') + + return new Page({ ...opts, relativePath, fullPath, raw }) + } + + static async exists (path) { + try { + return await fs.stat(path) + } catch (err) { + if (err.code === 'ENOENT') return false + console.error(err) + } + } + + constructor (opts) { assert(opts.languageCode, 'languageCode is required') Object.assign(this, { ...opts }) - this.relativePath = slash(this.relativePath) - this.fullPath = slash(path.join(this.basePath, this.relativePath)) - this.raw = fs.readFileSync(this.fullPath, 'utf8') // TODO remove this when crowdin-support issue 66 has been resolved if (this.languageCode !== 'en' && this.raw.includes(': verdadero')) { diff --git a/lib/pages.js b/lib/pages.js index cdca1fae1e..4db70e7dd5 100644 --- a/lib/pages.js +++ b/lib/pages.js @@ -2,42 +2,50 @@ const path = require('path') const walk = require('walk-sync').entries const Page = require('./page') const languages = require('./languages') -const fs = require('fs') +const { mapLimit, filterLimit } = require('async') +const FILE_READ_LIMIT = 500 async function loadPageList () { const pageList = [] // load english pages const englishPath = path.join(__dirname, '..', languages.en.dir, 'content') - const englishPages = walk(englishPath) - .filter(({ relativePath }) => { - return relativePath.endsWith('.md') && - !relativePath.includes('README') - }) - .map(fileData => new Page({ ...fileData, languageCode: languages.en.code })) - + const englishPaths = walk(englishPath) + .filter(({ relativePath }) => + relativePath.endsWith('.md') && !relativePath.includes('README') + ) + const englishPages = await mapLimit( + englishPaths, + FILE_READ_LIMIT, + async fileData => await Page.init({ ...fileData, languageCode: languages.en.code }) + ) pageList.push(...englishPages) // load matching pages in other languages - for (const page of englishPages) { - for (const language of Object.values(languages)) { - if (language.code === 'en') continue - + let localizedPaths = Object.values(languages) + .filter(({ code }) => code !== 'en') + .map(language => { const basePath = path.join(__dirname, '..', language.dir, 'content') - const localizedPath = path.join(basePath, page.relativePath) - try { - fs.statSync(localizedPath) - } catch (_) { - continue - } - - pageList.push(new Page({ - relativePath: page.relativePath, + return englishPages.map(page => ({ basePath, + relativePath: page.relativePath, + localizedPath: path.join(basePath, page.relativePath), languageCode: language.code })) - } - } + }) + .flat() + localizedPaths = await filterLimit( + localizedPaths, + FILE_READ_LIMIT, + async ({ localizedPath }) => Page.exists(localizedPath) + ) + const localizedPages = await mapLimit( + localizedPaths, + FILE_READ_LIMIT, + async ({ basePath, relativePath, languageCode }) => + await Page.init({ basePath, relativePath, languageCode }) + ) + pageList.push(...localizedPages) return pageList } diff --git a/lib/redirects/get-docs-path-from-developer-path.js b/lib/redirects/get-docs-path-from-developer-path.js index 35395143d9..5286bba04b 100644 --- a/lib/redirects/get-docs-path-from-developer-path.js +++ b/lib/redirects/get-docs-path-from-developer-path.js @@ -15,7 +15,25 @@ module.exports = function getDocsPathFromDeveloperPath (oldDeveloperPath, allRed // oneoff redirect const v3OrgPreReceiveHooks = '/v3/orgs/pre_receive_hooks' if (newPath.endsWith(v3OrgPreReceiveHooks)) { - newPath = newPath.replace(v3OrgPreReceiveHooks, '/v3/enterprise-admin/org_pre_receive_hooks') + newPath = newPath.replace(v3OrgPreReceiveHooks, '/v3/enterprise-admin/organization_pre_receive_hooks') + } + + // oneoff redirect + const v3RepoPreReceiveHooks = '/v3/repos/pre_receive_hooks' + if (newPath.endsWith(v3RepoPreReceiveHooks)) { + newPath = newPath.replace(v3RepoPreReceiveHooks, '/v3/enterprise-admin/repository_pre_receive_hooks') + } + + // oneoff redirect + const v3OrgHooks = '/v3/orgs/hooks' + if (newPath.endsWith(v3OrgHooks)) { + newPath = newPath.replace(v3OrgHooks, '/v3/orgs/webhooks') + } + + // oneoff redirect + const v3RepoHooks = '/v3/repos/hooks' + if (newPath.endsWith(v3RepoHooks)) { + newPath = newPath.replace(v3RepoHooks, '/v3/repos/webhooks') } // oneoff redirect for a dotcom developer path to Enterprise-only path on docs.github.com @@ -46,6 +64,7 @@ module.exports = function getDocsPathFromDeveloperPath (oldDeveloperPath, allRed .replace(/_/g, '-') // this is a special oneoff replacement .replace('org-pre-receive-hooks', 'organization-pre-receive-hooks') + .replace('repo-pre-receive-hooks', 'repository-pre-receive-hooks') : lastSegment } diff --git a/lib/redirects/precompile.js b/lib/redirects/precompile.js index 4af7e5f077..9708757274 100755 --- a/lib/redirects/precompile.js +++ b/lib/redirects/precompile.js @@ -50,22 +50,6 @@ module.exports = async function precompileRedirects (pageList, pageMap) { const developerRouteWithLanguage = `/en${developerRoute}` allRedirects[developerRouteWithLanguage] = newPath - // TODO until we update all the old /v3 and /v4 links, we need to support redirects - // from the old /enterprise//v3 format to the new /enterprise-server@ /en/enterprise-server@2.20/rest/reference/pulls#comments - // /en/enterprise-server@2.20/v3/pulls/comments -> /en/enterprise-server@2.20/rest/reference/pulls#comments - // NOTE: after we update all the /v3 and /v4 links, we can yank the following block - if (developerRoute.includes('/enterprise/')) { - const developerRouteWithNewFormat = developerRoute.replace(/\/enterprise\/(\d.\d\d)\//, '/enterprise-server@$1/') - const developerRouteWithNewFormatWithLanguage = `/en${developerRouteWithNewFormat}` - allRedirects[developerRouteWithNewFormat] = newPath - allRedirects[developerRouteWithNewFormatWithLanguage] = newPath - } - // TODO ENDYANK - // although we only support developer Enterprise paths up to 2.21, we make // an exception to always redirect versionless paths to the latest version if (developerRoute.includes('/2.21/')) { @@ -74,33 +58,8 @@ module.exports = async function precompileRedirects (pageList, pageMap) { const developerRouteWithLanguageWithoutVersion = `/en${developerRouteWithoutVersion}` allRedirects[developerRouteWithoutVersion] = newPathOnLatestVersion allRedirects[developerRouteWithLanguageWithoutVersion] = newPathOnLatestVersion - // TODO after we update all the /v3 and /v4 links, we can yank the following - const developerRouteWithoutVersionWithNewFormat = developerRouteWithoutVersion - .replace('/enterprise/', 'enterprise-server') - const developerRouteWithoutVersionWithNewFormatWithLanguage = `/en${developerRouteWithoutVersionWithNewFormat}` - allRedirects[developerRouteWithoutVersionWithNewFormat] = newPathOnLatestVersion - allRedirects[developerRouteWithoutVersionWithNewFormatWithLanguage] = newPathOnLatestVersion - // TODO ENDYANK } - // TODO: TEMPORARILY support explicit 2.22 redirects (created on page render by lib/rewrite-local-links) - // after we update `/v3` and `/v4` links everywhere to `/rest` and `/graphql`, we can - // yank this entire block because 2.22 never existed on developer site - if (developerRoute.includes('/2.21/')) { - const newPath222 = newPath.replace('@2.21/', '@2.22/') - const developerRoute222 = developerRoute.replace('/2.21/', '/2.22/') - const developerRouteWithLanguage222 = `/en${developerRoute222}` - allRedirects[developerRoute222] = newPath222 - allRedirects[developerRouteWithLanguage222] = newPath222 - - const developerRouteWithNewFormat222 = developerRoute222 - .replace('/enterprise/2.22/', '/enterprise-server@2.22/') - const developerRouteWithNewFormatWithLanguage222 = `/en${developerRouteWithNewFormat222}` - allRedirects[developerRouteWithNewFormat222] = newPath222 - allRedirects[developerRouteWithNewFormatWithLanguage222] = newPath222 - } - // TODO ENDYANK - // given a developer route like `/enterprise/2.19/v3/activity`, // add a veriation like `/enterprise/2.19/user/v3/activity`; // we need to do this because all links in content get rewritten diff --git a/lib/rest/static/decorated/api.github.com.json b/lib/rest/static/decorated/api.github.com.json index e2f389b736..f5234c81cc 100644 --- a/lib/rest/static/decorated/api.github.com.json +++ b/lib/rest/static/decorated/api.github.com.json @@ -5975,6 +5975,123 @@ "bodyParameters": [], "descriptionHTML": "

Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.

\n

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

" }, + { + "verb": "get", + "requestPath": "/enterprises/{enterprise}/audit-log", + "serverUrl": "https://api.github.com", + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

" + }, + { + "name": "phrase", + "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A search phrase. For more information, see Searching the audit log.

" + }, + { + "name": "include", + "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "web", + "git", + "all" + ] + }, + "descriptionHTML": "

The event types to include:

\n
    \n
  • web - returns web (non-Git) events
  • \n
  • git - returns Git events
  • \n
  • all - returns both web and Git events
  • \n
\n

The default is web.

" + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.

" + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.

" + }, + { + "name": "per_page", + "description": "Results per page (max 100)", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + }, + "descriptionHTML": "

Results per page (max 100)

" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/audit-log", + "html": "
curl \\\n  -H \"Accept: application/vnd.github.v3+json\" \\\n  https://api.github.com/enterprises/ENTERPRISE/audit-log
" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n enterprise: 'enterprise'\n})", + "html": "
await octokit.request('GET /enterprises/{enterprise}/audit-log', {\n  enterprise: 'enterprise'\n})\n
" + } + ], + "summary": "Get the audit log for an enterprise", + "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.", + "operationId": "audit-log/get-audit-log", + "tags": [ + "audit-log" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise" + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": false, + "previews": [], + "category": "enterprise-admin", + "subcategory": "audit-log" + }, + "slug": "get-the-audit-log-for-an-enterprise", + "category": "enterprise-admin", + "categoryLabel": "Enterprise admin", + "subcategory": "audit-log", + "subcategoryLabel": "Audit log", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "

Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.

\n

Gets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the admin:enterprise scope.

", + "responses": [ + { + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Default response", + "payload": "
[\n  {\n    \"@timestamp\": 1606929874512,\n    \"action\": \"team.add_member\",\n    \"actor\": \"octocat\",\n    \"created_at\": 1606929874512,\n    \"org\": \"octo-corp\",\n    \"team\": \"octo-corp/example-team\",\n    \"user\": \"monalisa\"\n  },\n  {\n    \"@timestamp\": 1606507117008,\n    \"action\": \"org.create\",\n    \"actor\": \"octocat\",\n    \"created_at\": 1606507117008,\n    \"org\": \"octocat-test-org\"\n  },\n  {\n    \"@timestamp\": 1605719148837,\n    \"action\": \"repo.destroy\",\n    \"actor\": \"monalisa\",\n    \"created_at\": 1605719148837,\n    \"org\": \"mona-org\",\n    \"repo\": \"mona-org/mona-test-repo\",\n    \"visibility\": \"private\"\n  }\n]\n
" + } + ] + }, { "verb": "get", "requestPath": "/enterprises/{enterprise}/settings/billing/actions", @@ -14225,6 +14342,120 @@ "bodyParameters": [], "descriptionHTML": "

Removes a repository from an organization secret when the visibility for repository access is set to selected. The visibility is set when you Create or update an organization secret. You must authenticate using an access token with the admin:org scope to use this endpoint. GitHub Apps must have the secrets organization permission to use this endpoint.

" }, + { + "verb": "get", + "requestPath": "/orgs/{org}/audit-log", + "serverUrl": "https://api.github.com", + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "" + }, + { + "name": "phrase", + "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A search phrase. For more information, see Searching the audit log.

" + }, + { + "name": "include", + "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "web", + "git", + "all" + ] + }, + "descriptionHTML": "

The event types to include:

\n
    \n
  • web - returns web (non-Git) events
  • \n
  • git - returns Git events
  • \n
  • all - returns both web and Git events
  • \n
\n

The default is web.

" + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A cursor, as given in the Link header. If specified, the query only searches for events after this cursor.

" + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "descriptionHTML": "

A cursor, as given in the Link header. If specified, the query only searches for events before this cursor.

" + }, + { + "name": "per_page", + "description": "Results per page (max 100)", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + }, + "descriptionHTML": "

Results per page (max 100)

" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/audit-log", + "html": "
curl \\\n  -H \"Accept: application/vnd.github.v3+json\" \\\n  https://api.github.com/orgs/ORG/audit-log
" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /orgs/{org}/audit-log', {\n org: 'org'\n})", + "html": "
await octokit.request('GET /orgs/{org}/audit-log', {\n  org: 'org'\n})\n
" + } + ], + "summary": "Get the audit log for an organization", + "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.", + "operationId": "orgs/get-audit-log", + "tags": [ + "orgs" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization" + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "previews": [], + "category": "orgs", + "subcategory": null + }, + "slug": "get-the-audit-log-for-an-organization", + "category": "orgs", + "categoryLabel": "Orgs", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "

Note: The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.

\n

Gets the audit log for an organization. For more information, see \"Reviewing the audit log for your organization.\"

\n

To use this endpoint, you must be an organization owner, and you must use an access token with the admin:org scope. GitHub Apps must have the organization_administration read permission to use this endpoint.

", + "responses": [ + { + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Default response", + "payload": "
[\n  {\n    \"@timestamp\": 1606929874512,\n    \"action\": \"team.add_member\",\n    \"actor\": \"octocat\",\n    \"created_at\": 1606929874512,\n    \"org\": \"octo-corp\",\n    \"team\": \"octo-corp/example-team\",\n    \"user\": \"monalisa\"\n  },\n  {\n    \"@timestamp\": 1606507117008,\n    \"action\": \"org.create\",\n    \"actor\": \"octocat\",\n    \"created_at\": 1606507117008,\n    \"org\": \"octocat-test-org\"\n  },\n  {\n    \"@timestamp\": 1605719148837,\n    \"action\": \"repo.destroy\",\n    \"actor\": \"monalisa\",\n    \"created_at\": 1605719148837,\n    \"org\": \"mona-org\",\n    \"repo\": \"mona-org/mona-test-repo\",\n    \"visibility\": \"private\"\n  }\n]\n
" + } + ] + }, { "verb": "get", "requestPath": "/orgs/{org}/blocks", diff --git a/lib/rest/static/dereferenced/api.github.com.deref.json b/lib/rest/static/dereferenced/api.github.com.deref.json index 873643c5bc..7dbc79d269 100644 --- a/lib/rest/static/dereferenced/api.github.com.deref.json +++ b/lib/rest/static/dereferenced/api.github.com.deref.json @@ -17051,6 +17051,254 @@ } } }, + "/enterprises/{enterprise}/audit-log": { + "get": { + "summary": "Get the audit log for an enterprise", + "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an enterprise. To use this endpoint, you must be an enterprise admin, and you must use an access token with the `admin:enterprise` scope.", + "operationId": "audit-log/get-audit-log", + "tags": [ + "audit-log" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/reference/enterprise-admin#get-the-audit-log-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "phrase", + "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "include", + "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "web", + "git", + "all" + ] + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "Results per page (max 100)", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "@timestamp": { + "type": "integer", + "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)." + }, + "action": { + "type": "string", + "description": "The name of the action that was performed, for example `user.login` or `repo.create`." + }, + "active": { + "type": "boolean" + }, + "active_was": { + "type": "boolean" + }, + "actor": { + "type": "string", + "description": "The actor who performed the action." + }, + "blocked_user": { + "type": "string", + "description": "The username of the account being blocked." + }, + "business": { + "type": "string" + }, + "config": { + "type": "array" + }, + "config_was": { + "type": "array" + }, + "content_type": { + "type": "string" + }, + "created_at": { + "type": "integer", + "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)." + }, + "deploy_key_fingerprint": { + "type": "string" + }, + "emoji": { + "type": "string" + }, + "events": { + "type": "array" + }, + "events_were": { + "type": "array" + }, + "explanation": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "hook_id": { + "type": "integer" + }, + "limited_availability": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "name": { + "type": "string" + }, + "old_user": { + "type": "string" + }, + "openssh_public_key": { + "type": "string" + }, + "org": { + "type": "string" + }, + "previous_visibility": { + "type": "string" + }, + "read_only": { + "type": "boolean" + }, + "repo": { + "type": "string", + "description": "The name of the repository." + }, + "repository": { + "type": "string", + "description": "The name of the repository." + }, + "repository_public": { + "type": "boolean" + }, + "target_login": { + "type": "string" + }, + "team": { + "type": "string" + }, + "transport_protocol": { + "type": "integer", + "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data." + }, + "transport_protocol_name": { + "type": "string", + "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data." + }, + "user": { + "type": "string", + "description": "The user that was affected by the action performed (if available)." + }, + "visibility": { + "type": "string", + "description": "The repository visibility, for example `public` or `private`." + } + } + } + }, + "examples": { + "default": { + "value": [ + { + "@timestamp": 1606929874512, + "action": "team.add_member", + "actor": "octocat", + "created_at": 1606929874512, + "org": "octo-corp", + "team": "octo-corp/example-team", + "user": "monalisa" + }, + { + "@timestamp": 1606507117008, + "action": "org.create", + "actor": "octocat", + "created_at": 1606507117008, + "org": "octocat-test-org" + }, + { + "@timestamp": 1605719148837, + "action": "repo.destroy", + "actor": "monalisa", + "created_at": 1605719148837, + "org": "mona-org", + "repo": "mona-org/mona-test-repo", + "visibility": "private" + } + ] + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": false, + "previews": [ + + ], + "category": "enterprise-admin", + "subcategory": "audit-log" + } + } + }, "/enterprises/{enterprise}/settings/billing/actions": { "get": { "summary": "Get GitHub Actions billing for an enterprise", @@ -49105,6 +49353,253 @@ } } }, + "/orgs/{org}/audit-log": { + "get": { + "summary": "Get the audit log for an organization", + "description": "**Note:** The audit log REST API is currently in beta and is subject to change. To join the beta, talk to your services or sales contact at GitHub.\n\nGets the audit log for an organization. For more information, see \"[Reviewing the audit log for your organization](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization).\"\n\nTo use this endpoint, you must be an organization owner, and you must use an access token with the `admin:org` scope. GitHub Apps must have the `organization_administration` read permission to use this endpoint.", + "operationId": "orgs/get-audit-log", + "tags": [ + "orgs" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/reference/orgs#get-the-audit-log-for-an-organization" + }, + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "phrase", + "description": "A search phrase. For more information, see [Searching the audit log](https://docs.github.com/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#searching-the-audit-log).", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "include", + "description": "The event types to include:\n\n- `web` - returns web (non-Git) events\n- `git` - returns Git events\n- `all` - returns both web and Git events\n\nThe default is `web`.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "web", + "git", + "all" + ] + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events after this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/overview/resources-in-the-rest-api#link-header). If specified, the query only searches for events before this cursor.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "Results per page (max 100)", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "@timestamp": { + "type": "integer", + "description": "The time the audit log event occurred, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)." + }, + "action": { + "type": "string", + "description": "The name of the action that was performed, for example `user.login` or `repo.create`." + }, + "active": { + "type": "boolean" + }, + "active_was": { + "type": "boolean" + }, + "actor": { + "type": "string", + "description": "The actor who performed the action." + }, + "blocked_user": { + "type": "string", + "description": "The username of the account being blocked." + }, + "business": { + "type": "string" + }, + "config": { + "type": "array" + }, + "config_was": { + "type": "array" + }, + "content_type": { + "type": "string" + }, + "created_at": { + "type": "integer", + "description": "The time the audit log event was recorded, given as a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time)." + }, + "deploy_key_fingerprint": { + "type": "string" + }, + "emoji": { + "type": "string" + }, + "events": { + "type": "array" + }, + "events_were": { + "type": "array" + }, + "explanation": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "hook_id": { + "type": "integer" + }, + "limited_availability": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "name": { + "type": "string" + }, + "old_user": { + "type": "string" + }, + "openssh_public_key": { + "type": "string" + }, + "org": { + "type": "string" + }, + "previous_visibility": { + "type": "string" + }, + "read_only": { + "type": "boolean" + }, + "repo": { + "type": "string", + "description": "The name of the repository." + }, + "repository": { + "type": "string", + "description": "The name of the repository." + }, + "repository_public": { + "type": "boolean" + }, + "target_login": { + "type": "string" + }, + "team": { + "type": "string" + }, + "transport_protocol": { + "type": "integer", + "description": "The type of protocol (for example, HTTP or SSH) used to transfer Git data." + }, + "transport_protocol_name": { + "type": "string", + "description": "A human readable name for the protocol (for example, HTTP or SSH) used to transfer Git data." + }, + "user": { + "type": "string", + "description": "The user that was affected by the action performed (if available)." + }, + "visibility": { + "type": "string", + "description": "The repository visibility, for example `public` or `private`." + } + } + } + }, + "examples": { + "default": { + "value": [ + { + "@timestamp": 1606929874512, + "action": "team.add_member", + "actor": "octocat", + "created_at": 1606929874512, + "org": "octo-corp", + "team": "octo-corp/example-team", + "user": "monalisa" + }, + { + "@timestamp": 1606507117008, + "action": "org.create", + "actor": "octocat", + "created_at": 1606507117008, + "org": "octocat-test-org" + }, + { + "@timestamp": 1605719148837, + "action": "repo.destroy", + "actor": "monalisa", + "created_at": 1605719148837, + "org": "mona-org", + "repo": "mona-org/mona-test-repo", + "visibility": "private" + } + ] + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "previews": [ + + ], + "category": "orgs", + "subcategory": null + } + } + }, "/orgs/{org}/blocks": { "get": { "summary": "List users blocked by an organization", diff --git a/lib/rewrite-local-links.js b/lib/rewrite-local-links.js index 4854a739cd..2cd18221c0 100644 --- a/lib/rewrite-local-links.js +++ b/lib/rewrite-local-links.js @@ -2,6 +2,7 @@ const externalRedirects = Object.keys(require('./redirects/external-sites')) const pathUtils = require('./path-utils') const assert = require('assert') const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version') +const supportedPlans = Object.values(require('./all-versions')).map(v => v.plan) // Content authors write links like `/some/article/path`, but they need to be // rewritten on the fly to match the current language and page version @@ -24,11 +25,21 @@ function getNewHref (link, languageCode, version) { // e.g. `/contact` should not be replaced with `/en/contact` if (externalRedirects.includes(href)) return + let newHref + + // If the link has a hardcoded plan name in it (e.g., /enterprise-server/rest/reference/oauth-authorizations), + // only rewrite it with a language code + if (supportedPlans.includes(href.split('/')[1])) { + newHref = pathUtils.getPathWithLanguage(href, languageCode) + } + // If link is dotcom-only, just get the language code // Otherwise, get the versioned path with language code - const newHref = link.hasClass('dotcom-only') - ? pathUtils.getVersionedPathWithLanguage(href, nonEnterpriseDefaultVersion, languageCode) - : pathUtils.getVersionedPathWithLanguage(href, version, languageCode) + if (!newHref) { + newHref = link.hasClass('dotcom-only') + ? pathUtils.getVersionedPathWithLanguage(href, nonEnterpriseDefaultVersion, languageCode) + : pathUtils.getVersionedPathWithLanguage(href, version, languageCode) + } if (href !== newHref) link.attr('href', newHref) } diff --git a/lib/site-data.js b/lib/site-data.js index 7c4ba0c988..bdd47f1ce7 100755 --- a/lib/site-data.js +++ b/lib/site-data.js @@ -2,12 +2,12 @@ const path = require('path') const flat = require('flat') const { get, set } = require('lodash') const languages = require('./languages') -const dataDirectory = require('@github-docs/data-directory') +const dataDirectory = require('./data-directory') const encodeBracketedParentheticals = require('./encode-bracketed-parentheticals') -const loadSiteDataFromDir = dir => ({ +const loadSiteDataFromDir = async dir => ({ site: { - data: dataDirectory(path.join(dir, 'data'), { + data: await dataDirectory(path.join(dir, 'data'), { preprocess: dataString => encodeBracketedParentheticals(dataString.trimEnd()), ignorePatterns: [/README\.md$/] @@ -18,7 +18,7 @@ const loadSiteDataFromDir = dir => ({ module.exports = async function loadSiteData () { // load english site data const siteData = { - en: loadSiteDataFromDir(languages.en.dir) + en: await loadSiteDataFromDir(languages.en.dir) } // load and add other language data to siteData where keys match english keys, @@ -26,7 +26,7 @@ module.exports = async function loadSiteData () { const englishKeys = Object.keys(flat(siteData.en)) for (const language of Object.values(languages)) { if (language.code === 'en') continue - const data = loadSiteDataFromDir(language.dir) + const data = await loadSiteDataFromDir(language.dir) for (const key of englishKeys) { set( siteData, diff --git a/lib/warm-server.js b/lib/warm-server.js index b123113051..36cf5e7416 100644 --- a/lib/warm-server.js +++ b/lib/warm-server.js @@ -4,6 +4,16 @@ const loadRedirects = require('./redirects/precompile') const loadSiteData = require('./site-data') const loadSiteTree = require('./site-tree') +// Instrument these functions so that +// it's wrapped in a timer that reports to Datadog +const dog = { + loadPages: statsd.asyncTimer(loadPages, 'load_pages'), + loadPageMap: statsd.asyncTimer(loadPageMap, 'load_page_map'), + loadRedirects: statsd.asyncTimer(loadRedirects, 'load_redirects'), + loadSiteData: statsd.asyncTimer(loadSiteData, 'load_site_data'), + loadSiteTree: statsd.asyncTimer(loadSiteTree, 'load_site_tree') +} + // For local caching let pageList, pageMap, site, redirects, siteTree @@ -32,21 +42,21 @@ async function warmServer () { if (!pageList || !site) { // Promise.all is used to load multiple things in parallel [pageList, site] = await Promise.all([ - pageList || loadPages(), - site || loadSiteData() + pageList || dog.loadPages(), + site || dog.loadSiteData() ]) } if (!pageMap) { - pageMap = await loadPageMap(pageList) + pageMap = await dog.loadPageMap(pageList) } if (!redirects) { - redirects = await loadRedirects(pageList, pageMap) + redirects = await dog.loadRedirects(pageList, pageMap) } if (!siteTree) { - siteTree = await loadSiteTree(pageMap, site, redirects) + siteTree = await dog.loadSiteTree(pageMap, site, redirects) } if (process.env.NODE_ENV !== 'test') { @@ -58,7 +68,7 @@ async function warmServer () { // Instrument the `warmServer` function so that // it's wrapped in a timer that reports to Datadog -const instrumentedWarmServer = statsd.asyncTimer(warmServer, 'warm_server') +dog.warmServer = statsd.asyncTimer(warmServer, 'warm_server') // We only want statistics if the priming needs to occur, so let's wrap the // real method and return early [without statistics] whenever possible @@ -68,5 +78,5 @@ module.exports = async function warmServerWrapper () { return getWarmedCache() } - return instrumentedWarmServer() + return dog.warmServer() } diff --git a/middleware/categories-for-support-team.js b/middleware/categories-for-support-team.js index 7a38fb0cde..4b550a566e 100644 --- a/middleware/categories-for-support-team.js +++ b/middleware/categories-for-support-team.js @@ -2,7 +2,7 @@ // to quickly search for Help articles by title and insert the link to // the article into a reply to a customer. const path = require('path') -const fs = require('fs') +const fs = require('fs').promises const matter = require('gray-matter') const dotcomDir = path.join(__dirname, '../content/github') const dotcomIndex = path.join(dotcomDir, 'index.md') @@ -10,24 +10,22 @@ const linkRegex = /{% (?:topic_)?link_in_list ?\/(.*?) ?%}/g module.exports = async (req, res, next) => { if (req.path !== '/categories.json') return next() - const categories = generateCategories() + const categories = await generateCategories() return res.json(categories) } -function generateCategories () { +async function generateCategories () { // get links included in dotcom index page. // each link corresponds to a dotcom subdirectory // example: getting-started-with-github - const links = getLinks(fs.readFileSync(dotcomIndex, 'utf8')) - - const categories = [] + const links = getLinks(await fs.readFile(dotcomIndex, 'utf8')) // get links included in each subdir's index page // these are links to articles - links.forEach(link => { + const categories = await Promise.all(links.map(async link => { const category = {} const indexPath = getPath(link, 'index') - const indexContents = fs.readFileSync(indexPath, 'utf8') + const indexContents = await fs.readFile(indexPath, 'utf8') const { data, content } = matter(indexContents) // get name from title frontmatter @@ -36,29 +34,23 @@ function generateCategories () { // get child article links const articleLinks = getLinks(content) - const publishedArticles = [] - - articleLinks.forEach(articleLink => { - const publishedArticle = {} - + category.published_articles = (await Promise.all(articleLinks.map(async articleLink => { // get title from frontmatter const articlePath = getPath(link, articleLink) - const articleContents = fs.readFileSync(articlePath, 'utf8') + const articleContents = await fs.readFile(articlePath, 'utf8') const { data } = matter(articleContents) // do not include map topics in list of published articles if (data.mapTopic) return - publishedArticle.title = data.title - publishedArticle.slug = articleLink + return { + title: data.title, + slug: articleLink + } + }))).filter(Boolean) - publishedArticles.push(publishedArticle) - }) - - category.published_articles = publishedArticles - - categories.push(category) - }) + return category + })) return categories } diff --git a/middleware/csp.js b/middleware/csp.js index a081f0490c..647448e928 100644 --- a/middleware/csp.js +++ b/middleware/csp.js @@ -2,47 +2,66 @@ // inline scripts and content from untrusted sources. const { contentSecurityPolicy } = require('helmet') +const isArchivedVersion = require('../lib/is-archived-version') +const versionSatisfiesRange = require('../lib/version-satisfies-range') -module.exports = contentSecurityPolicy({ - directives: { - defaultSrc: ["'none'"], - connectSrc: [ - "'self'", - '*.algolia.net', - '*.algolianet.com' - ], - fontSrc: [ - "'self'", - 'data:', - 'github-images.s3.amazonaws.com' - ], - imgSrc: [ - "'self'", - 'github.githubassets.com', - 'github-images.s3.amazonaws.com', - 'octodex.github.com', - 'placehold.it', - '*.githubusercontent.com', - 'github.com' - ], - objectSrc: [ - "'self'" - ], - scriptSrc: [ - "'self'", - 'data:' - ], - frameSrc: [ // exceptions for GraphQL Explorer - 'https://graphql-explorer.githubapp.com', // production env - 'http://localhost:3000', // development env - 'https://www.youtube-nocookie.com' - ], - styleSrc: [ - "'self'", - "'unsafe-inline'" - ], - childSrc: [ - "'self'" // exception for search in deprecated GHE versions - ] +// module.exports = contentSecurityPolicy({ +module.exports = async (req, res, next) => { + const csp = { + directives: { + defaultSrc: ["'none'"], + connectSrc: [ + "'self'", + '*.algolia.net', + '*.algolianet.com' + ], + fontSrc: [ + "'self'", + 'data:', + 'github-images.s3.amazonaws.com' + ], + imgSrc: [ + "'self'", + 'github.githubassets.com', + 'github-images.s3.amazonaws.com', + 'octodex.github.com', + 'placehold.it', + '*.githubusercontent.com', + 'github.com' + ], + objectSrc: [ + "'self'" + ], + scriptSrc: [ + "'self'", + 'data:' + ], + frameSrc: [ // exceptions for GraphQL Explorer + 'https://graphql-explorer.githubapp.com', // production env + 'http://localhost:3000', // development env + 'https://www.youtube-nocookie.com' + ], + styleSrc: [ + "'self'", + "'unsafe-inline'" + ], + childSrc: [ + "'self'" // exception for search in deprecated GHE versions + ] + } } -}) + + const { requestedVersion } = isArchivedVersion(req) + + // Exception for Algolia instantsearch in deprecated Enterprise docs (Node.js era) + if (versionSatisfiesRange(requestedVersion, '<=2.19') && versionSatisfiesRange(requestedVersion, '>2.12')) { + csp.directives.scriptSrc.push("'unsafe-eval'") + } + + // Exception for search in deprecated Enterprise docs <=2.12 (static site era) + if (versionSatisfiesRange(requestedVersion, '<=2.12')) { + csp.directives.scriptSrc.push("'unsafe-inline'") + } + + return contentSecurityPolicy(csp)(req, res, next) +} diff --git a/package-lock.json b/package-lock.json index b33963cf8b..e4cee8054d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2969,36 +2969,6 @@ } } }, - "@github-docs/data-directory": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/@github-docs/data-directory/-/data-directory-1.2.0.tgz", - "integrity": "sha512-hp+Ubwl8e77EdnR4OncSUIE7G/cMn9ENOo6ABy8FjqdYCbAWgb/79w7yXVebIV5P3q5r6KAAqPzHj1N5SSrBgw==", - "requires": { - "lodash": "^4.17.15", - "walk-sync": "^2.0.2" - }, - "dependencies": { - "matcher-collection": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/matcher-collection/-/matcher-collection-2.0.1.tgz", - "integrity": "sha512-daE62nS2ZQsDg9raM0IlZzLmI2u+7ZapXBwdoeBUKAYERPDDIc0qNqA8E0Rp2D+gspKR7BgIFP52GeujaGXWeQ==", - "requires": { - "@types/minimatch": "^3.0.3", - "minimatch": "^3.0.2" - } - }, - "walk-sync": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/walk-sync/-/walk-sync-2.1.0.tgz", - "integrity": "sha512-KpH9Xw64LNSx7/UI+3guRZvJWlDxVA4+KKb/4puRoVrG8GkvZRxnF3vhxdjgpoKJGL2TVg1OrtkXIE/VuGPLHQ==", - "requires": { - "@types/minimatch": "^3.0.3", - "ensure-posix-path": "^1.1.0", - "matcher-collection": "^2.0.0" - } - } - } - }, "@github-docs/frontmatter": { "version": "1.3.1", "resolved": "https://registry.npmjs.org/@github-docs/frontmatter/-/frontmatter-1.3.1.tgz", @@ -5301,7 +5271,7 @@ }, "agentkeepalive": { "version": "2.2.0", - "resolved": "http://registry.npmjs.org/agentkeepalive/-/agentkeepalive-2.2.0.tgz", + "resolved": "https://registry.npmjs.org/agentkeepalive/-/agentkeepalive-2.2.0.tgz", "integrity": "sha1-xdG9SxKQCPEWPyNvhuX66iAm4u8=" }, "aggregate-error": { @@ -5447,7 +5417,7 @@ "argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", - "integrity": "sha1-vNZ5HqWuCXJeF+WtmIE0zUCz2RE=", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", "requires": { "sprintf-js": "~1.0.2" } @@ -5577,8 +5547,7 @@ "async": { "version": "3.2.0", "resolved": "https://registry.npmjs.org/async/-/async-3.2.0.tgz", - "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw==", - "dev": true + "integrity": "sha512-TR2mEZFVOj2pLStYxLht7TyfuRzaydfpxr3k9RpHIzMgw7A64dzsdqCxH1WJyQdoe8T10nDXd9wnEigmiuHIZw==" }, "async-each": { "version": "1.0.3", @@ -6825,7 +6794,7 @@ }, "brfs": { "version": "1.6.1", - "resolved": "http://registry.npmjs.org/brfs/-/brfs-1.6.1.tgz", + "resolved": "https://registry.npmjs.org/brfs/-/brfs-1.6.1.tgz", "integrity": "sha512-OfZpABRQQf+Xsmju8XE9bDjs+uU4vLREGolP7bDgcpsI17QREyZ4Bl+2KLxxx1kCgA0fAIhKQBaBYh+PEcCqYQ==", "requires": { "quote-stream": "^1.0.1", @@ -9434,7 +9403,7 @@ "error-ex": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", - "integrity": "sha1-tKxAZIEH/c3PriQvQovqihTU8b8=", + "integrity": "sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==", "requires": { "is-arrayish": "^0.2.1" } @@ -12578,7 +12547,7 @@ "dependencies": { "mkdirp": { "version": "0.3.0", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.3.0.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.3.0.tgz", "integrity": "sha1-G79asbqCevI1dRQ0kEJkVfSB/h4=" }, "nopt": { @@ -17704,7 +17673,7 @@ }, "magic-string": { "version": "0.22.5", - "resolved": "http://registry.npmjs.org/magic-string/-/magic-string-0.22.5.tgz", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.22.5.tgz", "integrity": "sha512-oreip9rJZkzvA8Qzk9HFs8fZGF/u7H/gtrE8EN6RjKJ9kh2HlC+yQ2QezifqTZfGyiuAV0dRv5a+y/8gBb1m9w==", "requires": { "vlq": "^0.2.2" diff --git a/package.json b/package.json index bb0f35f588..545de58826 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,6 @@ "@babel/preset-env": "^7.12.7", "@babel/preset-react": "^7.12.7", "@babel/runtime": "^7.11.2", - "@github-docs/data-directory": "^1.2.0", "@github-docs/frontmatter": "^1.3.1", "@graphql-inspector/core": "^2.3.0", "@graphql-tools/load": "^6.2.5", @@ -27,6 +26,7 @@ "@primer/css": "^15.1.0", "@primer/octicons": "^11.0.0", "algoliasearch": "^3.35.1", + "async": "^3.2.0", "babel-loader": "^8.1.0", "babel-preset-env": "^1.7.0", "browser-date-formatter": "^3.0.3", @@ -94,7 +94,6 @@ "devDependencies": { "@actions/core": "^1.2.6", "ajv": "^6.11.0", - "async": "^3.2.0", "await-sleep": "0.0.1", "aws-sdk": "^2.610.0", "babel-eslint": "^10.1.0", @@ -181,4 +180,4 @@ "pre-push": "npm run prevent-pushes-to-main" } } -} \ No newline at end of file +} diff --git a/script/check-s3-images.js b/script/check-s3-images.js index 00ef528b7c..6c83a4dc8a 100755 --- a/script/check-s3-images.js +++ b/script/check-s3-images.js @@ -12,6 +12,7 @@ const patterns = require('../lib/patterns') const authenticateToAWS = require('../lib/authenticate-to-aws.js') const readlineSync = require('readline-sync') const { execSync } = require('child_process') +const enterpriseServerVersions = Object.keys(allVersions).filter(v => v.startsWith('enterprise-server@')) const uploadScript = path.join(process.cwd(), 'script/upload-images-to-s3.js') // ignore the non-enterprise default version @@ -51,7 +52,8 @@ async function main () { page, site: siteData, currentVersion: version, - currentLanguage: 'en' + currentLanguage: 'en', + enterpriseServerVersions } const rendered = await renderContent(page.markdown, context) diff --git a/server.js b/server.js index ce00b05169..744d1fa924 100644 --- a/server.js +++ b/server.js @@ -18,14 +18,8 @@ if (!module.parent) { if (status === false) { // If in a deployed environment, warm the server at the start if (process.env.NODE_ENV === 'production') { - // If in a true production environment, wait for the cache to be fully warmed. - if (process.env.HEROKU_PRODUCTION_APP) { - await warmServer() - } else { - // If not in a true production environment, don't wait for the cache to be fully warmed. - // This avoids deployment timeouts in environments with slower servers. - warmServer() - } + // If in a production environment, wait for the cache to be fully warmed. + await warmServer() } // workaround for https://github.com/expressjs/express/issues/1101 diff --git a/tests/browser/browser.js b/tests/browser/browser.js index 64fdb083ab..aca6b864a7 100644 --- a/tests/browser/browser.js +++ b/tests/browser/browser.js @@ -3,6 +3,8 @@ const sleep = require('await-sleep') const querystring = require('querystring') describe('homepage', () => { + jest.setTimeout(60 * 1000) + test('should be titled "GitHub Documentation"', async () => { await page.goto('http://localhost:4001') await expect(page.title()).resolves.toMatch('GitHub Documentation') @@ -10,6 +12,8 @@ describe('homepage', () => { }) describe('algolia browser search', () => { + jest.setTimeout(60 * 1000) + it('works on the homepage', async () => { await page.goto('http://localhost:4001/en') await page.click('#search-input-container input[type="search"]') diff --git a/tests/content/category-pages.js b/tests/content/category-pages.js index 3eb1214605..218301846e 100644 --- a/tests/content/category-pages.js +++ b/tests/content/category-pages.js @@ -42,7 +42,7 @@ describe('category pages', () => { // Get links included in product index page. // Each link corresponds to a product subdirectory (category). // Example: "getting-started-with-github" - const contents = fs.readFileSync(productIndex, 'utf8') + const contents = fs.readFileSync(productIndex, 'utf8') // TODO move to async const { content } = matter(contents) const productDir = path.dirname(productIndex) @@ -50,6 +50,7 @@ describe('category pages', () => { const categoryLinks = getLinks(content) // Only include category directories, not standalone category files like content/actions/quickstart.md .filter(link => fs.existsSync(getPath(productDir, link, 'index'))) + // TODO this should move to async, but you can't asynchronously define tests with Jest... // Map those to the Markdown file paths that represent that category page index const categoryPaths = categoryLinks.map(link => getPath(productDir, link, 'index')) diff --git a/tests/content/crowdin-config.js b/tests/content/crowdin-config.js index 63301e0993..fd26e74b42 100644 --- a/tests/content/crowdin-config.js +++ b/tests/content/crowdin-config.js @@ -4,6 +4,8 @@ const ignoredPagePaths = config.files[0].ignore const ignoredDataPaths = config.files[2].ignore describe('crowdin.yml config file', () => { + jest.setTimeout(60 * 1000) + let pages beforeAll(async (done) => { pages = await loadPages() diff --git a/tests/content/featured-links.js b/tests/content/featured-links.js index c5b476153b..9829f1abd7 100644 --- a/tests/content/featured-links.js +++ b/tests/content/featured-links.js @@ -45,8 +45,9 @@ describe('featuredLinks', () => { test('featured links respect versioning', async () => { const $ = await getDOM(`/en/enterprise/${enterpriseServerReleases.latest}/user/packages`) - const $featuredLinks = $('.featured-links a') + const $featuredLinks = $('.all-articles-list a') expect($featuredLinks.length).toBeGreaterThan(2) + expect($featuredLinks.text().includes('Package client guides for GitHub Packages')).toBe(true) // does not include dotcom-only links expect($featuredLinks.text().includes('About GitHub Container Registry')).toBe(false) expect($featuredLinks.text().includes('Getting started with GitHub Container Registry')).toBe(false) diff --git a/tests/content/glossary.js b/tests/content/glossary.js index 3e3aea66f9..3f278e5016 100644 --- a/tests/content/glossary.js +++ b/tests/content/glossary.js @@ -9,7 +9,10 @@ describe('glossaries', () => { test('are broken into external, internal, and candidates', async () => { const keys = Object.keys(glossaries) - expect(keys).toEqual(['candidates', 'external', 'internal']) + expect(keys).toHaveLength(3) + expect(keys).toContain('candidates') + expect(keys).toContain('external') + expect(keys).toContain('internal') }) test('every entry has a valid term', async () => { diff --git a/tests/content/remove-liquid-statements.js b/tests/content/remove-liquid-statements.js index 80fd021669..f94dd5ae5c 100644 --- a/tests/content/remove-liquid-statements.js +++ b/tests/content/remove-liquid-statements.js @@ -1,4 +1,4 @@ -const fs = require('fs') +const fs = require('fs').promises const path = require('path') const cheerio = require('cheerio') const matter = require('gray-matter') @@ -35,8 +35,8 @@ function processFrontmatter (contents, file) { } describe('removing liquid statements only', () => { - test('removes liquid statements that specify "greater than version to deprecate"', () => { - let contents = fs.readFileSync(greaterThan, 'utf8') + test('removes liquid statements that specify "greater than version to deprecate"', async () => { + let contents = await fs.readFile(greaterThan, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('Alpha') @@ -57,8 +57,8 @@ Alpha\n\n{% else %}\n\nBravo\n\n{% if currentVersion ver_gt "enterprise-server@2 expect($('.example10').text().trim()).toBe('Alpha') }) - test('removes liquid statements that specify "and greater than version to deprecate"', () => { - let contents = fs.readFileSync(andGreaterThan1, 'utf8') + test('removes liquid statements that specify "and greater than version to deprecate"', async () => { + let contents = await fs.readFile(andGreaterThan1, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('{% if currentVersion != "free-pro-team@latest" %}\n\nAlpha\n\n{% endif %}') @@ -71,8 +71,8 @@ Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif Alpha\n\n{% if currentVersion ver_gt "enterprise-server@2.16" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`) }) - test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', () => { - let contents = fs.readFileSync(andGreaterThan2, 'utf8') + test('removes liquid statements that specify "and greater than version to deprecate" (alternate format)', async () => { + let contents = await fs.readFile(andGreaterThan2, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nAlpha\n\n{% endif %}') @@ -85,8 +85,8 @@ Alpha\n\n{% if currentVersion ver_lt "enterprise-server@2.16" %}\n\nBravo\n\n{% Alpha\n\n{% if currentVersion != "free-pro-team@latest" %}\n\nBravo\n\n{% endif %}\n\n{% endif %}`) }) - test('removes liquid statements that specify "not equals version to deprecate"', () => { - let contents = fs.readFileSync(notEquals, 'utf8') + test('removes liquid statements that specify "not equals version to deprecate"', async () => { + let contents = await fs.readFile(notEquals, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('Alpha') @@ -103,8 +103,8 @@ Alpha\n\n{% endif %}`) }) describe('removing liquid statements and content', () => { - test('removes interior content and liquid statements that specify "equals version to deprecate"', () => { - let contents = fs.readFileSync(equals, 'utf8') + test('removes interior content and liquid statements that specify "equals version to deprecate"', async () => { + let contents = await fs.readFile(equals, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('') @@ -117,8 +117,8 @@ Alpha\n\n{% else %}\n\nCharlie\n\n{% endif %}`) expect($('.example6').text().trim()).toBe('Charlie\n\nBravo') }) - test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', () => { - let contents = fs.readFileSync(lessThanNextOldest, 'utf8') + test('removes interior content and liquid statements that specify "less than next oldest than version to deprecate"', async () => { + let contents = await fs.readFile(lessThanNextOldest, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text().trim()).toBe('Alpha') @@ -137,8 +137,8 @@ Charlie\n\n{% else %}\n\nDelta\n\n{% endif %}\n\nEcho`) }) describe('updating frontmatter', () => { - test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', () => { - let contents = fs.readFileSync(frontmatter1, 'utf8') + test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to version to deprecate', async () => { + let contents = await fs.readFile(frontmatter1, 'utf8') contents = processFrontmatter(contents, frontmatter1) const $ = cheerio.load(contents) // console.log('foo') @@ -147,8 +147,8 @@ describe('updating frontmatter', () => { expect($.text().includes('enterprise-server: \'>=2.13\'')).toBe(false) }) - test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', () => { - let contents = fs.readFileSync(frontmatter2, 'utf8') + test('updates frontmatter versions Enterprise if set to greater-than-or-equal-to next oldest version', async () => { + let contents = await fs.readFile(frontmatter2, 'utf8') contents = processFrontmatter(contents, frontmatter2) const $ = cheerio.load(contents) expect($.text().includes('enterprise-server: \'*\'')).toBe(true) @@ -157,8 +157,8 @@ describe('updating frontmatter', () => { }) describe('whitespace', () => { - test('does not add newlines when whitespace control is used', () => { - let contents = fs.readFileSync(whitespace, 'utf8') + test('does not add newlines when whitespace control is used', async () => { + let contents = await fs.readFile(whitespace, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example1').text()).toBe('\n Alpha\n') @@ -167,8 +167,8 @@ describe('whitespace', () => { expect($('.example4').text()).toBe('\n Alpha\n') }) - test('does not add newlines when no newlines are present', () => { - let contents = fs.readFileSync(whitespace, 'utf8') + test('does not add newlines when no newlines are present', async () => { + let contents = await fs.readFile(whitespace, 'utf8') contents = removeLiquidStatements(contents, versionToDeprecate, nextOldestVersion) const $ = cheerio.load(contents) expect($('.example5').text()).toBe('\n Alpha\n') diff --git a/tests/content/site-data-references.js b/tests/content/site-data-references.js index c6f0a019bd..045e33843b 100644 --- a/tests/content/site-data-references.js +++ b/tests/content/site-data-references.js @@ -3,10 +3,12 @@ const loadSiteData = require('../../lib/site-data') const { loadPages } = require('../../lib/pages') const getDataReferences = require('../../lib/get-liquid-data-references') const frontmatter = require('@github-docs/frontmatter') -const fs = require('fs') +const fs = require('fs').promises const path = require('path') describe('data references', () => { + jest.setTimeout(60 * 1000) + let data, pages beforeAll(async (done) => { @@ -33,34 +35,34 @@ describe('data references', () => { expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0) }) - test('every data reference found in metadata of English content files is defined and has a value', () => { + test('every data reference found in metadata of English content files is defined and has a value', async () => { let errors = [] expect(pages.length).toBeGreaterThan(0) - pages.forEach(page => { + await Promise.all(pages.map(async page => { const metadataFile = path.join('content', page.relativePath) - const fileContents = fs.readFileSync(path.join(__dirname, '../..', metadataFile)) + const fileContents = await fs.readFile(path.join(__dirname, '../..', metadataFile)) const { data: metadata } = frontmatter(fileContents, { filepath: page.fullPath }) const metadataRefs = getDataReferences(JSON.stringify(metadata)) metadataRefs.forEach(key => { const value = get(data.en, key) if (typeof value !== 'string') errors.push({ key, value, metadataFile }) }) - }) + })) errors = uniqWith(errors, isEqual) // remove duplicates expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0) }) - test('every data reference found in English reusable files is defined and has a value', () => { + test('every data reference found in English reusable files is defined and has a value', async () => { let errors = [] const allReusables = data.en.site.data.reusables const reusables = Object.values(allReusables) expect(reusables.length).toBeGreaterThan(0) - reusables.forEach(reusablesPerFile => { + await Promise.all(reusables.map(async reusablesPerFile => { let reusableFile = path.join(__dirname, '../../data/reusables/', getFilenameByValue(allReusables, reusablesPerFile)) - reusableFile = getFilepath(reusableFile) + reusableFile = await getFilepath(reusableFile) const reusableRefs = getDataReferences(JSON.stringify(reusablesPerFile)) @@ -68,21 +70,21 @@ describe('data references', () => { const value = get(data.en, key) if (typeof value !== 'string') errors.push({ key, value, reusableFile }) }) - }) + })) errors = uniqWith(errors, isEqual) // remove duplicates expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0) }) - test('every data reference found in English variable files is defined and has a value', () => { + test('every data reference found in English variable files is defined and has a value', async () => { let errors = [] const allVariables = data.en.site.data.variables const variables = Object.values(allVariables) expect(variables.length).toBeGreaterThan(0) - variables.forEach(variablesPerFile => { + await Promise.all(variables.map(async variablesPerFile => { let variableFile = path.join(__dirname, '../../data/variables/', getFilenameByValue(allVariables, variablesPerFile)) - variableFile = getFilepath(variableFile) + variableFile = await getFilepath(variableFile) const variableRefs = getDataReferences(JSON.stringify(variablesPerFile)) @@ -90,7 +92,7 @@ describe('data references', () => { const value = get(data.en, key) if (typeof value !== 'string') errors.push({ key, value, variableFile }) }) - }) + })) errors = uniqWith(errors, isEqual) // remove duplicates expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0) @@ -102,10 +104,13 @@ function getFilenameByValue (object, value) { } // if path exists, assume it's a directory; otherwise, assume a YML extension -function getFilepath (filepath) { - filepath = fs.existsSync(filepath) - ? filepath + '/' - : filepath + '.yml' +async function getFilepath (filepath) { + try { + await fs.stat(filepath) + filepath = filepath + '/' + } catch (_) { + filepath = filepath + '.yml' + } // we only need the relative path return filepath.replace(path.join(__dirname, '../../'), '') diff --git a/tests/content/site-data.js b/tests/content/site-data.js index e563df27d3..adbdaa7596 100644 --- a/tests/content/site-data.js +++ b/tests/content/site-data.js @@ -45,11 +45,11 @@ describe('siteData module (English)', () => { // TODO: re-enable once Janky flakyness is resolved test.skip('backfills missing translated site data with English values', async () => { const newFile = path.join(__dirname, '../../data/newfile.yml') - fs.writeFileSync(newFile, 'newvalue: bar') + await fs.writeFile(newFile, 'newvalue: bar') const data = await loadSiteData() expect(get(data, 'en.site.data.newfile.newvalue')).toEqual('bar') expect(get(data, 'ja.site.data.newfile.newvalue')).toEqual('bar') - fs.unlinkSync(newFile) + await fs.unlink(newFile) }) test('all Liquid templating is valid', async () => { diff --git a/tests/fixtures/rest-redirects.json b/tests/fixtures/rest-redirects.json index 01470158f7..d6b4e852f2 100644 --- a/tests/fixtures/rest-redirects.json +++ b/tests/fixtures/rest-redirects.json @@ -219,7 +219,7 @@ "/en/enterprise/2.20/v3/enterprise-admin/orgs": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#orgs", "/en/enterprise/2.20/v3/enterprise-admin/pre_receive_environments": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#pre-receive-environments", "/en/enterprise/2.20/v3/enterprise-admin/pre_receive_hooks": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#pre-receive-hooks", - "/en/enterprise/2.20/v3/enterprise-admin/repo_pre_receive_hooks": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#repo-pre-receive-hooks", + "/en/enterprise/2.20/v3/enterprise-admin/repo_pre_receive_hooks": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#repository-pre-receive-hooks", "/en/enterprise/2.20/v3/enterprise-admin/search_indexing": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#search-indexing", "/en/enterprise/2.20/v3/enterprise-admin/users": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#users", "/en/enterprise/2.20/v3/gists/comments": "/en/enterprise-server@2.20/rest/reference/gists#comments", @@ -243,7 +243,7 @@ "/en/enterprise/2.20/v3/markdown": "/en/enterprise-server@2.20/rest/reference/markdown", "/en/enterprise/2.20/v3/meta": "/en/enterprise-server@2.20/rest/reference/meta", "/en/enterprise/2.20/v3/oauth_authorizations": "/en/enterprise-server@2.20/rest/reference/oauth-authorizations", - "/en/enterprise/2.20/v3/orgs/hooks": "/en/enterprise-server@2.20/rest/reference/orgs#hooks", + "/en/enterprise/2.20/v3/orgs/hooks": "/en/enterprise-server@2.20/rest/reference/orgs#webhooks", "/en/enterprise/2.20/v3/orgs": "/en/enterprise-server@2.20/rest/reference/orgs", "/en/enterprise/2.20/v3/orgs/members": "/en/enterprise-server@2.20/rest/reference/orgs#members", "/en/enterprise/2.20/v3/orgs/outside_collaborators": "/en/enterprise-server@2.20/rest/reference/orgs#outside-collaborators", @@ -267,13 +267,13 @@ "/en/enterprise/2.20/v3/repos/deployments": "/en/enterprise-server@2.20/rest/reference/repos#deployments", "/en/enterprise/2.20/v3/repos/downloads": "/en/enterprise-server@2.20/rest/reference/repos#downloads", "/en/enterprise/2.20/v3/repos/forks": "/en/enterprise-server@2.20/rest/reference/repos#forks", - "/en/enterprise/2.20/v3/repos/hooks": "/en/enterprise-server@2.20/rest/reference/repos#hooks", + "/en/enterprise/2.20/v3/repos/hooks": "/en/enterprise-server@2.20/rest/reference/repos#webhooks", "/en/enterprise/2.20/v3/repos": "/en/enterprise-server@2.20/rest/reference/repos", "/en/enterprise/2.20/v3/repos/invitations": "/en/enterprise-server@2.20/rest/reference/repos#invitations", "/en/enterprise/2.20/v3/repos/keys": "/en/enterprise-server@2.20/rest/reference/repos#keys", "/en/enterprise/2.20/v3/repos/merging": "/en/enterprise-server@2.20/rest/reference/repos#merging", "/en/enterprise/2.20/v3/repos/pages": "/en/enterprise-server@2.20/rest/reference/repos#pages", - "/en/enterprise/2.20/v3/repos/pre_receive_hooks": "/en/enterprise-server@2.20/rest/reference/repos#pre-receive-hooks", + "/en/enterprise/2.20/v3/repos/pre_receive_hooks": "/en/enterprise-server@2.20/rest/reference/enterprise-admin#repository-pre-receive-hooks", "/en/enterprise/2.20/v3/repos/releases": "/en/enterprise-server@2.20/rest/reference/repos#releases", "/en/enterprise/2.20/v3/repos/statistics": "/en/enterprise-server@2.20/rest/reference/repos#statistics", "/en/enterprise/2.20/v3/repos/statuses": "/en/enterprise-server@2.20/rest/reference/repos#statuses", @@ -316,7 +316,7 @@ "/en/enterprise/2.21/v3/enterprise-admin/orgs": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#orgs", "/en/enterprise/2.21/v3/enterprise-admin/pre_receive_environments": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#pre-receive-environments", "/en/enterprise/2.21/v3/enterprise-admin/pre_receive_hooks": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#pre-receive-hooks", - "/en/enterprise/2.21/v3/enterprise-admin/repo_pre_receive_hooks": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#repo-pre-receive-hooks", + "/en/enterprise/2.21/v3/enterprise-admin/repo_pre_receive_hooks": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#repository-pre-receive-hooks", "/en/enterprise/2.21/v3/enterprise-admin/search_indexing": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#search-indexing", "/en/enterprise/2.21/v3/enterprise-admin/users": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#users", "/en/enterprise/2.21/v3/gists/comments": "/en/enterprise-server@2.21/rest/reference/gists#comments", @@ -340,7 +340,7 @@ "/en/enterprise/2.21/v3/markdown": "/en/enterprise-server@2.21/rest/reference/markdown", "/en/enterprise/2.21/v3/meta": "/en/enterprise-server@2.21/rest/reference/meta", "/en/enterprise/2.21/v3/oauth_authorizations": "/en/enterprise-server@2.21/rest/reference/oauth-authorizations", - "/en/enterprise/2.21/v3/orgs/hooks": "/en/enterprise-server@2.21/rest/reference/orgs#hooks", + "/en/enterprise/2.21/v3/orgs/hooks": "/en/enterprise-server@2.21/rest/reference/orgs#webhooks", "/en/enterprise/2.21/v3/orgs": "/en/enterprise-server@2.21/rest/reference/orgs", "/en/enterprise/2.21/v3/orgs/members": "/en/enterprise-server@2.21/rest/reference/orgs#members", "/en/enterprise/2.21/v3/orgs/outside_collaborators": "/en/enterprise-server@2.21/rest/reference/orgs#outside-collaborators", @@ -364,13 +364,13 @@ "/en/enterprise/2.21/v3/repos/deployments": "/en/enterprise-server@2.21/rest/reference/repos#deployments", "/en/enterprise/2.21/v3/repos/downloads": "/en/enterprise-server@2.21/rest/reference/repos#downloads", "/en/enterprise/2.21/v3/repos/forks": "/en/enterprise-server@2.21/rest/reference/repos#forks", - "/en/enterprise/2.21/v3/repos/hooks": "/en/enterprise-server@2.21/rest/reference/repos#hooks", + "/en/enterprise/2.21/v3/repos/hooks": "/en/enterprise-server@2.21/rest/reference/repos#webhooks", "/en/enterprise/2.21/v3/repos": "/en/enterprise-server@2.21/rest/reference/repos", "/en/enterprise/2.21/v3/repos/invitations": "/en/enterprise-server@2.21/rest/reference/repos#invitations", "/en/enterprise/2.21/v3/repos/keys": "/en/enterprise-server@2.21/rest/reference/repos#keys", "/en/enterprise/2.21/v3/repos/merging": "/en/enterprise-server@2.21/rest/reference/repos#merging", "/en/enterprise/2.21/v3/repos/pages": "/en/enterprise-server@2.21/rest/reference/repos#pages", - "/en/enterprise/2.21/v3/repos/pre_receive_hooks": "/en/enterprise-server@2.21/rest/reference/repos#pre-receive-hooks", + "/en/enterprise/2.21/v3/repos/pre_receive_hooks": "/en/enterprise-server@2.21/rest/reference/enterprise-admin#repository-pre-receive-hooks", "/en/enterprise/2.21/v3/repos/releases": "/en/enterprise-server@2.21/rest/reference/repos#releases", "/en/enterprise/2.21/v3/repos/statistics": "/en/enterprise-server@2.21/rest/reference/repos#statistics", "/en/enterprise/2.21/v3/repos/statuses": "/en/enterprise-server@2.21/rest/reference/repos#statuses", @@ -453,7 +453,7 @@ "/v3/migrations/users": "/en/free-pro-team@latest/rest/reference/migrations#users", "/v3/oauth_authorizations": "/en/enterprise-server/rest/reference/oauth-authorizations", "/v3/orgs/blocking": "/en/free-pro-team@latest/rest/reference/orgs#blocking", - "/v3/orgs/hooks": "/en/free-pro-team@latest/rest/reference/orgs#hooks", + "/v3/orgs/hooks": "/en/free-pro-team@latest/rest/reference/orgs#webhooks", "/v3/orgs": "/en/free-pro-team@latest/rest/reference/orgs", "/v3/orgs/members": "/en/free-pro-team@latest/rest/reference/orgs#members", "/v3/orgs/migrations": "/en/free-pro-team@latest/rest/reference/orgs#migrations", @@ -479,13 +479,13 @@ "/v3/repos/deployments": "/en/free-pro-team@latest/rest/reference/repos#deployments", "/v3/repos/downloads": "/en/free-pro-team@latest/rest/reference/repos#downloads", "/v3/repos/forks": "/en/free-pro-team@latest/rest/reference/repos#forks", - "/v3/repos/hooks": "/en/free-pro-team@latest/rest/reference/repos#hooks", + "/v3/repos/hooks": "/en/free-pro-team@latest/rest/reference/repos#webhooks", "/v3/repos": "/en/free-pro-team@latest/rest/reference/repos", "/v3/repos/invitations": "/en/free-pro-team@latest/rest/reference/repos#invitations", "/v3/repos/keys": "/en/free-pro-team@latest/rest/reference/repos#keys", "/v3/repos/merging": "/en/free-pro-team@latest/rest/reference/repos#merging", "/v3/repos/pages": "/en/free-pro-team@latest/rest/reference/repos#pages", - "/v3/repos/pre_receive_hooks": "/en/free-pro-team@latest/rest/reference/repos#pre-receive-hooks", + "/v3/repos/pre_receive_hooks": "/en/enterprise-server/rest/reference/enterprise-admin#repository-pre-receive-hooks", "/v3/repos/releases": "/en/free-pro-team@latest/rest/reference/repos#releases", "/v3/repos/statistics": "/en/free-pro-team@latest/rest/reference/repos#statistics", "/v3/repos/statuses": "/en/free-pro-team@latest/rest/reference/repos#statuses", diff --git a/tests/graphql/build-changelog-test.js b/tests/graphql/build-changelog-test.js index 1a55d59bab..4620d4aeee 100644 --- a/tests/graphql/build-changelog-test.js +++ b/tests/graphql/build-changelog-test.js @@ -1,6 +1,6 @@ const yaml = require('js-yaml') const { createChangelogEntry, cleanPreviewTitle, previewAnchor, prependDatedEntry } = require('../../script/graphql/build-changelog') -const fs = require('fs') +const fs = require('fs').promises const MockDate = require('mockdate') const expectedChangelogEntry = require('../fixtures/changelog-entry') const expectedUpdatedChangelogFile = require('../fixtures/updated-changelog-file') @@ -111,18 +111,18 @@ describe('updating the changelog file', () => { MockDate.reset() }) - it('modifies the entry object and the file on disk', () => { + it('modifies the entry object and the file on disk', async () => { const testTargetPath = 'tests/graphql/example_changelog.json' - const previousContents = fs.readFileSync(testTargetPath) + const previousContents = await fs.readFile(testTargetPath) const exampleEntry = { someStuff: true } const expectedDate = '2020-11-20' MockDate.set(expectedDate) prependDatedEntry(exampleEntry, testTargetPath) - const newContents = fs.readFileSync(testTargetPath, 'utf8') + const newContents = await fs.readFile(testTargetPath, 'utf8') // reset the file: - fs.writeFileSync(testTargetPath, previousContents) + await fs.writeFile(testTargetPath, previousContents) expect(exampleEntry).toEqual({ someStuff: true, date: expectedDate }) expect(JSON.parse(newContents)).toEqual(expectedUpdatedChangelogFile) diff --git a/tests/meta/orphan-tests.js b/tests/meta/orphan-tests.js index 770b10389c..9d561140c6 100644 --- a/tests/meta/orphan-tests.js +++ b/tests/meta/orphan-tests.js @@ -1,20 +1,28 @@ -const fs = require('fs') +const fs = require('fs').promises const path = require('path') +const { filter: asyncFilter } = require('async') describe('check for orphan tests', () => { - test('all tests are in sub-directories', () => { + test('all tests are in sub-directories', async () => { // A known list of exceptions that can live outside of directories const EXCEPTIONS = ['README.md'] const pathToTests = path.join(process.cwd(), 'tests') // Get a list of files/directories in `/tests` - const testDirectory = fs.readdirSync(pathToTests) + const testDirectory = await fs.readdir(pathToTests) - const filteredList = testDirectory + let filteredList = testDirectory // Filter out our exceptions .filter(item => !EXCEPTIONS.includes(item)) - // Don't include directories - .filter(item => !fs.statSync(path.join(pathToTests, item)).isDirectory()) + // Don't include directories + filteredList = await asyncFilter( + filteredList, + async item => !( + await fs.stat( + path.join(pathToTests, item) + ) + ).isDirectory() + ) expect(filteredList).toHaveLength(0) }) diff --git a/tests/rendering/rest.js b/tests/rendering/rest.js index d26e1b74ad..34a9428a04 100644 --- a/tests/rendering/rest.js +++ b/tests/rendering/rest.js @@ -1,4 +1,4 @@ -const fs = require('fs') +const fs = require('fs').promises const path = require('path') const { difference, isPlainObject } = require('lodash') const { getJSON } = require('../helpers/supertest') @@ -17,7 +17,7 @@ describe('REST references docs', () => { test('markdown file exists for every operationId prefix in the api.github.com schema', async () => { const { categories } = require('../../lib/rest') const referenceDir = path.join(__dirname, '../../content/rest/reference') - const filenames = fs.readdirSync(referenceDir) + const filenames = (await fs.readdir(referenceDir)) .filter(filename => !excludeFromResourceNameCheck.find(excludedFile => filename.endsWith(excludedFile))) .map(filename => filename.replace('.md', '')) diff --git a/tests/routing/developer-site-redirects.js b/tests/routing/developer-site-redirects.js index 7378066dc9..d44d90360b 100644 --- a/tests/routing/developer-site-redirects.js +++ b/tests/routing/developer-site-redirects.js @@ -1,7 +1,6 @@ const { eachOfLimit } = require('async') const enterpriseServerReleases = require('../../lib/enterprise-server-releases') const { get } = require('../helpers/supertest') -const { getEnterpriseVersionNumber } = require('../../lib/patterns') const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version') const restRedirectFixtures = require('../fixtures/rest-redirects') const graphqlRedirectFixtures = require('../fixtures/graphql-redirects') @@ -126,29 +125,6 @@ describe('developer redirects', () => { ) }) - // TODO temprarily ensure we redirect old links using the new enterprise format - // for currently supported enterprise releases only - // EXAMPLE: /en/enterprise-server@2.20/v3/pulls/comments -> /en/enterprise-server@2.20/rest/reference/pulls#comments - // We can remove test after we update all the old `/v3` links to point to `/rest` - test('temporary rest reference enterprise redirects', async () => { - await eachOfLimit( - restRedirectFixtures, - MAX_CONCURRENT_REQUESTS, - async (newPath, oldPath) => { - const releaseNumber = oldPath.match(getEnterpriseVersionNumber) - if (!releaseNumber) return - if (!enterpriseServerReleases.supported.includes(releaseNumber[1])) return - - oldPath = oldPath - .replace(/\/enterprise\/(\d.\d\d)\//, '/enterprise-server@$1/') - .replace('/user/', '/') - const res = await get(oldPath) - expect(res.statusCode, `${oldPath} did not redirect to ${newPath}`).toBe(301) - expect(res.headers.location).toBe(newPath) - } - ) - }) - // this fixtures file includes /v4 and /enterprise/v4 paths test('graphql reference redirects', async () => { await eachOfLimit( @@ -164,28 +140,5 @@ describe('developer redirects', () => { } ) }) - - // TODO temprarily ensure we redirect old links using the new enterprise format - // for currently supported enterprise releases only - // EXAMPLE: /en/enterprise-server@2.20/v4/interface/actor -> /en/enterprise-server@2.20/graphql/reference/interfaces#actor - // We can remove test after we update all the old `/v4` links to point to `/graphql` - test('temporary rest reference enterprise redirects', async () => { - await eachOfLimit( - graphqlRedirectFixtures, - MAX_CONCURRENT_REQUESTS, - async (newPath, oldPath) => { - const releaseNumber = oldPath.match(getEnterpriseVersionNumber) - if (!releaseNumber) return - if (!enterpriseServerReleases.supported.includes(releaseNumber[1])) return - - oldPath = oldPath - .replace(/\/enterprise\/(\d.\d\d)\//, '/enterprise-server@$1/') - .replace('/user/', '/') - const res = await get(oldPath) - expect(res.statusCode, `${oldPath} did not redirect to ${newPath}`).toBe(301) - expect(res.headers.location).toBe(newPath) - } - ) - }) }) }) diff --git a/tests/routing/redirects.js b/tests/routing/redirects.js index 740cd67d55..b41a0888a8 100644 --- a/tests/routing/redirects.js +++ b/tests/routing/redirects.js @@ -17,8 +17,8 @@ describe('redirects', () => { done() }) - test('page.redirects is an array', () => { - const page = new Page({ + test('page.redirects is an array', async () => { + const page = await Page.init({ relativePath: 'github/collaborating-with-issues-and-pull-requests/about-branches.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -26,8 +26,8 @@ describe('redirects', () => { expect(isPlainObject(page.redirects)).toBe(true) }) - test('dotcom homepage page.redirects', () => { - const page = new Page({ + test('dotcom homepage page.redirects', async () => { + const page = await Page.init({ relativePath: 'github/index.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -41,7 +41,7 @@ describe('redirects', () => { }) test('converts single `redirect_from` strings values into arrays', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'github/collaborating-with-issues-and-pull-requests/about-conversations-on-github.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' diff --git a/tests/unit/data-directory/filename-to-key.js b/tests/unit/data-directory/filename-to-key.js new file mode 100644 index 0000000000..052f78cf98 --- /dev/null +++ b/tests/unit/data-directory/filename-to-key.js @@ -0,0 +1,15 @@ +const filenameToKey = require('../../../lib/filename-to-key') + +describe('filename-to-key', () => { + test('converts filenames to object keys', () => { + expect(filenameToKey('foo/bar/baz.txt')).toBe('foo.bar.baz') + }) + + test('ignores leading slash on filenames', () => { + expect(filenameToKey('/foo/bar/baz.txt')).toBe('foo.bar.baz') + }) + + test('supports MS Windows paths', () => { + expect(filenameToKey('path\\to\\file.txt')).toBe('path.to.file') + }) +}) diff --git a/tests/unit/data-directory/fixtures/README.md b/tests/unit/data-directory/fixtures/README.md new file mode 100644 index 0000000000..fb62e0bc60 --- /dev/null +++ b/tests/unit/data-directory/fixtures/README.md @@ -0,0 +1 @@ +I am a README. I am ignored by default. \ No newline at end of file diff --git a/tests/unit/data-directory/fixtures/bar.yaml b/tests/unit/data-directory/fixtures/bar.yaml new file mode 100644 index 0000000000..d028f54fed --- /dev/null +++ b/tests/unit/data-directory/fixtures/bar.yaml @@ -0,0 +1 @@ +another_markup_language: 'yes' diff --git a/tests/unit/data-directory/fixtures/foo.json b/tests/unit/data-directory/fixtures/foo.json new file mode 100644 index 0000000000..8fd3eb5c42 --- /dev/null +++ b/tests/unit/data-directory/fixtures/foo.json @@ -0,0 +1 @@ +{"meaningOfLife": 42} \ No newline at end of file diff --git a/tests/unit/data-directory/fixtures/nested/baz.md b/tests/unit/data-directory/fixtures/nested/baz.md new file mode 100644 index 0000000000..c2be33651c --- /dev/null +++ b/tests/unit/data-directory/fixtures/nested/baz.md @@ -0,0 +1 @@ +I am markdown! \ No newline at end of file diff --git a/tests/unit/data-directory/index.js b/tests/unit/data-directory/index.js new file mode 100644 index 0000000000..0a6bdcf793 --- /dev/null +++ b/tests/unit/data-directory/index.js @@ -0,0 +1,40 @@ +const path = require('path') +const dataDirectory = require('../../../lib/data-directory') +const fixturesDir = path.join(__dirname, 'fixtures') + +describe('data-directory', () => { + test('works', async () => { + const data = await dataDirectory(fixturesDir) + const expected = { + bar: { another_markup_language: 'yes' }, + foo: { meaningOfLife: 42 }, + nested: { baz: 'I am markdown!' } + } + expect(data).toEqual(expected) + }) + + test('option: preprocess function', async () => { + const preprocess = function (content) { + return content.replace('markdown', 'MARKDOWN') + } + const data = await dataDirectory(fixturesDir, { preprocess }) + expect(data.nested.baz).toBe('I am MARKDOWN!') + }) + + test('option: extensions array', async () => { + const extensions = ['.yaml', 'markdown'] + const data = await dataDirectory(fixturesDir, { extensions }) + expect('bar' in data).toBe(true) + expect('foo' in data).toBe(false) // JSON file should be ignored + }) + + test('option: ignorePatterns', async () => { + const ignorePatterns = [] + + // README is ignored by default + expect('README' in await dataDirectory(fixturesDir)).toBe(false) + + // README can be included by setting empty ignorePatterns array + expect('README' in await dataDirectory(fixturesDir, { ignorePatterns })).toBe(true) + }) +}) diff --git a/tests/unit/early-access.js b/tests/unit/early-access.js index f8ad0b3b88..80aa48373f 100644 --- a/tests/unit/early-access.js +++ b/tests/unit/early-access.js @@ -1,4 +1,4 @@ -const fs = require('fs') +const fs = require('fs').promises const path = require('path') const { GITHUB_ACTIONS, GITHUB_REPOSITORY } = process.env @@ -7,17 +7,17 @@ const testViaActionsOnly = runningActionsOnInternalRepo ? test : test.skip describe('cloning early-access', () => { testViaActionsOnly('the content directory exists', async () => { - const eaContentDir = path.join(process.cwd(), 'content/early-access') - expect(fs.existsSync(eaContentDir)).toBe(true) + const eaDir = path.join(process.cwd(), 'content/early-access') + expect(await fs.stat(eaDir)).toBeTruthy() }) testViaActionsOnly('the data directory exists', async () => { - const eaContentDir = path.join(process.cwd(), 'data/early-access') - expect(fs.existsSync(eaContentDir)).toBe(true) + const eaDir = path.join(process.cwd(), 'data/early-access') + expect(await fs.stat(eaDir)).toBeTruthy() }) testViaActionsOnly('the assets/images directory exists', async () => { - const eaContentDir = path.join(process.cwd(), 'assets/images/early-access') - expect(fs.existsSync(eaContentDir)).toBe(true) + const eaDir = path.join(process.cwd(), 'assets/images/early-access') + expect(await fs.stat(eaDir)).toBeTruthy() }) }) diff --git a/tests/unit/find-page.js b/tests/unit/find-page.js index bb422df1b3..5772db5f01 100644 --- a/tests/unit/find-page.js +++ b/tests/unit/find-page.js @@ -8,7 +8,7 @@ describe('find page', () => { jest.setTimeout(1000 * 1000) test('falls back to the English page if it can\'t find a localized page', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'page-that-does-not-exist-in-translations-dir.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' @@ -24,7 +24,7 @@ describe('find page', () => { }) test('follows redirects', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'page-with-redirects.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' diff --git a/tests/unit/liquid-helpers.js b/tests/unit/liquid-helpers.js index ee6b8d3ecf..7a66b64a48 100644 --- a/tests/unit/liquid-helpers.js +++ b/tests/unit/liquid-helpers.js @@ -1,10 +1,11 @@ const { liquid } = require('../../lib/render-content') const { loadPageMap } = require('../../lib/pages') const entities = new (require('html-entities').XmlEntities)() -const { set } = require('lodash') const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version') describe('liquid helper tags', () => { + jest.setTimeout(60 * 1000) + const context = {} let pageMap beforeAll(async (done) => { @@ -13,11 +14,16 @@ describe('liquid helper tags', () => { context.currentVersion = nonEnterpriseDefaultVersion context.pages = pageMap context.redirects = [] - context.site = {} + context.site = { + data: { + reusables: { + example: 'a rose by any other name\nwould smell as sweet' + } + } + } context.page = { relativePath: 'desktop/index.md' } - set(context.site, 'data.reusables.example', 'a rose by any other name\nwould smell as sweet') done() }) @@ -81,8 +87,6 @@ describe('liquid helper tags', () => { }) describe('indented_data_reference tag', () => { - set(context.site, 'data.reusables.example', 'a rose by any other name\nwould smell as sweet') - test('without any number of spaces specified', async () => { const template = '{% indented_data_reference site.data.reusables.example %}' const expected = ` a rose by any other name @@ -115,4 +119,47 @@ would smell as sweet` expect(output).toBe(expected) }) }) + + describe('data tag', () => { + test( + 'handles bracketed array access within for-in loop', + async () => { + const template = ` +{% for term in site.data.glossaries.external %} +### {% data glossaries.external[forloop.index0].term %} +{% data glossaries.external[forloop.index0].description %} +--- +{% endfor %}` + + const localContext = { ...context } + localContext.site = { + data: { + variables: { + fire_emoji: ':fire:' + }, + glossaries: { + external: [ + { term: 'lit', description: 'Awesome things. {% data variables.fire_emoji %}' }, + { term: 'Zhu Li', description: '_"Zhu Li, do the thing!"_ :point_up:' } + ] + } + } + } + + const expected = ` + +### lit +Awesome things. :fire: +--- + +### Zhu Li +_"Zhu Li, do the thing!"_ :point_up: +--- +` + + const output = await liquid.parseAndRender(template, localContext) + expect(output).toBe(expected) + } + ) + }) }) diff --git a/tests/unit/page.js b/tests/unit/page.js index 5d1b46a0c3..44f98c94a5 100644 --- a/tests/unit/page.js +++ b/tests/unit/page.js @@ -15,14 +15,14 @@ const opts = { } describe('Page class', () => { - test('preserves file path info', () => { - const page = new Page(opts) + test('preserves file path info', async () => { + const page = await Page.init(opts) expect(page.relativePath).toBe('github/collaborating-with-issues-and-pull-requests/about-branches.md') expect(page.fullPath.includes(page.relativePath)).toBe(true) }) - test('does not error out on translated TOC with no links', () => { - const page = new Page({ + test('does not error out on translated TOC with no links', async () => { + const page = await Page.init({ relativePath: 'translated-toc-with-no-links-index.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'ja' @@ -31,30 +31,34 @@ describe('Page class', () => { }) describe('showMiniToc page property', () => { - const article = new Page({ - relativePath: 'sample-article.md', - basePath: path.join(__dirname, '../fixtures'), - languageCode: 'en' - }) + let article, articleWithFM, tocPage, mapTopic - const articleWithFM = new Page({ - showMiniToc: false, - relativePath: article.relativePath, - basePath: article.basePath, - languageCode: article.languageCode - }) + beforeAll(async () => { + article = await Page.init({ + relativePath: 'sample-article.md', + basePath: path.join(__dirname, '../fixtures'), + languageCode: 'en' + }) - const tocPage = new Page({ - relativePath: 'sample-toc-index.md', - basePath: path.join(__dirname, '../fixtures'), - languageCode: 'en' - }) + articleWithFM = await Page.init({ + showMiniToc: false, + relativePath: article.relativePath, + basePath: article.basePath, + languageCode: article.languageCode + }) - const mapTopic = new Page({ - mapTopic: true, - relativePath: article.relativePath, - basePath: article.basePath, - languageCode: article.languageCode + tocPage = await Page.init({ + relativePath: 'sample-toc-index.md', + basePath: path.join(__dirname, '../fixtures'), + languageCode: 'en' + }) + + mapTopic = await Page.init({ + mapTopic: true, + relativePath: article.relativePath, + basePath: article.basePath, + languageCode: article.languageCode + }) }) test('is true by default on articles', () => { @@ -76,7 +80,7 @@ describe('Page class', () => { describe('page.render(context)', () => { test('rewrites links to include the current language prefix and version', async () => { - const page = new Page(opts) + const page = await Page.init(opts) const context = { page: { version: nonEnterpriseDefaultVersion }, currentVersion: nonEnterpriseDefaultVersion, @@ -99,7 +103,7 @@ describe('Page class', () => { }) test('rewrites links in the intro to include the current language prefix and version', async () => { - const page = new Page(opts) + const page = await Page.init(opts) page.rawIntro = '[Pull requests](/articles/about-pull-requests)' const context = { page: { version: nonEnterpriseDefaultVersion }, @@ -114,7 +118,7 @@ describe('Page class', () => { }) test('does not rewrite links that include deprecated enterprise release numbers', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'admin/enterprise-management/migrating-from-github-enterprise-1110x-to-2123.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -133,7 +137,7 @@ describe('Page class', () => { }) test('does not rewrite links to external redirects', async () => { - const page = new Page(opts) + const page = await Page.init(opts) page.markdown = `${page.markdown}\n\nSee [Capistrano](/capistrano).` const context = { page: { version: nonEnterpriseDefaultVersion }, @@ -150,7 +154,7 @@ describe('Page class', () => { // But they don't have access to our currently supported versions, which we're testing here. // This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %} test('renders the expected Enterprise Server versioned content', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'page-versioned-for-all-enterprise-releases.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' @@ -184,27 +188,27 @@ describe('Page class', () => { }) }) - test('preserves `languageCode`', () => { - const page = new Page(opts) + test('preserves `languageCode`', async () => { + const page = await Page.init(opts) expect(page.languageCode).toBe('en') }) - test('parentProductId getter', () => { - let page = new Page({ + test('parentProductId getter', async () => { + let page = await Page.init({ relativePath: 'github/some-category/some-article.md', basePath: path.join(__dirname, '../fixtures/products'), languageCode: 'en' }) expect(page.parentProductId).toBe('github') - page = new Page({ + page = await Page.init({ relativePath: 'actions/some-category/some-article.md', basePath: path.join(__dirname, '../fixtures/products'), languageCode: 'en' }) expect(page.parentProductId).toBe('actions') - page = new Page({ + page = await Page.init({ relativePath: 'admin/some-category/some-article.md', basePath: path.join(__dirname, '../fixtures/products'), languageCode: 'en' @@ -213,26 +217,26 @@ describe('Page class', () => { }) describe('permalinks', () => { - test('is an array', () => { - const page = new Page(opts) + test('is an array', async () => { + const page = await Page.init(opts) expect(Array.isArray(page.permalinks)).toBe(true) }) - test('has a key for every supported enterprise version (and no deprecated versions)', () => { - const page = new Page(opts) + test('has a key for every supported enterprise version (and no deprecated versions)', async () => { + const page = await Page.init(opts) const pageVersions = page.permalinks.map(permalink => permalink.pageVersion) expect(enterpriseServerReleases.supported.every(version => pageVersions.includes(`enterprise-server@${version}`))).toBe(true) expect(enterpriseServerReleases.deprecated.every(version => !pageVersions.includes(`enterprise-server@${version}`))).toBe(true) }) - test('sets versioned values', () => { - const page = new Page(opts) + test('sets versioned values', async () => { + const page = await Page.init(opts) expect(page.permalinks.find(permalink => permalink.pageVersion === nonEnterpriseDefaultVersion).href).toBe(`/en/${nonEnterpriseDefaultVersion}/github/collaborating-with-issues-and-pull-requests/about-branches`) expect(page.permalinks.find(permalink => permalink.pageVersion === `enterprise-server@${enterpriseServerReleases.oldestSupported}`).href).toBe(`/en/enterprise-server@${enterpriseServerReleases.oldestSupported}/github/collaborating-with-issues-and-pull-requests/about-branches`) }) - test('homepage permalinks', () => { - const page = new Page({ + test('homepage permalinks', async () => { + const page = await Page.init({ relativePath: 'index.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -242,8 +246,8 @@ describe('Page class', () => { expect(page.permalinks.find(permalink => permalink.pageVersion === 'homepage').href).toBe('/en') }) - test('permalinks for dotcom-only pages', () => { - const page = new Page({ + test('permalinks for dotcom-only pages', async () => { + const page = await Page.init({ relativePath: 'github/getting-started-with-github/signing-up-for-a-new-github-account.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -252,8 +256,8 @@ describe('Page class', () => { expect(page.permalinks.length).toBe(1) }) - test('permalinks for enterprise-only pages', () => { - const page = new Page({ + test('permalinks for enterprise-only pages', async () => { + const page = await Page.init({ relativePath: 'products/admin/some-category/some-article.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' @@ -264,8 +268,8 @@ describe('Page class', () => { expect(pageVersions.includes(nonEnterpriseDefaultVersion)).toBe(false) }) - test('permalinks for non-GitHub.com products without Enterprise versions', () => { - const page = new Page({ + test('permalinks for non-GitHub.com products without Enterprise versions', async () => { + const page = await Page.init({ relativePath: 'products/actions/some-category/some-article.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' @@ -274,8 +278,8 @@ describe('Page class', () => { expect(page.permalinks.length).toBe(1) }) - test('permalinks for non-GitHub.com products with Enterprise versions', () => { - const page = new Page({ + test('permalinks for non-GitHub.com products with Enterprise versions', async () => { + const page = await Page.init({ relativePath: '/insights/installing-and-configuring-github-insights/about-github-insights.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -318,7 +322,7 @@ describe('Page class', () => { }) test('fixes translated frontmatter that includes verdadero', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'article-with-mislocalized-frontmatter.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'ja' @@ -333,7 +337,7 @@ describe('Page class', () => { // Note this test will go out of date when we deprecate 2.20 test('pages that apply to newer enterprise versions', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'github/administering-a-repository/comparing-releases.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -343,7 +347,7 @@ describe('Page class', () => { }) test('index page', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'index.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -352,7 +356,7 @@ describe('Page class', () => { }) test('enterprise admin index page', async () => { - const page = new Page({ + const page = await Page.init({ relativePath: 'admin/index.md', basePath: path.join(__dirname, '../../content'), languageCode: 'en' @@ -366,50 +370,50 @@ describe('Page class', () => { describe('catches errors thrown in Page class', () => { test('frontmatter parsing error', () => { - function getPage () { - return new Page({ + async function getPage () { + return await Page.init({ relativePath: 'page-with-frontmatter-error.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' }) } - expect(getPage).toThrowError('invalid frontmatter entry') + expect(getPage).rejects.toThrowError('invalid frontmatter entry') }) test('missing versions frontmatter', () => { - function getPage () { - return new Page({ + async function getPage () { + return await Page.init({ relativePath: 'page-with-missing-product-versions.md', basePath: path.join(__dirname, '../fixtures'), languageCode: 'en' }) } - expect(getPage).toThrowError('versions') + expect(getPage).rejects.toThrowError('versions') }) test('English page with a version in frontmatter that its parent product is not available in', () => { - function getPage () { - return new Page({ + async function getPage () { + return await Page.init({ relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md', basePath: path.join(__dirname, '../fixtures/products'), languageCode: 'en' }) } - expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/) + expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/) }) test('non-English page with a version in frontmatter that its parent product is not available in', () => { - function getPage () { - return new Page({ + async function getPage () { + return await Page.init({ relativePath: 'admin/some-category/some-article-with-mismatched-versions-frontmatter.md', basePath: path.join(__dirname, '../fixtures/products'), languageCode: 'es' }) } - expect(getPage).toThrowError(/`versions` frontmatter.*? product is not available in/) + expect(getPage).rejects.toThrowError(/`versions` frontmatter.*? product is not available in/) }) }) diff --git a/tests/unit/pages.js b/tests/unit/pages.js index f27b73ff1b..bb405b5e9c 100644 --- a/tests/unit/pages.js +++ b/tests/unit/pages.js @@ -10,6 +10,8 @@ const entities = new Entities() const { chain, difference } = require('lodash') describe('pages module', () => { + jest.setTimeout(60 * 1000) + let pages beforeAll(async (done) => {