зеркало из https://github.com/github/docs.git
Merge branch 'main' into build-changelog
This commit is contained in:
Robert Mosolgo
Коммит
9e5d72eb42
|
|
@ -0,0 +1,36 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
const fs = require('fs')
|
||||
const core = require('@actions/core')
|
||||
const eventPayload = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8'))
|
||||
|
||||
// This workflow-run script does the following:
|
||||
// 1. Gets an array of labels on a PR.
|
||||
// 2. Finds one with the relevant Algolia text; if none found, exits early.
|
||||
// 3. Gets the version substring from the label string.
|
||||
|
||||
const labelText = 'sync-english-index-for-'
|
||||
const labelsArray = eventPayload.pull_request.labels
|
||||
|
||||
// Exit early if no labels are on this PR
|
||||
if (!(labelsArray && labelsArray.length)) {
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
// Find the relevant label
|
||||
const algoliaLabel = labelsArray
|
||||
.map(label => label.name)
|
||||
.find(label => label.startsWith(labelText))
|
||||
|
||||
// Exit early if no relevant label is found
|
||||
if (!algoliaLabel) {
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
// Given: sync-english-index-for-enterprise-server@3.0
|
||||
// Returns: enterprise-server@3.0
|
||||
const versionToSync = algoliaLabel.split(labelText)[1]
|
||||
|
||||
// Store the version so we can access it later in the workflow
|
||||
core.setOutput('versionToSync', versionToSync)
|
||||
process.exit(0)
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
const fs = require('fs')
|
||||
const path = require('path')
|
||||
const { execSync } = require('child_process')
|
||||
const semver = require('semver')
|
||||
|
||||
/*
|
||||
* This script performs two checks to prevent shipping development mode OpenAPI schemas:
|
||||
* - Ensures the `info.version` property is a semantic version.
|
||||
* In development mode, the `info.version` property is a string
|
||||
* containing the `github/github` branch name.
|
||||
* - Ensures the decorated schema matches the dereferenced schema.
|
||||
* The workflow that calls this script runs `script/rest/update-files.js`
|
||||
* with the `--decorate-only` switch then checks to see if files changed.
|
||||
*
|
||||
*/
|
||||
|
||||
// Check that the `info.version` property is a semantic version
|
||||
const dereferencedDir = path.join(process.cwd(), 'lib/rest/static/dereferenced')
|
||||
const schemas = fs.readdirSync(dereferencedDir)
|
||||
schemas.forEach(filename => {
|
||||
const schema = require(path.join(dereferencedDir, filename))
|
||||
if (!semver.valid(schema.info.version)) {
|
||||
console.log(`🚧⚠️ Your branch contains a development mode OpenAPI schema: ${schema.info.version}. This check is a reminder to not 🚢 OpenAPI files in development mode. 🛑`)
|
||||
process.exit(1)
|
||||
}
|
||||
})
|
||||
|
||||
// Check that the decorated schema matches the dereferenced schema
|
||||
const changedFiles = execSync('git diff --name-only HEAD').toString()
|
||||
|
||||
if(changedFiles !== '') {
|
||||
console.log(`These files were changed:\n${changedFiles}`)
|
||||
console.log(`🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md'. 🛑`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
// All checks pass, ready to ship
|
||||
console.log('All good 👍')
|
||||
process.exit(0)
|
||||
|
|
@ -21,13 +21,16 @@ module.exports = [
|
|||
'juliangruber/approve-pull-request-action@c530832d4d346c597332e20e03605aa94fa150a8',
|
||||
'juliangruber/find-pull-request-action@64d55773c959748ad30a4184f4dc102af1669f7b',
|
||||
'juliangruber/read-file-action@e0a316da496006ffd19142f0fd594a1783f3b512',
|
||||
'lee-dohm/close-matching-issues@22002609b2555fe18f52b8e2e7c07cbf5529e8a8',
|
||||
'pascalgn/automerge-action@c9bd182',
|
||||
'peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326',
|
||||
'peter-evans/create-or-update-project-card@80140aaeb9730972a83c626031250621fe8f6670',
|
||||
'peter-evans/create-pull-request@938e6aea6f8dbdaced2064e948cb806c77fe87b8',
|
||||
'rachmari/actions-add-new-issue-to-column@1a459ef92308ba7c9c9dc2fcdd72f232495574a9',
|
||||
'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e',
|
||||
'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88',
|
||||
'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d',
|
||||
'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815',
|
||||
'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0'
|
||||
'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0',
|
||||
'EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575'
|
||||
]
|
||||
|
|
|
|||
|
|
@ -17,16 +17,34 @@ jobs:
|
|||
- name: npm run build
|
||||
run: npm run build
|
||||
- name: Run script
|
||||
run: script/check-english-links.js > broken_links.md
|
||||
run: |
|
||||
script/check-english-links.js > broken_links.md
|
||||
echo -e '\ncc @github/docs-content'>> broken_links.md
|
||||
- if: ${{ failure() }}
|
||||
name: Get title for issue
|
||||
id: check
|
||||
run: echo "::set-output name=title::$(head -1 broken_links.md)"
|
||||
- if: ${{ failure() }}
|
||||
name: Close previous report
|
||||
uses: lee-dohm/close-matching-issues@22002609b2555fe18f52b8e2e7c07cbf5529e8a8
|
||||
with:
|
||||
query: 'label:"broken+link+report"'
|
||||
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}
|
||||
- if: ${{ failure() }}
|
||||
name: Create issue from file
|
||||
id: broken-link-report
|
||||
uses: peter-evans/create-issue-from-file@a04ce672e3acedb1f8e416b46716ddfd09905326
|
||||
with:
|
||||
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}
|
||||
title: ${{ steps.check.outputs.title }}
|
||||
content-filepath: ./broken_links.md
|
||||
labels: broken link report
|
||||
- if: ${{ failure() }}
|
||||
name: Add issue to FR project board
|
||||
uses: peter-evans/create-or-update-project-card@80140aaeb9730972a83c626031250621fe8f6670
|
||||
with:
|
||||
project-repository: 'github'
|
||||
project-number: '1367'
|
||||
column-name: 'Docs-content FR issues'
|
||||
issue-number: ${{ steps.broken-link-report.outputs.issue-number }}
|
||||
token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,32 @@
|
|||
name: OpenAPI generate decorated schema files
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
pull_request:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
generate-decorated-files:
|
||||
if: github.event.pull_request.user.login == 'github-openapi-bot'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository code
|
||||
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Decorate the dereferenced OpenAPI schemas
|
||||
run: script/rest/update-files.js --decorate-only
|
||||
|
||||
- name: Check in the decorated files
|
||||
uses: EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575
|
||||
with:
|
||||
# The arguments for the `git add` command
|
||||
add: 'lib/rest/static/decorated'
|
||||
|
||||
# The message for the commit
|
||||
message: 'Add decorated OpenAPI schema files'
|
||||
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
name: OpenAPI dev mode check
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
|
||||
jobs:
|
||||
check-schema-versions:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository code
|
||||
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
# Differences between decorated and dereferenced files indicates a problem
|
||||
- name: Generate decorated files to check that there are no differences
|
||||
run: script/rest/update-files.js --decorate-only
|
||||
|
||||
- name: Check if deref/decorated schemas are dev mode and that they match
|
||||
run: .github/actions-scripts/openapi-schema-branch.js
|
||||
|
|
@ -3,6 +3,8 @@ name: Algolia Sync Single English Index
|
|||
on:
|
||||
pull_request:
|
||||
types:
|
||||
- labeled
|
||||
- unlabeled
|
||||
- opened
|
||||
- reopened
|
||||
- synchronize
|
||||
|
|
@ -13,7 +15,7 @@ on:
|
|||
jobs:
|
||||
updateIndices:
|
||||
name: Update English index for single version based on a label's version
|
||||
if: github.repository == 'github/docs-internal' && startsWith(github.event.label.name, 'sync-english-index-for-')
|
||||
if: github.repository == 'github/docs-internal'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: checkout
|
||||
|
|
@ -30,13 +32,13 @@ jobs:
|
|||
${{ runner.os }}-node-
|
||||
- name: npm ci
|
||||
run: npm ci
|
||||
- name: Get version from label
|
||||
- name: Get version from Algolia label if present; only continue if the label is found.
|
||||
id: getVersion
|
||||
run: |
|
||||
echo "::set-output name=version::$(github.event.label.name.split('sync-english-index-for-')[1])"
|
||||
- name: Sync English index for single version
|
||||
run: $GITHUB_WORKSPACE/.github/actions-scripts/enterprise-algolia-label.js
|
||||
- if: ${{ steps.getVersion.outputs.versionToSync }}
|
||||
name: Sync English index for single version
|
||||
env:
|
||||
VERSION: ${{ steps.getVersion.outputs.version }}
|
||||
VERSION: ${{ steps.getVersion.outputs.versionToSync }}
|
||||
LANGUAGE: 'en'
|
||||
ALGOLIA_APPLICATION_ID: ${{ secrets.ALGOLIA_APPLICATION_ID }}
|
||||
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
|
||||
|
|
|
|||
|
|
@ -91,7 +91,7 @@ steps:
|
|||
|
||||
### Caching dependencies
|
||||
|
||||
You can cache your dependencies to speed up your workflow runs. After a successful run, your local Gradle package cache will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote package repositories. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache your dependencies to speed up your workflow runs. After a successful run, your local Gradle package cache will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote package repositories. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -91,7 +91,7 @@ steps:
|
|||
|
||||
### Caching dependencies
|
||||
|
||||
You can cache your dependencies to speed up your workflow runs. After a successful run, your local Maven repository will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote Maven repositories. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache your dependencies to speed up your workflow runs. After a successful run, your local Maven repository will be stored on GitHub Actions infrastructure. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote Maven repositories. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -129,7 +129,7 @@ If you don't specify a Node.js version, {% data variables.product.prodname_dotco
|
|||
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux {% data variables.product.prodname_dotcom %}-hosted runners also have Grunt, Gulp, and Bower installed.
|
||||
|
||||
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
#### Example using npm
|
||||
|
||||
|
|
@ -227,7 +227,7 @@ always-auth=true
|
|||
|
||||
#### Example caching dependencies
|
||||
|
||||
You can cache dependencies using a unique key, and restore the dependencies when you run future workflows using the `cache` action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache dependencies using a unique key, and restore the dependencies when you run future workflows using the `cache` action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>" and the [`cache` action](https://github.com/marketplace/actions/cache).
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
|
|
@ -241,7 +241,7 @@ steps:
|
|||
uses: actions/cache@v2
|
||||
with:
|
||||
# npm cache files are stored in `~/.npm` on Linux/macOS
|
||||
path: ~/.npm
|
||||
path: ~/.npm
|
||||
key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
|
||||
restore-keys: |
|
||||
${{ runner.OS }}-node-
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ We recommend that you have a basic understanding of PowerShell and Pester. For m
|
|||
|
||||
### Adding a workflow for Pester
|
||||
|
||||
To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example, `Test-Path` is used to check that a file called `resultsfile.log` is present.
|
||||
To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example, `Test-Path` is used to check that a file called `resultsfile.log` is present.
|
||||
|
||||
This example workflow file must be added to your repository's `.github/workflows/` directory:
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ jobs:
|
|||
{% endraw %}
|
||||
|
||||
* `shell: pwsh` - Configures the job to use PowerShell when running the `run` commands.
|
||||
* `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory.
|
||||
* `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:
|
||||
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ The table below describes the locations for various PowerShell modules in each {
|
|||
|
||||
### Installing dependencies
|
||||
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code.
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code.
|
||||
|
||||
{% note %}
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ The table below describes the locations for various PowerShell modules in each {
|
|||
|
||||
{% endnote %}
|
||||
|
||||
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
For example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules:
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ jobs:
|
|||
|
||||
#### Caching dependencies
|
||||
|
||||
You can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
PowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, the `path` location used in the following Ubuntu example will be different for a Windows operating system.
|
||||
|
||||
|
|
|
|||
|
|
@ -141,9 +141,9 @@ jobs:
|
|||
uses: actions/setup-python@v2
|
||||
with:
|
||||
# Semantic version range syntax or exact version of a Python version
|
||||
python-version: '3.x'
|
||||
python-version: '3.x'
|
||||
# Optional - x64 or x86 architecture, defaults to x64
|
||||
architecture: 'x64'
|
||||
architecture: 'x64'
|
||||
# You can test your matrix by printing the current Python version
|
||||
- name: Display Python version
|
||||
run: python -c "import sys; print(sys.version)"
|
||||
|
|
@ -192,7 +192,7 @@ We recommend using `setup-python` to configure the version of Python used in you
|
|||
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners have the pip package manager installed. You can use pip to install dependencies from the PyPI package registry before building and testing your code. For example, the YAML below installs or upgrades the `pip` package installer and the `setuptools` and `wheel` packages.
|
||||
|
||||
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can also cache dependencies to speed up your workflow. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
|
|
@ -228,7 +228,7 @@ steps:
|
|||
|
||||
#### Caching Dependencies
|
||||
|
||||
You can cache pip dependencies using a unique key, and restore the dependencies when you run future workflows using the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "[Caching dependencies to speed up workflows](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
When using {% data variables.product.prodname_dotcom %}-hosted runners, you can cache pip dependencies using a unique key, and restore the dependencies when you run future workflows using the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
Pip caches dependencies in different locations, depending on the operating system of the runner. The path you'll need to cache may differ from the Ubuntu example below depending on the operating system you use. For more information, see [Python caching examples](https://github.com/actions/cache/blob/main/examples.md#python---pip).
|
||||
|
||||
|
|
|
|||
|
|
@ -148,7 +148,7 @@ steps:
|
|||
|
||||
#### Caching dependencies
|
||||
|
||||
The `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs.
|
||||
If you are using {% data variables.product.prodname_dotcom %}-hosted runners, the `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs.
|
||||
|
||||
To enable caching, set the following.
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ This will configure bundler to install your gems to `vendor/cache`. For each suc
|
|||
|
||||
**Caching without setup-ruby**
|
||||
|
||||
For greater control over caching, you can use the `actions/cache` Action directly. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
|
||||
For greater control over caching, if you are using {% data variables.product.prodname_dotcom %}-hosted runners, you can use the `actions/cache` Action directly. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ The `retention-days` value cannot exceed the retention limit set by the reposito
|
|||
|
||||
During a workflow run, you can use the [`download-artifact`](https://github.com/actions/download-artifact)action to download artifacts that were previously uploaded in the same workflow run.
|
||||
|
||||
After a workflow run has been completed, you can download or delete artifacts on {% data variables.product.prodname_dotcom %} or using the REST API. For more information, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)," "[Removing workflow artifacts](/actions/managing-workflow-runs/removing-workflow-artifacts)," and the "[Artifacts REST API](/v3/actions/artifacts/)."
|
||||
After a workflow run has been completed, you can download or delete artifacts on {% data variables.product.prodname_dotcom %} or using the REST API. For more information, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)," "[Removing workflow artifacts](/actions/managing-workflow-runs/removing-workflow-artifacts)," and the "[Artifacts REST API](/rest/reference/actions#artifacts)."
|
||||
|
||||
#### Downloading artifacts during a workflow run
|
||||
|
||||
|
|
|
|||
|
|
@ -48,7 +48,9 @@ When creating a group, you must choose a policy that defines which repositories
|
|||
{% warning %}
|
||||
|
||||
**Warning**
|
||||
|
||||
{% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %}
|
||||
|
||||
For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
|
||||
|
||||
{% endwarning %}
|
||||
|
|
@ -78,7 +80,9 @@ When creating a group, you must choose a policy that defines which organizations
|
|||
{% warning %}
|
||||
|
||||
**Warning**
|
||||
|
||||
{% indented_data_reference site.data.reusables.github-actions.self-hosted-runner-security spaces=3 %}
|
||||
|
||||
For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
|
||||
|
||||
{% endwarning %}
|
||||
|
|
|
|||
|
|
@ -12,11 +12,11 @@ versions:
|
|||
|
||||
### Overview
|
||||
|
||||
This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you work create more complex workflows.
|
||||
This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you work create more complex workflows.
|
||||
|
||||
### Storing secrets
|
||||
|
||||
If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.
|
||||
If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.
|
||||
|
||||
This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ jobs:
|
|||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- run: ./test_server.sh
|
||||
- run: ./test_server.sh
|
||||
```
|
||||
|
||||
For more information, see [`jobs.<job_id>.needs`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds).
|
||||
|
|
@ -85,7 +85,7 @@ For more information, see [`jobs.<job_id>.strategy.matrix`](/actions/reference/w
|
|||
|
||||
### Caching dependencies
|
||||
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.
|
||||
|
||||
This example demonstrates how to cache the ` ~/.npm` directory:
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ jobs:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)."
|
||||
For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
### Using databases and service containers
|
||||
|
||||
|
|
@ -136,7 +136,7 @@ For more information, see "[Using databases and service containers](/actions/con
|
|||
|
||||
### Using labels to route workflows
|
||||
|
||||
This feature helps you assign jobs to a specific self-hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner, and then refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way.
|
||||
This feature helps you assign jobs to a specific self-hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner, and then refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way.
|
||||
|
||||
This example shows how a workflow can use labels to specify the required runner:
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ GitHub Actions
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)."
|
||||
{% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
{% data variables.product.prodname_actions %} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC).
|
||||
|
||||
|
|
|
|||
|
|
@ -262,7 +262,7 @@ jobs:
|
|||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- run: echo "This job will be run first, in parallel with build_a"
|
||||
|
||||
|
||||
test_ab:
|
||||
runs-on: ubuntu-latest
|
||||
needs: [build_a,build_b]
|
||||
|
|
@ -346,7 +346,7 @@ jobs:
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)."
|
||||
{% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
### Artifacts
|
||||
|
||||
|
|
@ -367,7 +367,7 @@ GitLab CI/CD
|
|||
<td class="d-table-cell v-align-top">
|
||||
{% raw %}
|
||||
```yaml
|
||||
script:
|
||||
script:
|
||||
artifacts:
|
||||
paths:
|
||||
- math-homework.txt
|
||||
|
|
@ -414,7 +414,7 @@ GitLab CI/CD
|
|||
container-job:
|
||||
variables:
|
||||
POSTGRES_PASSWORD: postgres
|
||||
# The hostname used to communicate with the
|
||||
# The hostname used to communicate with the
|
||||
# PostgreSQL service container
|
||||
POSTGRES_HOST: postgres
|
||||
# The default PostgreSQL port
|
||||
|
|
@ -423,10 +423,10 @@ container-job:
|
|||
services:
|
||||
- postgres
|
||||
script:
|
||||
# Performs a clean installation of all dependencies
|
||||
# Performs a clean installation of all dependencies
|
||||
# in the `package.json` file
|
||||
- npm ci
|
||||
# Runs a script that creates a PostgreSQL client,
|
||||
# Runs a script that creates a PostgreSQL client,
|
||||
# populates the client with data, and retrieves data
|
||||
- node client.js
|
||||
tags:
|
||||
|
|
@ -452,7 +452,7 @@ jobs:
|
|||
- name: Check out repository code
|
||||
uses: actions/checkout@v2
|
||||
|
||||
# Performs a clean installation of all dependencies
|
||||
# Performs a clean installation of all dependencies
|
||||
# in the `package.json` file
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
|
@ -462,7 +462,7 @@ jobs:
|
|||
# populates the client with data, and retrieves data
|
||||
run: node client.js
|
||||
env:
|
||||
# The hostname used to communicate with the
|
||||
# The hostname used to communicate with the
|
||||
# PostgreSQL service container
|
||||
POSTGRES_HOST: postgres
|
||||
# The default PostgreSQL port
|
||||
|
|
|
|||
|
|
@ -184,7 +184,7 @@ When migrating from Travis CI, consider the following key features in {% data va
|
|||
|
||||
#### Hosting your own runners
|
||||
|
||||
If your jobs require specific hardware or software, {% data variables.product.prodname_actions %} allows you to host your own runners and send your jobs to them for processing. {% data variables.product.prodname_actions %} also lets you use policies to control how these runners are accessed, granting access at the organization or repository level. For more information, see ["Hosting your own runners](/actions/hosting-your-own-runners)."
|
||||
If your jobs require specific hardware or software, {% data variables.product.prodname_actions %} allows you to host your own runners and send your jobs to them for processing. {% data variables.product.prodname_actions %} also lets you use policies to control how these runners are accessed, granting access at the organization or repository level. For more information, see ["Hosting your own runners](/actions/hosting-your-own-runners)."
|
||||
|
||||
#### Concurrent jobs and execution time
|
||||
|
||||
|
|
@ -213,7 +213,7 @@ For example:
|
|||
shell: bash
|
||||
```
|
||||
|
||||
### Error handling in {% data variables.product.prodname_actions %}
|
||||
### Error handling in {% data variables.product.prodname_actions %}
|
||||
|
||||
When migrating to {% data variables.product.prodname_actions %}, there are different approaches to error handling that you might need to be aware of.
|
||||
|
||||
|
|
@ -288,7 +288,7 @@ jobs:
|
|||
|
||||
### Caching dependencies
|
||||
|
||||
Travis CI and {% data variables.product.prodname_actions %} let you manually cache dependencies for later reuse. This example demonstrates the cache syntax for each system.
|
||||
Travis CI and {% data variables.product.prodname_actions %} let you manually cache dependencies for later reuse. This example demonstrates the cache syntax for each system.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
|
|
@ -323,7 +323,7 @@ cache: npm
|
|||
</tr>
|
||||
</table>
|
||||
|
||||
For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)."
|
||||
{% data variables.product.prodname_actions %} caching is only applicable to {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
|
||||
### Examples of common tasks
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ You can see whether a workflow run is in progress or complete from the workflow
|
|||
|
||||
If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also view billable job execution minutes, or download logs and build artifacts.
|
||||
|
||||
{% data variables.product.prodname_actions %} use the Checks API to output statuses, results, and logs for a workflow. {% data variables.product.prodname_dotcom %} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {% data variables.product.prodname_actions %} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/v3/checks/)."
|
||||
{% data variables.product.prodname_actions %} use the Checks API to output statuses, results, and logs for a workflow. {% data variables.product.prodname_dotcom %} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {% data variables.product.prodname_actions %} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/rest/reference/checks)."
|
||||
|
||||
{% data reusables.github-actions.invalid-workflow-files %}
|
||||
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ You can use the `GITHUB_TOKEN` to make authenticated API calls. This example wor
|
|||
|
||||
### Permissions for the `GITHUB_TOKEN`
|
||||
|
||||
For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see "[{% data variables.product.prodname_github_app %} Permissions](/v3/apps/permissions/)."
|
||||
For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see "[{% data variables.product.prodname_github_app %} Permissions](/rest/reference/permissions-required-for-github-apps)."
|
||||
|
||||
| Permission | Access type | Access by forked repos |
|
||||
|------------|-------------|--------------------------|
|
||||
|
|
|
|||
|
|
@ -43,11 +43,11 @@ You can use and read encrypted secrets in a workflow file if you have access to
|
|||
|
||||
{% endwarning %}
|
||||
|
||||
You can also manage secrets using the REST API. For more information, see "[Secrets](/v3/actions/secrets/)."
|
||||
You can also manage secrets using the REST API. For more information, see "[Secrets](/rest/reference/actions#secrets)."
|
||||
|
||||
#### Limiting credential permissions
|
||||
|
||||
When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/v3/guides/managing-deploy-keys/#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token (PAT), select the fewest scopes necessary.
|
||||
When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/developers/overview/managing-deploy-keys#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token (PAT), select the fewest scopes necessary.
|
||||
|
||||
### Creating encrypted secrets for a repository
|
||||
|
||||
|
|
|
|||
|
|
@ -143,7 +143,7 @@ jobs:
|
|||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
You can use the {% data variables.product.product_name %} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.prodname_dotcom %}. For more information, see "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)."
|
||||
You can use the {% data variables.product.product_name %} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.prodname_dotcom %}. For more information, see "[Create a repository dispatch event](/rest/reference/repos#create-a-repository-dispatch-event)."
|
||||
|
||||
To trigger the custom `repository_dispatch` webhook event, you must send a `POST` request to a {% data variables.product.product_name %} API endpoint and provide an `event_type` name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the `repository_dispatch` event.
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ You can configure your workflow to run when webhook events are created on {% dat
|
|||
|
||||
#### `check_run`
|
||||
|
||||
Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/v3/checks/runs/)."
|
||||
Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/rest/reference/checks#runs)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -183,7 +183,7 @@ on:
|
|||
|
||||
#### `check_suite`
|
||||
|
||||
Runs your workflow anytime the `check_suite` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check suites](/v3/checks/suites/)."
|
||||
Runs your workflow anytime the `check_suite` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check suites](/rest/reference/checks#suites)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -209,7 +209,7 @@ on:
|
|||
|
||||
#### `create`
|
||||
|
||||
Runs your workflow anytime someone creates a branch or tag, which triggers the `create` event. For information about the REST API, see "[Create a reference](/v3/git/refs/#create-a-reference)."
|
||||
Runs your workflow anytime someone creates a branch or tag, which triggers the `create` event. For information about the REST API, see "[Create a reference](/rest/reference/git#create-a-reference)."
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
|
|
@ -224,7 +224,7 @@ on:
|
|||
|
||||
#### `delete`
|
||||
|
||||
Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/v3/git/refs/#delete-a-reference)."
|
||||
Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/rest/reference/git#delete-a-reference)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -271,7 +271,7 @@ on:
|
|||
|
||||
#### `fork`
|
||||
|
||||
Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/v3/repos/forks/#create-a-fork)."
|
||||
Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/rest/reference/repos#create-a-fork)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -354,7 +354,7 @@ jobs:
|
|||
|
||||
#### `issues`
|
||||
|
||||
Runs your workflow anytime the `issues` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issues](/v3/issues)."
|
||||
Runs your workflow anytime the `issues` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issues](/rest/reference/issues)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -374,7 +374,7 @@ on:
|
|||
|
||||
#### `label`
|
||||
|
||||
Runs your workflow anytime the `label` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Labels](/v3/issues/labels/)."
|
||||
Runs your workflow anytime the `label` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Labels](/rest/reference/issues#labels)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -394,7 +394,7 @@ on:
|
|||
|
||||
#### `milestone`
|
||||
|
||||
Runs your workflow anytime the `milestone` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Milestones](/v3/issues/milestones/)."
|
||||
Runs your workflow anytime the `milestone` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Milestones](/rest/reference/issues#milestones)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -431,7 +431,7 @@ on:
|
|||
|
||||
#### `project`
|
||||
|
||||
Runs your workflow anytime the `project` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Projects](/v3/projects/)."
|
||||
Runs your workflow anytime the `project` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Projects](/rest/reference/projects)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -451,7 +451,7 @@ on:
|
|||
|
||||
#### `project_card`
|
||||
|
||||
Runs your workflow anytime the `project_card` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project cards](/v3/projects/cards)."
|
||||
Runs your workflow anytime the `project_card` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project cards](/rest/reference/projects#cards)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -471,7 +471,7 @@ on:
|
|||
|
||||
#### `project_column`
|
||||
|
||||
Runs your workflow anytime the `project_column` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project columns](/v3/projects/columns)."
|
||||
Runs your workflow anytime the `project_column` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project columns](/rest/reference/projects#columns)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -491,7 +491,7 @@ on:
|
|||
|
||||
#### `public`
|
||||
|
||||
Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/v3/repos/#edit)."
|
||||
Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/rest/reference/repos#edit)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -508,7 +508,7 @@ on:
|
|||
|
||||
#### `pull_request`
|
||||
|
||||
Runs your workflow anytime the `pull_request` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull requests](/v3/pulls)."
|
||||
Runs your workflow anytime the `pull_request` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull requests](/rest/reference/pulls)."
|
||||
|
||||
{% note %}
|
||||
|
||||
|
|
@ -534,7 +534,7 @@ on:
|
|||
|
||||
#### `pull_request_review`
|
||||
|
||||
Runs your workflow anytime the `pull_request_review` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull request reviews](/v3/pulls/reviews)."
|
||||
Runs your workflow anytime the `pull_request_review` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull request reviews](/rest/reference/pulls#reviews)."
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
|
|
@ -554,7 +554,7 @@ on:
|
|||
|
||||
#### `pull_request_review_comment`
|
||||
|
||||
Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see [Review comments](/v3/pulls/comments).
|
||||
Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see [Review comments](/rest/reference/pulls#comments).
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
|
|
@ -597,7 +597,7 @@ on: pull_request_target
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note:** The webhook payload available to GitHub Actions does not include the `added`, `removed`, and `modified` attributes in the `commit` object. You can retrieve the full commit object using the REST API. For more information, see "[Get a single commit](/v3/repos/commits/#get-a-single-commit)"".
|
||||
**Note:** The webhook payload available to GitHub Actions does not include the `added`, `removed`, and `modified` attributes in the `commit` object. You can retrieve the full commit object using the REST API. For more information, see "[Get a single commit](/rest/reference/repos#get-a-single-commit)"".
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -640,7 +640,7 @@ on:
|
|||
|
||||
{% endnote %}
|
||||
|
||||
Runs your workflow anytime the `release` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Releases](/v3/repos/releases/)."
|
||||
Runs your workflow anytime the `release` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Releases](/rest/reference/repos#releases)."
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
|
|
@ -658,7 +658,7 @@ on:
|
|||
|
||||
#### `status`
|
||||
|
||||
Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/v3/repos/statuses/).
|
||||
Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/rest/reference/repos#statuses).
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
@ -675,7 +675,7 @@ on:
|
|||
|
||||
#### `watch`
|
||||
|
||||
Runs your workflow anytime the `watch` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Starring](/v3/activity/starring/)."
|
||||
Runs your workflow anytime the `watch` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Starring](/rest/reference/activity#starring)."
|
||||
|
||||
{% data reusables.github-actions.branch-requirement %}
|
||||
|
||||
|
|
|
|||
|
|
@ -76,6 +76,7 @@ For more information, see:
|
|||
- "[Disabling or limiting {% data variables.product.prodname_actions %} for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization)"{% if currentVersion == "free-pro-team@latest" %}
|
||||
- "[Enforcing {% data variables.product.prodname_actions %} policies in your enterprise account](/github/setting-up-and-managing-your-enterprise/enforcing-github-actions-policies-in-your-enterprise-account)" for {% data variables.product.prodname_ghe_cloud %}{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %}
|
||||
### Disabling and enabling workflows
|
||||
|
||||
You can enable and disable individual workflows in your repository on {% data variables.product.prodname_dotcom %}.
|
||||
|
|
@ -83,3 +84,4 @@ You can enable and disable individual workflows in your repository on {% data va
|
|||
{% data reusables.actions.scheduled-workflows-disabled %}
|
||||
|
||||
For more information, see "[Disabling and enabling a workflow](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow)."
|
||||
{% endif %}
|
||||
|
|
|
|||
|
|
@ -227,7 +227,7 @@ Each job runs in an environment specified by `runs-on`.
|
|||
|
||||
You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {% data variables.product.prodname_dotcom %}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits.
|
||||
|
||||
If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/v3/actions/workflow-jobs)."
|
||||
If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/rest/reference/actions#workflow-jobs)."
|
||||
|
||||
### **`jobs.<job_id>`**
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ versions:
|
|||
---
|
||||
User accounts on {% data variables.product.product_location %} are preserved when you change the authentication method and users will continue to log into the same account as long as their username doesn't change.
|
||||
|
||||
If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/enterprise/{{currentVersion}}/v3/enterprise-admin/users/#rename-an-existing-user).
|
||||
If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/rest/reference/enterprise-admin#update-the-username-for-a-user).
|
||||
|
||||
Other issues you should take into consideration include:
|
||||
|
||||
|
|
|
|||
|
|
@ -157,7 +157,7 @@ $ ghe-es-index-status -do | column -ts,
|
|||
|
||||
#### ghe-legacy-github-services-report
|
||||
|
||||
This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {% data variables.product.prodname_dotcom %} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {% data variables.product.prodname_dotcom %} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {% data variables.product.prodname_blog %} or "[Replacing {% data variables.product.prodname_dotcom %} Services](/v3/guides/replacing-github-services/)." For more information about this command or for additional options, use the `-h` flag.
|
||||
This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {% data variables.product.prodname_dotcom %} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {% data variables.product.prodname_dotcom %} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {% data variables.product.prodname_blog %} or "[Replacing {% data variables.product.prodname_dotcom %} Services](/developers/overview/replacing-github-services)." For more information about this command or for additional options, use the `-h` flag.
|
||||
|
||||
```shell
|
||||
ghe-legacy-github-services-report
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ Enabling {% data variables.product.prodname_github_connect %} also creates a {%
|
|||
|
||||
Enabling {% data variables.product.prodname_github_connect %} will not allow {% data variables.product.prodname_dotcom_the_website %} users to make changes to {% data variables.product.prodname_ghe_server %}.
|
||||
|
||||
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)."
|
||||
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/graphql/guides/managing-enterprise-accounts)."
|
||||
### Enabling {% data variables.product.prodname_github_connect %}
|
||||
|
||||
1. Sign in to {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_dotcom_the_website %}.
|
||||
|
|
|
|||
|
|
@ -19,6 +19,6 @@ With the APIs, you can automate many administrative tasks. Some examples include
|
|||
- Perform changes to the {% data variables.enterprise.management_console %}. For more information, see "[{% data variables.enterprise.management_console %}](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#management-console)."
|
||||
- Configure LDAP sync. For more information, see "[LDAP](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#ldap)."{% endif %}
|
||||
- Collect statistics about your enterprise. For more information, see "[Admin stats](/rest/reference/enterprise-admin#admin-stats)."
|
||||
- Manage your enterprise account. For more information, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)."
|
||||
- Manage your enterprise account. For more information, see "[Enterprise accounts](/graphql/guides/managing-enterprise-accounts)."
|
||||
|
||||
For the complete documentation for {% data variables.product.prodname_enterprise_api %}, see [{% data variables.product.prodname_dotcom %} REST API](/rest) and [{% data variables.product.prodname_dotcom%} GraphQL API](/graphql).
|
||||
For the complete documentation for {% data variables.product.prodname_enterprise_api %}, see [{% data variables.product.prodname_dotcom %} REST API](/rest) and [{% data variables.product.prodname_dotcom%} GraphQL API](/graphql).
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Name | Description
|
|||
[add key]: /articles/adding-a-new-ssh-key-to-your-github-account
|
||||
[deploy key]: /guides/managing-deploy-keys/#deploy-keys
|
||||
[generate token]: /articles/creating-an-access-token-for-command-line-use
|
||||
[OAuth access token]: /v3/oauth/
|
||||
[OAuth access token]: /developers/apps/authorizing-oauth-apps
|
||||
[OAuth application]: /guides/basics-of-authentication/#registering-your-app
|
||||
[2fa]: /articles/about-two-factor-authentication
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ versions:
|
|||
|
||||
To export repository data from {% data variables.product.prodname_dotcom_the_website %}, use <a href="/rest/reference/migrations" class="dotcom-only">the Migrations API</a>.
|
||||
|
||||
The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. To access the Migrations API, you must provide a custom [media type](/v3/media) in the `Accept` header: `application/vnd.github.wyandotte-preview+json`. The examples below include the custom media type.
|
||||
The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. To access the Migrations API, you must provide a custom [media type](/rest/overview/media-types) in the `Accept` header: `application/vnd.github.wyandotte-preview+json`. The examples below include the custom media type.
|
||||
|
||||
### Generating a migration archive
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ The Migrations API is currently in a preview period, which means that the endpoi
|
|||
|
||||
2. Start a migration by `POST`ing to <a href="/rest/reference/migrations#start-an-organization-migration" class="dotcom-only">the migration endpoint</a>. You'll need:
|
||||
* Your access token for authentication.
|
||||
* A [list of the repositories](/v3/repos/#list-organization-repositories) you want to migrate:
|
||||
* A [list of the repositories](/rest/reference/repos#list-organization-repositories) you want to migrate:
|
||||
```shell
|
||||
curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X POST \
|
||||
-H "Accept: application/vnd.github.wyandotte-preview+json" \
|
||||
|
|
|
|||
|
|
@ -131,7 +131,7 @@ curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X DELETE \
|
|||
|
||||
#### Deleting repositories from an organization on {% data variables.product.prodname_dotcom_the_website %}
|
||||
|
||||
After unlocking the {% data variables.product.prodname_dotcom_the_website %} organization's repositories, you should delete every repository you previously migrated using [the repository delete endpoint](/enterprise/{{ currentVersion }}/v3/repos/#delete-a-repository). You'll need your access token for authentication:
|
||||
After unlocking the {% data variables.product.prodname_dotcom_the_website %} organization's repositories, you should delete every repository you previously migrated using [the repository delete endpoint](/rest/reference/repos/#delete-a-repository). You'll need your access token for authentication:
|
||||
```shell
|
||||
curl -H "Authorization: token <em>GITHUB_ACCESS_TOKEN</em>" -X DELETE \
|
||||
https://api.github.com/repos/<em>orgname</em>/<em>repo_name</em>
|
||||
|
|
|
|||
|
|
@ -92,4 +92,4 @@ You can create a custom message that suspended users will see when attempting to
|
|||
```
|
||||
|
||||
### Further reading
|
||||
- "[Suspend a user](/enterprise/{{ currentVersion }}/v3/enterprise-admin/users/#suspend-a-user)"
|
||||
- "[Suspend a user](/rest/reference/enterprise-admin#suspend-a-user)"
|
||||
|
|
@ -67,13 +67,13 @@ Keep these ideas in mind when creating {% data variables.product.prodname_oauth_
|
|||
* Don't build an {% data variables.product.prodname_oauth_app %} to act as an application for your team or company. {% data variables.product.prodname_oauth_app %}s authenticate as a single user, so if one person creates an {% data variables.product.prodname_oauth_app %} for a company to use, and then they leave the company, no one else will have access to it.{% if currentVersion == "free-pro-team@latest" %}
|
||||
* {% data reusables.apps.oauth-apps-restrictions %}{% endif %}
|
||||
|
||||
For more on {% data variables.product.prodname_oauth_app %}s, see "[Creating an {% data variables.product.prodname_oauth_app %}](/apps/building-oauth-apps/creating-an-oauth-app/)" and "[Registering your app](/v3/guides/basics-of-authentication/#registering-your-app)."
|
||||
For more on {% data variables.product.prodname_oauth_app %}s, see "[Creating an {% data variables.product.prodname_oauth_app %}](/apps/building-oauth-apps/creating-an-oauth-app/)" and "[Registering your app](/rest/guides/basics-of-authentication#registering-your-app)."
|
||||
|
||||
### Personal access tokens
|
||||
|
||||
A [personal access token](/articles/creating-a-personal-access-token-for-the-command-line/) is a string of characters that functions similarly to an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/) in that you can specify its permissions via [scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). A personal access token is also similar to a password, but you can have many of them and you can revoke access to each one at any time.
|
||||
|
||||
As an example, you can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that [creates an issue](/v3/issues/#create-an-issue) in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it.
|
||||
As an example, you can enable a personal access token to write to your repositories. If then you run a cURL command or write a script that [creates an issue](/rest/reference/issues#create-an-issue) in your repository, you would pass the personal access token to authenticate. You can store the personal access token as an environment variable to avoid typing it every time you use it.
|
||||
|
||||
Keep these ideas in mind when using personal access tokens:
|
||||
|
||||
|
|
|
|||
|
|
@ -120,13 +120,13 @@ You'll need to create a new JWT after the time expires.
|
|||
|
||||
### Accessing API endpoints as a {% data variables.product.prodname_github_app %}
|
||||
|
||||
For a list of REST API endpoints you can use to get high-level information about a {% data variables.product.prodname_github_app %}, see "[GitHub Apps](/v3/apps/)."
|
||||
For a list of REST API endpoints you can use to get high-level information about a {% data variables.product.prodname_github_app %}, see "[GitHub Apps](/rest/reference/apps)."
|
||||
|
||||
### Authenticating as an installation
|
||||
|
||||
Authenticating as an installation lets you perform actions in the API for that installation. Before authenticating as an installation, you must create an installation access token. These installation access tokens are used by {% data variables.product.prodname_github_app %}s to authenticate.
|
||||
|
||||
By default, installation access tokens are scoped to all the repositories that an installation can access. You can limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. See the [Create an installation access token for an app](/v3/apps/#create-an-installation-access-token-for-an-app) endpoint for more details. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %} and expire after one hour.
|
||||
By default, installation access tokens are scoped to all the repositories that an installation can access. You can limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. See the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint for more details. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %} and expire after one hour.
|
||||
|
||||
To create an installation access token, include the JWT [generated above](#jwt-payload) in the Authorization header in the API request:
|
||||
|
||||
|
|
@ -146,7 +146,7 @@ $ curl -i -X POST \
|
|||
```
|
||||
{% endif %}
|
||||
|
||||
The response will include your installation access token, the expiration date, the token's permissions, and the repositories that the token can access. For more information about the response format, see the [Create an installation access token for an app](/v3/apps/#create-an-installation-access-token-for-an-app) endpoint.
|
||||
The response will include your installation access token, the expiration date, the token's permissions, and the repositories that the token can access. For more information about the response format, see the [Create an installation access token for an app](/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint.
|
||||
|
||||
To authenticate with an installation access token, include it in the Authorization header in the API request:
|
||||
|
||||
|
|
@ -170,9 +170,9 @@ $ curl -i \
|
|||
|
||||
### Accessing API endpoints as an installation
|
||||
|
||||
For a list of REST API endpoints that are available for use by {% data variables.product.prodname_github_app %}s using an installation access token, see "[Available Endpoints](/v3/apps/available-endpoints/)."
|
||||
For a list of REST API endpoints that are available for use by {% data variables.product.prodname_github_app %}s using an installation access token, see "[Available Endpoints](/rest/overview/endpoints-available-for-github-apps)."
|
||||
|
||||
For a list of endpoints related to installations, see "[Installations](/v3/apps/installations/)."
|
||||
For a list of endpoints related to installations, see "[Installations](/rest/reference/apps#installations)."
|
||||
|
||||
### HTTP-based Git access by an installation
|
||||
|
||||
|
|
|
|||
|
|
@ -236,13 +236,13 @@ For more information, see the "[OAuth 2.0 Device Authorization Grant](https://to
|
|||
|
||||
### Non-Web application flow
|
||||
|
||||
Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/v3/auth#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.
|
||||
Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
|
||||
{% note %}
|
||||
|
||||
**Note:** When using the non-web application flow to create an OAuth2 token, make sure to understand how to [work with
|
||||
two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if
|
||||
two-factor authentication](/rest/overview/other-authentication-methods#working-with-two-factor-authentication) if
|
||||
you or your users have two-factor authentication enabled.
|
||||
|
||||
{% endnote %}
|
||||
|
|
@ -296,7 +296,7 @@ To build this link, you'll need your OAuth Apps `client_id` that you received fr
|
|||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** To learn more about the resources that your OAuth App can access for a user, see "[Discovering resources for a user](/v3/guides/discovering-resources-for-a-user/)."
|
||||
**Tip:** To learn more about the resources that your OAuth App can access for a user, see "[Discovering resources for a user](/rest/guides/discovering-resources-for-a-user)."
|
||||
|
||||
{% endtip %}
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ The person creating the app will be redirected to a GitHub page with an input fi
|
|||
`description` | `string` | A description of the GitHub App.
|
||||
`public` | `boolean` | Set to `true` when your GitHub App is available to the public or `false` when it is only accessible to the owner of the app.
|
||||
`default_events` | `array` | The list of [events](/webhooks/event-payloads) the GitHub App subscribes to.
|
||||
`default_permissions` | `object` | The set of [permissions](/v3/apps/permissions/) needed by the GitHub App. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`).
|
||||
`default_permissions` | `object` | The set of [permissions](/rest/reference/permissions-required-for-github-apps) needed by the GitHub App. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`).
|
||||
|
||||
The `hook_attributes` object has the following key:
|
||||
|
||||
|
|
@ -153,13 +153,13 @@ If you provided a `state` parameter, you will also see that parameter in the `re
|
|||
|
||||
#### 3. You exchange the temporary code to retrieve the app configuration
|
||||
|
||||
To complete the handshake, send the temporary `code` in a `POST` request to the [Create a GitHub App from a manifest](/v3/apps/#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` (GitHub App ID), `pem` (private key), and `webhook_secret`. GitHub creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file.
|
||||
To complete the handshake, send the temporary `code` in a `POST` request to the [Create a GitHub App from a manifest](/rest/reference/apps#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` (GitHub App ID), `pem` (private key), and `webhook_secret`. GitHub creates a webhook secret for the app automatically. You can store these values in environment variables on the app's server. For example, if your app uses [dotenv](https://github.com/bkeepers/dotenv) to store environment variables, you would store the variables in your app's `.env` file.
|
||||
|
||||
You must complete this step of the GitHub App Manifest flow within one hour.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** This endpoint is rate limited. See [Rate limits](/v3/rate_limit/) to learn how to get your current rate limit status.
|
||||
**Note:** This endpoint is rate limited. See [Rate limits](/rest/reference/rate-limit) to learn how to get your current rate limit status.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ You must complete this step of the GitHub App Manifest flow within one hour.
|
|||
|
||||
POST /app-manifests/:code/conversions
|
||||
|
||||
For more information about the endpoint's response, see [Create a GitHub App from a manifest](/v3/apps/#create-a-github-app-from-a-manifest).
|
||||
For more information about the endpoint's response, see [Create a GitHub App from a manifest](/rest/reference/apps#create-a-github-app-from-a-manifest).
|
||||
|
||||
When the final step in the manifest flow is completed, the person creating the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time.
|
||||
|
||||
|
|
@ -191,4 +191,4 @@ Using [dotenv](https://github.com/bkeepers/dotenv), Probot creates a `.env` file
|
|||
|
||||
#### Hosting your app with Glitch
|
||||
|
||||
You can see an [example Probot app](https://glitch.com/~auspicious-aardwolf) that uses [Glitch](https://glitch.com/) to host and share the app. The example uses the [Checks API](/v3/checks/) and selects the necessary Checks API events and permissions in the `app.yml` file. Glitch is a tool that allows you to "Remix your own" apps. Remixing an app creates a copy of the app that Glitch hosts and deploys. See "[About Glitch](https://glitch.com/about/)" to learn about remixing Glitch apps.
|
||||
You can see an [example Probot app](https://glitch.com/~auspicious-aardwolf) that uses [Glitch](https://glitch.com/) to host and share the app. The example uses the [Checks API](/rest/reference/checks) and selects the necessary Checks API events and permissions in the `app.yml` file. Glitch is a tool that allows you to "Remix your own" apps. Remixing an app creates a copy of the app that Glitch hosts and deploys. See "[About Glitch](https://glitch.com/about/)" to learn about remixing Glitch apps.
|
||||
|
|
|
|||
|
|
@ -52,32 +52,32 @@ You can select permissions in a query string using the permission name in the fo
|
|||
Permission | Description
|
||||
---------- | -----------
|
||||
[`administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-administration) | Grants access to various endpoints for organization and repository administration. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %}
|
||||
[`blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-blocking) | Grants access to the [Blocking Users API](/v3/users/blocking/). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`checks`](/rest/reference/permissions-required-for-github-apps/#permission-on-checks) | Grants access to the [Checks API](/v3/checks/). Can be one of: `none`, `read`, or `write`.
|
||||
`content_references` | Grants access to the "[Create a content attachment](/v3/apps/installations/#create-a-content-attachment)" endpoint. Can be one of: `none`, `read`, or `write`.
|
||||
[`blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-blocking) | Grants access to the [Blocking Users API](/rest/reference/users#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`checks`](/rest/reference/permissions-required-for-github-apps/#permission-on-checks) | Grants access to the [Checks API](/rest/reference/checks). Can be one of: `none`, `read`, or `write`.
|
||||
`content_references` | Grants access to the "[Create a content attachment](/rest/reference/apps#create-a-content-attachment)" endpoint. Can be one of: `none`, `read`, or `write`.
|
||||
[`contents`](/rest/reference/permissions-required-for-github-apps/#permission-on-contents) | Grants access to various endpoints that allow you to modify repository contents. Can be one of: `none`, `read`, or `write`.
|
||||
[`deployments`](/rest/reference/permissions-required-for-github-apps/#permission-on-deployments) | Grants access to the [Deployments API](/rest/reference/repos#deployments). Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" or enterpriseServerVersions contains currentVersion %}
|
||||
[`emails`](/rest/reference/permissions-required-for-github-apps/#permission-on-emails) | Grants access to the [Emails API](/v3/users/emails/). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`followers`](/rest/reference/permissions-required-for-github-apps/#permission-on-followers) | Grants access to the [Followers API](/v3/users/followers/). Can be one of: `none`, `read`, or `write`.
|
||||
[`gpg_keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-gpg-keys) | Grants access to the [GPG Keys API](/v3/users/gpg_keys/). Can be one of: `none`, `read`, or `write`.
|
||||
[`issues`](/rest/reference/permissions-required-for-github-apps/#permission-on-issues) | Grants access to the [Issues API](/v3/issues/). Can be one of: `none`, `read`, or `write`.
|
||||
[`keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-keys) | Grants access to the [Public Keys API](/v3/users/keys/). Can be one of: `none`, `read`, or `write`.
|
||||
[`emails`](/rest/reference/permissions-required-for-github-apps/#permission-on-emails) | Grants access to the [Emails API](/rest/reference/users#emails). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`followers`](/rest/reference/permissions-required-for-github-apps/#permission-on-followers) | Grants access to the [Followers API](/rest/reference/users#followers). Can be one of: `none`, `read`, or `write`.
|
||||
[`gpg_keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-gpg-keys) | Grants access to the [GPG Keys API](/rest/reference/users#gpg-keys). Can be one of: `none`, `read`, or `write`.
|
||||
[`issues`](/rest/reference/permissions-required-for-github-apps/#permission-on-issues) | Grants access to the [Issues API](/rest/reference/issues). Can be one of: `none`, `read`, or `write`.
|
||||
[`keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-keys) | Grants access to the [Public Keys API](/rest/reference/users#keys). Can be one of: `none`, `read`, or `write`.
|
||||
[`members`](/rest/reference/permissions-required-for-github-apps/#permission-on-members) | Grants access to manage an organization's members. Can be one of: `none`, `read`, or `write`.{% if currentVersion == "free-pro-team@latest" %}
|
||||
[`metadata`](/rest/reference/permissions-required-for-github-apps/#metadata-permissions) | Grants access to read-only endpoints that do not leak sensitive data. Can be `read` or `none`. Defaults to `read` when you set any permission, or defaults to `none` when you don't specify any permissions for the {% data variables.product.prodname_github_app %}.
|
||||
[`organization_administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-administration) | Grants access to "[Update an organization](/v3/orgs/#update-an-organization)" endpoint and the [Organization Interaction Restrictions API](/v3/interactions/orgs/#set-interaction-restrictions-for-an-organization). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`organization_administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-administration) | Grants access to "[Update an organization](/rest/reference/orgs#update-an-organization)" endpoint and the [Organization Interaction Restrictions API](/rest/reference/interactions#set-interaction-restrictions-for-an-organization). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`organization_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-hooks) | Grants access to the [Organization Webhooks API](/rest/reference/orgs#webhooks/). Can be one of: `none`, `read`, or `write`.
|
||||
`organization_plan` | Grants access to get information about an organization's plan using the "[Get an organization](/v3/orgs/#get-an-organization)" endpoint. Can be one of: `none` or `read`.
|
||||
[`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/v3/projects/). Can be one of: `none`, `read`, `write`, or `admin`.{% if currentVersion == "free-pro-team@latest" %}
|
||||
[`organization_user_blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Blocking Organization Users API](/v3/orgs/blocking/). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
`organization_plan` | Grants access to get information about an organization's plan using the "[Get an organization](/rest/reference/orgs#get-an-organization)" endpoint. Can be one of: `none` or `read`.
|
||||
[`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% if currentVersion == "free-pro-team@latest" %}
|
||||
[`organization_user_blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Blocking Organization Users API](/rest/reference/orgs#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
|
||||
[`pages`](/rest/reference/permissions-required-for-github-apps/#permission-on-pages) | Grants access to the [Pages API](/rest/reference/repos#pages). Can be one of: `none`, `read`, or `write`.
|
||||
`plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/v3/users/#get-a-user)" endpoint. Can be one of: `none` or `read`.
|
||||
`plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/rest/reference/users#get-a-user)" endpoint. Can be one of: `none` or `read`.
|
||||
[`pull_requests`](/rest/reference/permissions-required-for-github-apps/#permission-on-pull-requests) | Grants access to various pull request endpoints. Can be one of: `none`, `read`, or `write`.
|
||||
[`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/v3/repos/hooks/). Can be one of: `none`, `read`, or `write`.
|
||||
[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/v3/projects/). Can be one of: `none`, `read`, `write`, or `admin`.
|
||||
[`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/v3/repos/contents/). Can be one of: `none`, `read`, or `write`.
|
||||
[`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/v3/activity/starring/). Can be one of: `none`, `read`, or `write`.
|
||||
[`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/v3/repos/statuses/). Can be one of: `none`, `read`, or `write`.
|
||||
[`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/v3/teams/discussions/) and the [Team Discussion Comments API](/v3/teams/discussion_comments/). Can be one of: `none`, `read`, or `write`.
|
||||
[`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/rest/reference/repos#hooks). Can be one of: `none`, `read`, or `write`.
|
||||
[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.
|
||||
[`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/rest/reference/repos#contents). Can be one of: `none`, `read`, or `write`.
|
||||
[`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/rest/reference/activity#starring). Can be one of: `none`, `read`, or `write`.
|
||||
[`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/rest/reference/repos#statuses). Can be one of: `none`, `read`, or `write`.
|
||||
[`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/rest/reference/teams#discussions) and the [Team Discussion Comments API](/rest/reference/teams#discussion-comments). Can be one of: `none`, `read`, or `write`.
|
||||
`vulnerability_alerts`| Grants access to receive security alerts for vulnerable dependencies in a repository. See "[About security alerts for vulnerable dependencies](/articles/about-security-alerts-for-vulnerable-dependencies)" to learn more. Can be one of: `none` or `read`.
|
||||
`watching` | Grants access to list and change repositories a user is subscribed to. Can be one of: `none`, `read`, or `write`.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ versions:
|
|||
|
||||
### Introduction
|
||||
|
||||
This guide will introduce you to [Github Apps](/apps/) and the [Checks API](/v3/checks/), which you'll use to build a continuous integration (CI) server that runs tests.
|
||||
This guide will introduce you to [Github Apps](/apps/) and the [Checks API](/rest/reference/checks), which you'll use to build a continuous integration (CI) server that runs tests.
|
||||
|
||||
CI is a software practice that requires frequently committing code to a shared repository. Committing code more often raises errors sooner and reduces the amount of code a developer needs to debug when finding the source of an error. Frequent code updates also make it easier to merge changes from different members of a software development team. This is great for developers, who can spend more time writing code and less time debugging errors or resolving merge conflicts. 🙌
|
||||
|
||||
|
|
@ -22,15 +22,15 @@ A CI server hosts code that runs CI tests such as code linters (which check styl
|
|||
|
||||
#### Checks API overview
|
||||
|
||||
The [Checks API](/v3/checks/) allows you to set up CI tests that are automatically run against each code commit in a repository. The Checks API reports detailed information about each check on GitHub in the pull request's **Checks** tab. With the Checks API, you can create annotations with additional details for specific lines of code. Annotations are visible in the **Checks** tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the **Files changed** tab.
|
||||
The [Checks API](/rest/reference/checks) allows you to set up CI tests that are automatically run against each code commit in a repository. The Checks API reports detailed information about each check on GitHub in the pull request's **Checks** tab. With the Checks API, you can create annotations with additional details for specific lines of code. Annotations are visible in the **Checks** tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the **Files changed** tab.
|
||||
|
||||
A _check suite_ is a group of _check runs_ (individual CI tests). Both the suite and the runs contain _statuses_ that are visible in a pull request on GitHub. You can use statuses to determine when a code commit introduces errors. Using these statuses with [protected branches](/v3/repos/branches/) can prevent people from merging pull requests prematurely. See "[Enabling required status checks](/articles/enabling-required-status-checks/)" for more details.
|
||||
A _check suite_ is a group of _check runs_ (individual CI tests). Both the suite and the runs contain _statuses_ that are visible in a pull request on GitHub. You can use statuses to determine when a code commit introduces errors. Using these statuses with [protected branches](/rest/reference/repos#branches) can prevent people from merging pull requests prematurely. See "[Enabling required status checks](/articles/enabling-required-status-checks/)" for more details.
|
||||
|
||||
The Checks API sends the [`check_suite` webhook event](/webhooks/event-payloads/#check_suite) to all GitHub Apps installed on a repository each time new code is pushed to the repository. To receive all Checks API event actions, the app must have the `checks:write` permission. GitHub automatically creates `check_suite` events for new code commits in a repository using the default flow, although [Update repository preferences for check suites](/v3/checks/suites/#update-repository-preferences-for-check-suites) if you'd like. Here's how the default flow works:
|
||||
The Checks API sends the [`check_suite` webhook event](/webhooks/event-payloads/#check_suite) to all GitHub Apps installed on a repository each time new code is pushed to the repository. To receive all Checks API event actions, the app must have the `checks:write` permission. GitHub automatically creates `check_suite` events for new code commits in a repository using the default flow, although [Update repository preferences for check suites](/rest/reference/checks#update-repository-preferences-for-check-suites) if you'd like. Here's how the default flow works:
|
||||
|
||||
1. Whenever someone pushes code to the repository, GitHub sends the `check_suite` event with an action of `requested` to all GitHub Apps installed on the repository that have the `checks:write` permission. This event lets the apps know that code was pushed and that GitHub has automatically created a new check suite.
|
||||
1. When your app receives this event, it can [add check runs](/v3/checks/runs/#create-a-check-run) to that suite.
|
||||
1. Your check runs can include [annotations](/v3/checks/runs/#annotations-object) that are displayed on specific lines of code.
|
||||
1. When your app receives this event, it can [add check runs](/rest/reference/checks#create-a-check-run) to that suite.
|
||||
1. Your check runs can include [annotations](/rest/reference/checks#annotations-object) that are displayed on specific lines of code.
|
||||
|
||||
**In this guide, you’ll learn how to:**
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ To get an idea of what your Checks API CI server will do when you've completed t
|
|||
|
||||
### Prerequisites
|
||||
|
||||
Before you get started, you may want to familiarize yourself with [Github Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/v3/checks/), if you're not already. You'll find more APIs in the [REST API docs](/v3/). The Checks API is also available to use in [GraphQL](/v4/), but this quickstart focuses on REST. See the GraphQL [Checks Suite](/v4/object/checksuite/) and [Check Run](/v4/object/checkrun/) objects for more details.
|
||||
Before you get started, you may want to familiarize yourself with [Github Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/rest/reference/checks), if you're not already. You'll find more APIs in the [REST API docs](/rest). The Checks API is also available to use in [GraphQL](/graphql), but this quickstart focuses on REST. See the GraphQL [Checks Suite](/graphql/reference/objects#checksuite) and [Check Run](/graphql/reference/objects#checkrun) objects for more details.
|
||||
|
||||
You'll use the [Ruby programming language](https://www.ruby-lang.org/en/), the [Smee](https://smee.io/) webhook payload delivery service, the [Octokit.rb Ruby library](http://octokit.github.io/octokit.rb/) for the GitHub REST API, and the [Sinatra web framework](http://sinatrarb.com/) to create your Checks API CI server app.
|
||||
|
||||
|
|
@ -140,7 +140,7 @@ You'll add this new method as a [Sinatra helper](https://github.com/sinatra/sina
|
|||
def create_check_run
|
||||
# # At the time of writing, Octokit does not support the Checks API yet, but
|
||||
# it does provide generic HTTP methods you can use:
|
||||
# /v3/checks/runs/#create-a-check-run
|
||||
# /rest/reference/checks#create-a-check-run
|
||||
check_run = @installation_client.post(
|
||||
"repos/#{@payload['repository']['full_name']}/check-runs",
|
||||
{
|
||||
|
|
@ -159,7 +159,7 @@ end
|
|||
def create_check_run
|
||||
# # At the time of writing, Octokit does not support the Checks API yet, but
|
||||
# it does provide generic HTTP methods you can use:
|
||||
# /v3/checks/runs/#create-a-check-run
|
||||
# /rest/reference/checks#create-a-check-run
|
||||
check_run = @installation_client.post(
|
||||
"repos/#{@payload['repository']['full_name']}/check-runs",
|
||||
{
|
||||
|
|
@ -175,7 +175,7 @@ end
|
|||
```
|
||||
{% endif %}
|
||||
|
||||
This code calls the "[Create a check run](/v3/checks/runs/#create-a-check-run)" endpoint using the generic [HTTP `POST` method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#post-instance_method). This method takes two parameters: the URL of the endpoint and the input parameters to the method.
|
||||
This code calls the "[Create a check run](/rest/reference/checks#create-a-check-run)" endpoint using the generic [HTTP `POST` method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#post-instance_method). This method takes two parameters: the URL of the endpoint and the input parameters to the method.
|
||||
|
||||
To create a check run, only two input parameters are required: `name` and `head_sha`. We will use [Rubocop](https://rubocop.readthedocs.io/en/latest/) to implement the CI test later in this quickstart, which is why the name "Octo Rubocop" is used here, but you can choose any name you'd like for the check run.
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ def initiate_check_run
|
|||
|
||||
# Octokit doesn't yet support the Checks API, but it does provide generic
|
||||
# HTTP methods you can use:
|
||||
# /v3/checks/runs/#update-a-check-run
|
||||
# /rest/reference/checks#update-a-check-run
|
||||
updated_check_run = @installation_client.patch(
|
||||
"repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}",
|
||||
{
|
||||
|
|
@ -276,7 +276,7 @@ def initiate_check_run
|
|||
|
||||
# Octokit doesn't yet support the Checks API, but it does provide generic
|
||||
# HTTP methods you can use:
|
||||
# /v3/checks/runs/#update-a-check-run
|
||||
# /rest/reference/checks#update-a-check-run
|
||||
updated_check_run = @installation_client.patch(
|
||||
"repos/#{@payload['repository']['full_name']}/check-runs/#{@payload['check_run']['id']}",
|
||||
{
|
||||
|
|
@ -305,11 +305,11 @@ end
|
|||
```
|
||||
{% endif %}
|
||||
|
||||
The code above calls the "[Update a check run](/v3/checks/runs/#update-a-check-run)" API endpoint using the generic [`patch` HTTP method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#patch-instance_method) to update the check run that you already created.
|
||||
The code above calls the "[Update a check run](/rest/reference/checks#update-a-check-run)" API endpoint using the generic [`patch` HTTP method](http://octokit.github.io/octokit.rb/Octokit/Connection.html#patch-instance_method) to update the check run that you already created.
|
||||
|
||||
Here's what this code is doing. First, it updates the check run's status to `in_progress` and sets the `started_at` time to the current time. In [Part 2](#part-2-creating-the-octo-rubocop-ci-test) of this quickstart, you'll add code that kicks off a real CI test under `***** RUN A CI TEST *****`. For now, you'll leave that section as a placeholder, so the code that follows it will just simulate that the CI process succeeds and all tests pass. Finally, the code updates the status of the check run again to `completed`.
|
||||
|
||||
You'll notice in the "[Update a check run](/v3/checks/runs/#update-a-check-run)" docs that when you provide a status of `completed`, the `conclusion` and `completed_at` parameters are required. The `conclusion` summarizes the outcome of a check run and can be `success`, `failure`, `neutral`, `cancelled`, `timed_out`, or `action_required`. You'll set the conclusion to `success`, the `completed_at` time to the current time, and the status to `completed`.
|
||||
You'll notice in the "[Update a check run](/rest/reference/checks#update-a-check-run)" docs that when you provide a status of `completed`, the `conclusion` and `completed_at` parameters are required. The `conclusion` summarizes the outcome of a check run and can be `success`, `failure`, `neutral`, `cancelled`, `timed_out`, or `action_required`. You'll set the conclusion to `success`, the `completed_at` time to the current time, and the status to `completed`.
|
||||
|
||||
You could also provide more details about what your check is doing, but you'll get to that in the next section. Let's test this code again by re-running `template_server.rb`:
|
||||
|
||||
|
|
@ -435,7 +435,7 @@ The code above gets the full repository name and the head SHA of the commit from
|
|||
|
||||
### Step 2.3. Running RuboCop
|
||||
|
||||
Great! You're cloning the repository and creating check runs using your CI server. Now you'll get into the nitty gritty details of the [RuboCop linter](https://rubocop.readthedocs.io/en/latest/basic_usage/#rubocop-as-a-code-style-checker) and [Checks API annotations](/v3/checks/runs/#create-a-check-run).
|
||||
Great! You're cloning the repository and creating check runs using your CI server. Now you'll get into the nitty gritty details of the [RuboCop linter](https://rubocop.readthedocs.io/en/latest/basic_usage/#rubocop-as-a-code-style-checker) and [Checks API annotations](/rest/reference/checks#create-a-check-run).
|
||||
|
||||
The following code runs RuboCop and saves the style code errors in JSON format. Add this code below the call to `clone_repository` you added in the [previous step](#step-22-cloning-the-repository) and above the code that updates the check run to complete.
|
||||
|
||||
|
|
@ -523,11 +523,11 @@ You should see the linting errors in the debug output, although they aren't prin
|
|||
|
||||
The `@output` variable contains the parsed JSON results of the RuboCop report. As shown above, the results contain a `summary` section that your code can use to quickly determine if there are any errors. The following code will set the check run conclusion to `success` when there are no reported errors. RuboCop reports errors for each file in the `files` array, so if there are errors, you'll need to extract some data from the file object.
|
||||
|
||||
The Checks API allows you to create annotations for specific lines of code. When you create or update a check run, you can add annotations. In this quickstart you are [updating the check run](/v3/checks/runs/#update-a-check-run) with annotations.
|
||||
The Checks API allows you to create annotations for specific lines of code. When you create or update a check run, you can add annotations. In this quickstart you are [updating the check run](/rest/reference/checks#update-a-check-run) with annotations.
|
||||
|
||||
The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the [Update a check run](/v3/checks/runs/#update-a-check-run) endpoint. For example, to create 105 annotations you'd need to call the [Update a check run](/v3/checks/runs/#update-a-check-run) endpoint three times. The first two requests would each have 50 annotations, and the third request would include the five remaining annotations. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run.
|
||||
The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the [Update a check run](/rest/reference/checks#update-a-check-run) endpoint. For example, to create 105 annotations you'd need to call the [Update a check run](/rest/reference/checks#update-a-check-run) endpoint three times. The first two requests would each have 50 annotations, and the third request would include the five remaining annotations. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run.
|
||||
|
||||
A check run expects annotations as an array of objects. Each annotation object must include the `path`, `start_line`, `end_line`, `annotation_level`, and `message`. RuboCop provides the `start_column` and `end_column` too, so you can include those optional parameters in the annotation. Annotations only support `start_column` and `end_column` on the same line. See the [`annotations` object](/v3/checks/runs/#annotations-object-1) reference documentation for details.
|
||||
A check run expects annotations as an array of objects. Each annotation object must include the `path`, `start_line`, `end_line`, `annotation_level`, and `message`. RuboCop provides the `start_column` and `end_column` too, so you can include those optional parameters in the annotation. Annotations only support `start_column` and `end_column` on the same line. See the [`annotations` object](/rest/reference/checks#annotations-object-1) reference documentation for details.
|
||||
|
||||
You'll extract the required information from RuboCop needed to create each annotation. Append the following code to the code you added in the [previous section](#step-23-running-rubocop):
|
||||
|
||||
|
|
@ -536,7 +536,7 @@ annotations = []
|
|||
# You can create a maximum of 50 annotations per request to the Checks
|
||||
# API. To add more than 50 annotations, use the "Update a check run" API
|
||||
# endpoint. This example code limits the number of annotations to 50.
|
||||
# See /v3/checks/runs/#update-a-check-run
|
||||
# See /rest/reference/checks#update-a-check-run
|
||||
# for details.
|
||||
max_annotations = 50
|
||||
|
||||
|
|
@ -869,4 +869,4 @@ After walking through this guide, you've learned the basics of using the Checks
|
|||
Here are some ideas for what you can do next:
|
||||
|
||||
* Currently, the "Fix this" button is always displayed. Update the code you wrote to display the "Fix this" button only when RuboCop finds errors.
|
||||
* If you'd prefer that RuboCop doesn't commit files directly to the head branch, you can update the code to [create a pull request](/v3/pulls/#create-a-pull-request) with a new branch based on the head branch.
|
||||
* If you'd prefer that RuboCop doesn't commit files directly to the head branch, you can update the code to [create a pull request](/rest/reference/pulls#create-a-pull-request) with a new branch based on the head branch.
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ Unlike OAuth apps, GitHub Apps have targeted permissions that allow them to requ
|
|||
|
||||
| GitHub Apps | OAuth Apps |
|
||||
| ----- | ----------- |
|
||||
| GitHub Apps ask for repository contents permission and use your installation token to authenticate via [HTTP-based Git](/apps/building-github-apps/authenticating-with-github-apps/#http-based-git-access-by-an-installation). | OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/v3/repos/keys/#create-a-deploy-key) via the API. You can then use that key to perform Git commands. |
|
||||
| GitHub Apps ask for repository contents permission and use your installation token to authenticate via [HTTP-based Git](/apps/building-github-apps/authenticating-with-github-apps/#http-based-git-access-by-an-installation). | OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/rest/reference/repos#create-a-deploy-key) via the API. You can then use that key to perform Git commands. |
|
||||
| The token is used as the HTTP password. | The token is used as the HTTP username. |
|
||||
|
||||
### Machine vs. bot accounts
|
||||
|
|
|
|||
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
|
|
@ -23,7 +23,7 @@ This article provides guidelines for existing integrators who are considering mi
|
|||
- Built-in support for OAuth is still available to GitHub Apps using [user-to-server endpoints](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/).
|
||||
- Dedicated [API rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/) for bot accounts scale with your integration.
|
||||
- Repository owners can [install GitHub Apps](/apps/differences-between-apps/#who-can-install-github-apps-and-authorize-oauth-apps) on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation.
|
||||
- Open Source community support is available through [Octokit libraries](/v3/libraries/) and other frameworks such as [Probot](https://probot.github.io/).
|
||||
- Open Source community support is available through [Octokit libraries](/rest/overview/libraries) and other frameworks such as [Probot](https://probot.github.io/).
|
||||
- Integrators building GitHub Apps have opportunities to adopt earlier access to APIs.
|
||||
|
||||
### Converting an OAuth App to a GitHub App
|
||||
|
|
@ -42,13 +42,13 @@ These guidelines assume that you have a registered OAuth App{% if currentVersion
|
|||
|
||||
#### Review the available API endpoints for GitHub Apps
|
||||
|
||||
While the majority of [REST API](/v3) endpoints and [GraphQL](/v4) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/v3/apps/available-endpoints/) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user.
|
||||
While the majority of [REST API](/rest) endpoints and [GraphQL](/graphql) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/rest/overview/endpoints-available-for-github-apps) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user.
|
||||
|
||||
We recommend reviewing the list of API endpoints you need as early as possible. Please let Support know if there is an endpoint you require that is not yet enabled for {% data variables.product.prodname_github_app %}s.
|
||||
|
||||
#### Design to stay within API rate limits
|
||||
|
||||
GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/v3/#conditional-requests) or consolidate requests by using the [GraphQL API V4](/v4/).
|
||||
GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest#conditional-requests) or consolidate requests by using the [GraphQL API V4](/graphql).
|
||||
|
||||
#### Register a new GitHub App
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ Once you've decided to make the switch to Github Apps, you'll need to [create a
|
|||
|
||||
#### Determine the permissions your app requires
|
||||
|
||||
When registering your GitHub App, you'll need to select the permissions required by each endpoint used in your app's code. See "[GitHub App permissions](/v3/apps/permissions/)" for a list of the permissions needed for each endpoint available to GitHub Apps.
|
||||
When registering your GitHub App, you'll need to select the permissions required by each endpoint used in your app's code. See "[GitHub App permissions](/rest/reference/permissions-required-for-github-apps)" for a list of the permissions needed for each endpoint available to GitHub Apps.
|
||||
|
||||
In your GitHub App's settings, you can specify whether your app needs `No Access`, `Read-only`, or `Read & Write` access for each permission type. The fine-grained permissions allow your app to gain targeted access to the subset of data you need. We recommend specifying the smallest set of permissions possible that provides the desired functionality.
|
||||
|
||||
|
|
@ -90,11 +90,11 @@ Once you've made the transition from an OAuth App to a GitHub App, you will need
|
|||
https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID
|
||||
```
|
||||
|
||||
You'll need to replace `YOUR_APP_NAME` with the name of your GitHub App, `ID_OF_USER_OR_ORG` with the ID of your target user or organization, and include up to 100 repository IDs (`REPO_A_ID` and `REPO_B_ID`). To get a list of repositories your OAuth App has access to, use the [List repositories for the authenticated user](/v3/repos/#list-repositories-for-the-authenticated-user) and [List organization repositories](/v3/repos/#list-organization-repositories) endpoints.
|
||||
You'll need to replace `YOUR_APP_NAME` with the name of your GitHub App, `ID_OF_USER_OR_ORG` with the ID of your target user or organization, and include up to 100 repository IDs (`REPO_A_ID` and `REPO_B_ID`). To get a list of repositories your OAuth App has access to, use the [List repositories for the authenticated user](/rest/reference/repos#list-repositories-for-the-authenticated-user) and [List organization repositories](/rest/reference/repos#list-organization-repositories) endpoints.
|
||||
|
||||
#### Remove any unnecessary repository hooks
|
||||
|
||||
Once your GitHub App has been installed on a repository, you should remove any unnecessary webhooks that were created by your legacy OAuth App. If both apps are installed on a repository, they may duplicate functionality for the user. To remove webhooks, you can listen for the [`installation_repositories` webhook](/webhooks/event-payloads/#installation_repositories) with the `repositories_added` action and [Delete a repository webhook](/v3/repos/hooks/#delete-a-repository-webhook) on those repositories that were created by your OAuth App.
|
||||
Once your GitHub App has been installed on a repository, you should remove any unnecessary webhooks that were created by your legacy OAuth App. If both apps are installed on a repository, they may duplicate functionality for the user. To remove webhooks, you can listen for the [`installation_repositories` webhook](/webhooks/event-payloads/#installation_repositories) with the `repositories_added` action and [Delete a repository webhook](/rest/reference/repos#delete-a-repository-webhook) on those repositories that were created by your OAuth App.
|
||||
|
||||
#### Encourage users to revoke access to your OAuth app
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ To renew an expiring user-to-server access token, you can exchange the `refresh_
|
|||
|
||||
`POST https://github.com/login/oauth/access_token`
|
||||
|
||||
This callback request will send you a new access token and a new refresh token. This callback request is similar to the OAuth request you would use to exchange a temporary `code` for an access token. For more information, see "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#2-users-are-redirected-back-to-your-site-by-github)" and "[Basics of authentication](/v3/guides/basics-of-authentication/#providing-a-callback)."
|
||||
This callback request will send you a new access token and a new refresh token. This callback request is similar to the OAuth request you would use to exchange a temporary `code` for an access token. For more information, see "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#2-users-are-redirected-back-to-your-site-by-github)" and "[Basics of authentication](/rest/guides/basics-of-authentication#providing-a-callback)."
|
||||
|
||||
#### Parameters
|
||||
|
||||
|
|
|
|||
|
|
@ -40,13 +40,13 @@ X-Accepted-OAuth-Scopes: user
|
|||
Name | Description
|
||||
-----|-----------|
|
||||
**`(no scope)`** | Grants read-only access to public information (includes public user profile info, public repository info, and gists){% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}
|
||||
**`site_admin`** | Grants site administrators access to [{% data variables.product.prodname_ghe_server %} Administration API endpoints](/v3/enterprise-admin).{% endif %}
|
||||
**`site_admin`** | Grants site administrators access to [{% data variables.product.prodname_ghe_server %} Administration API endpoints](/rest/reference/enterprise-admin).{% endif %}
|
||||
**`repo`** | Grants full access to private and public repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for public and private repositories and organizations. Also grants ability to manage user projects.
|
||||
 `repo:status`| Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code.
|
||||
 `repo_deployment`| Grants access to [deployment statuses](/v3/repos/deployments) for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code.
|
||||
 `repo_deployment`| Grants access to [deployment statuses](/rest/reference/repos#deployments) for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code.
|
||||
 `public_repo`| Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
|
||||
 `repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest"%}
|
||||
 `security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/v3/code-scanning).{% endif %}
|
||||
 `security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning).{% endif %}
|
||||
**`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in public and private repositories. The `repo` and `public_repo` scopes grants full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks.
|
||||
 `write:repo_hook` | Grants read, write, and ping access to hooks in public or private repositories.
|
||||
 `read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
|
||||
|
|
|
|||
|
|
@ -17,4 +17,4 @@ When you create a GitHub App, you can select the permissions it needs to access
|
|||
|
||||
By default, GitHub Apps have `Read-only` access to metadata endpoints. Metadata is a collection of read-only endpoints that provide general information about resources that the authorized installation can access.
|
||||
|
||||
{% data reusables.apps.metadata-permissions %} For a list of metadata endpoints, see "[Metadata permissions](/v3/apps/permissions/#metadata-permissions)."
|
||||
{% data reusables.apps.metadata-permissions %} For a list of metadata endpoints, see "[Metadata permissions](/rest/reference/permissions-required-for-github-apps#metadata-permissions)."
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ You may find it helpful to have a basic understanding of the following:
|
|||
* [GitHub Apps](/apps/about-apps)
|
||||
* [Webhooks](/webhooks)
|
||||
* [The Ruby programming language](https://www.ruby-lang.org/en/)
|
||||
* [REST APIs](/v3)
|
||||
* [REST APIs](/rest)
|
||||
* [Sinatra](http://sinatrarb.com/)
|
||||
|
||||
But you can follow along at any experience level. We'll link out to information you need along the way!
|
||||
|
|
@ -220,7 +220,7 @@ end
|
|||
|
||||
#### Define a route handler
|
||||
|
||||
An empty route is included in the template code. This code handles all `POST` requests to the `/event_handler` route. You'll won't write this event handler in this quickstart, but see the other [quickstart guides](/apps/quickstart-guides/) for examples of how to extend this template app.
|
||||
An empty route is included in the template code. This code handles all `POST` requests to the `/event_handler` route. You won't write this event handler in this quickstart, but see the other [quickstart guides](/apps/quickstart-guides/) for examples of how to extend this template app.
|
||||
|
||||
``` ruby
|
||||
post '/event_handler' do
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ The content attachment flow shows you the relationship between the URL in the is
|
|||
}
|
||||
```
|
||||
|
||||
**Step 4.** The app uses the `content_reference` `id`, to [Create a content attachment](/v3/apps/installations/#create-a-content-attachment) using the REST API. You'll also need the `installation` `id` to authenticate as a [GitHub App installation](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation).
|
||||
**Step 4.** The app uses the `content_reference` `id`, to [Create a content attachment](/rest/reference/apps#create-a-content-attachment) using the REST API. You'll also need the `installation` `id` to authenticate as a [GitHub App installation](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation).
|
||||
|
||||
{% data reusables.pre-release-program.corsair-preview %}
|
||||
{% data reusables.pre-release-program.api-preview-warning %}
|
||||
|
|
@ -116,7 +116,7 @@ curl -X "POST" "https://api.github.com/graphql" \
|
|||
}'
|
||||
```
|
||||
|
||||
For more information on `node_id`, see "[Using Global Node IDs](/v4/guides/using-global-node-ids/)."
|
||||
For more information on `node_id`, see "[Using Global Node IDs](/graphql/guides/using-global-node-ids)."
|
||||
|
||||
### Example using Probot and GitHub App Manifests
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ You may find it helpful to have a basic understanding of the following:
|
|||
* [GitHub Apps](/apps/about-apps)
|
||||
* [Webhooks](/webhooks)
|
||||
* [The Ruby programming language](https://www.ruby-lang.org/en/)
|
||||
* [REST APIs](/v3)
|
||||
* [REST APIs](/rest)
|
||||
* [Sinatra](http://sinatrarb.com/)
|
||||
|
||||
But you can follow along at any experience level. We'll link out to information you need along the way!
|
||||
|
|
@ -143,11 +143,11 @@ Before the label can be _added_ anywhere, you'll need to _create_ the custom lab
|
|||
|
||||
{% tip %}
|
||||
|
||||
**Tip**: Wouldn't it be great if your app could create the label programmatically? [It can](/v3/issues/labels/#create-a-label)! Try adding the code to do that on your own after you finish the steps in this guide.
|
||||
**Tip**: Wouldn't it be great if your app could create the label programmatically? [It can](/rest/reference/issues#create-a-label)! Try adding the code to do that on your own after you finish the steps in this guide.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
Now that the label exists, you can program your app to use the REST API to [add the label to any newly opened issue](/v3/issues/labels/#add-labels-to-an-issue).
|
||||
Now that the label exists, you can program your app to use the REST API to [add the label to any newly opened issue](/rest/reference/issues#add-labels-to-an-issue).
|
||||
|
||||
### Step 4. Add label handling
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ Customers must be able to perform the following actions from your app's website:
|
|||
|
||||
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)."
|
||||
|
||||
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](/v3/apps/marketplace/#list-accounts-for-a-plan).
|
||||
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).
|
||||
|
||||
#### Upgrades
|
||||
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ After the customer completes the authorization, your app receives an OAuth acces
|
|||
|
||||
### Step 4. Provisioning customer accounts
|
||||
|
||||
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[List subscriptions for the authenticated user](/v3/apps/marketplace/#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
|
||||
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
|
||||
|
||||
{% data reusables.marketplace.marketplace-double-purchases %}
|
||||
|
||||
|
|
@ -76,6 +76,6 @@ If the purchase is for an organization and per-user, you can prompt the customer
|
|||
|
||||
You can customize the way that organization members receive access to your app. Here are a few suggestions:
|
||||
|
||||
**Flat-rate pricing:** If the purchase is made for an organization using flat-rate pricing, your app can [get all the organization’s members](/v3/orgs/members/#list-organization-members) via the API and prompt the organization admin to choose which members will have paid users on the integrator side.
|
||||
**Flat-rate pricing:** If the purchase is made for an organization using flat-rate pricing, your app can [get all the organization’s members](/rest/reference/orgs#list-organization-members) via the API and prompt the organization admin to choose which members will have paid users on the integrator side.
|
||||
|
||||
**Per-unit pricing:** One method of provisioning per-unit seats is to allow users to occupy a seat as they log in to the app. Once the customer hits the seat count threshold, your app can alert the user that they need to upgrade through {% data variables.product.prodname_marketplace %}.
|
||||
|
|
|
|||
|
|
@ -28,6 +28,6 @@ When a customer cancels a free or paid plan, your app must perform these steps t
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note:** We recommend using the [`marketplace_purchase`](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook's `effective_date` to determine when a plan change will occur and periodically synchronizing the [List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan). For more information on webhooks, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)."
|
||||
**Note:** We recommend using the [`marketplace_purchase`](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook's `effective_date` to determine when a plan change will occur and periodically synchronizing the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan). For more information on webhooks, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)."
|
||||
|
||||
{% endnote %}
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/
|
|||
|
||||
For example, if you notice that a customer is on a 5 person plan and needs to move to a 10 person plan, you could display a button in your app's UI that says "Here's how to upgrade" or show a banner with a link to the upgrade URL. The upgrade URL takes the customer to your listing plan's upgrade confirmation page.
|
||||
|
||||
Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/v3/apps/marketplace/#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`.
|
||||
Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/rest/reference/apps#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`.
|
||||
|
||||
|
||||
{% note %}
|
||||
|
|
|
|||
|
|
@ -13,10 +13,10 @@ versions:
|
|||
|
||||
Here are some useful endpoints available for Marketplace listings:
|
||||
|
||||
* [List plans](/v3/apps/marketplace/#list-plans)
|
||||
* [List accounts for a plan](/v3/apps/marketplace/#list-accounts-for-a-plan)
|
||||
* [Get a subscription plan for an account](/v3/apps/marketplace/#get-a-subscription-plan-for-an-account)
|
||||
* [List subscriptions for the authenticated user](/v3/apps/marketplace/#list-subscriptions-for-the-authenticated-user)
|
||||
* [List plans](/rest/reference/apps#list-plans)
|
||||
* [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan)
|
||||
* [Get a subscription plan for an account](/rest/reference/apps#get-a-subscription-plan-for-an-account)
|
||||
* [List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)
|
||||
|
||||
See these pages for details on how to authenticate when using the {% data variables.product.prodname_marketplace %} API:
|
||||
|
||||
|
|
@ -25,6 +25,6 @@ See these pages for details on how to authenticate when using the {% data variab
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note:** [Rate limits for the REST API](/v3/#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints.
|
||||
**Note:** [Rate limits for the REST API](/rest#rate-limiting) apply to all {% data variables.product.prodname_marketplace %} API endpoints.
|
||||
|
||||
{% endnote %}
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ Your testing scenarios may require setting up listing plans that offer free tria
|
|||
|
||||
### Testing APIs
|
||||
|
||||
For most {% data variables.product.prodname_marketplace %} API endpoints, we also provide stubbed API endpoints that return hard-coded, fake data you can use for testing. To receive stubbed data, you must specify stubbed URLs, which include `/stubbed` in the route (for example, `/user/marketplace_purchases/stubbed`). For a list of endpoints that support this stubbed-data approach, see [{% data variables.product.prodname_marketplace %} endpoints](/v3/apps/marketplace/#github-marketplace).
|
||||
For most {% data variables.product.prodname_marketplace %} API endpoints, we also provide stubbed API endpoints that return hard-coded, fake data you can use for testing. To receive stubbed data, you must specify stubbed URLs, which include `/stubbed` in the route (for example, `/user/marketplace_purchases/stubbed`). For a list of endpoints that support this stubbed-data approach, see [{% data variables.product.prodname_marketplace %} endpoints](/rest/reference/apps#github-marketplace).
|
||||
|
||||
### Testing webhooks
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ The `marketplace_purchase` object has the following keys:
|
|||
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`account` | `object` | The `organization` or `user` account associated with the subscription. Organization accounts will include `organization_billing_email`, which is the organization's administrative email address. To find email addresses for personal accounts, you can use the [Get the authenticated user](/v3/users/#get-the-authenticated-user) endpoint.
|
||||
`account` | `object` | The `organization` or `user` account associated with the subscription. Organization accounts will include `organization_billing_email`, which is the organization's administrative email address. To find email addresses for personal accounts, you can use the [Get the authenticated user](/rest/reference/users#get-the-authenticated-user) endpoint.
|
||||
`billing_cycle` | `string` | Can be `yearly` or `monthly`. When the `account` owner has a free GitHub plan and has purchased a free {% data variables.product.prodname_marketplace %} plan, `billing_cycle` will be `nil`.
|
||||
`unit_count` | `integer` | Number of units purchased.
|
||||
`on_free_trial` | `boolean` | `true` when the `account` is on a free trial.
|
||||
|
|
|
|||
|
|
@ -9,11 +9,11 @@ versions:
|
|||
github-ae: '*'
|
||||
---
|
||||
|
||||
There are two stable versions of the GitHub API: the [REST API](/v3/) and the [GraphQL API](/v4/).
|
||||
There are two stable versions of the GitHub API: the [REST API](/rest) and the [GraphQL API](/graphql).
|
||||
|
||||
When using the REST API, we encourage you to [request v3 via the `Accept` header](/v3/media/#request-specific-version).
|
||||
When using the REST API, we encourage you to [request v3 via the `Accept` header](/rest/overview/media-types#request-specific-version).
|
||||
|
||||
For information on using the GraphQL API, see the [v4 docs](/v4/).
|
||||
For information on using the GraphQL API, see the [v4 docs](/graphql).
|
||||
|
||||
## Deprecated versions
|
||||
|
||||
|
|
|
|||
|
|
@ -31,4 +31,4 @@ See "[Webhook event payloads](/webhooks/event-payloads)" for the list of availab
|
|||
For more information about the `ping` event webhook payload, see the [`ping`](/webhooks/event-payloads/#ping) event.
|
||||
|
||||
[org-hooks]: /rest/reference/orgs#webhooks/
|
||||
[repo-hooks]: /v3/repos/hooks/
|
||||
[repo-hooks]: /rest/reference/repos#hooks
|
||||
|
|
|
|||
|
|
@ -65,5 +65,5 @@ When you're finished, click **Add webhook**. Phew! Now that you created the webh
|
|||
To configure a webhook for all events, use the wildcard (`*`) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.
|
||||
|
||||
[webhooks-overview]: /webhooks/
|
||||
[webhook-api]: /v3/repos/hooks/
|
||||
[webhook-api]: /rest/reference/repos#hooks
|
||||
[hooks-api]: /webhooks/#events
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ The event objects returned from the Events API endpoints have the same structure
|
|||
|
||||
#### Example WatchEvent event object
|
||||
|
||||
This example shows the format of the [WatchEvent](#watchevent) response when using the [Events API](/v3/activity/events).
|
||||
This example shows the format of the [WatchEvent](#watchevent) response when using the [Events API](/rest/reference/activity#events).
|
||||
|
||||
```
|
||||
Status: 200 OK
|
||||
|
|
@ -203,10 +203,10 @@ Key | Type | Description
|
|||
`push_id` | `integer` | Unique identifier for the push.
|
||||
`size`|`integer` | The number of commits in the push.
|
||||
`distinct_size`|`integer` | The number of distinct commits in the push.
|
||||
`ref`|`string` | The full [`git ref`](/v3/git/refs/) that was pushed. Example: `refs/heads/main`.
|
||||
`ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main`.
|
||||
`head`|`string` | The SHA of the most recent commit on `ref` after the push.
|
||||
`before`|`string` | The SHA of the most recent commit on `ref` before the push.
|
||||
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/v3/repos/commits/) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
|
||||
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
|
||||
`commits[][sha]`|`string` | The SHA of the commit.
|
||||
`commits[][message]`|`string` | The commit message.
|
||||
`commits[][author]`|`object` | The git author of the commit.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ versions:
|
|||
---
|
||||
|
||||
|
||||
Issue events are triggered by activity in issues and pull requests and are available in the [Issue Events API](/v3/issues/events) and the [Timeline Events API](/v3/issues/timeline). Each event type specifies whether the event is available in the Issue Events or Timeline Events APIs.
|
||||
Issue events are triggered by activity in issues and pull requests and are available in the [Issue Events API](/rest/reference/issues#events) and the [Timeline Events API](/rest/reference/issues#timeline). Each event type specifies whether the event is available in the Issue Events or Timeline Events APIs.
|
||||
|
||||
GitHub's REST API considers every pull request to be an issue, but not every issue is a pull request. For this reason, the Issue Events and Timeline Events endpoints may return both issues and pull requests in the response. Pull requests have a `pull_request` property in the `issue` object. Because pull requests are issues, issue and pull request numbers do not overlap in a repository. For example, if you open your first issue in a repository, the number will be 1. If you then open a pull request, the number will be 2. Each event type specifies if the event occurs in pull request, issues, or both.
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ Name | Type | Description
|
|||
`html_url` | `string` | The HTML URL of the issue comment.
|
||||
`issue_url` | `string` | The HTML URL of the issue.
|
||||
`id` | `integer` | The unique identifier of the event.
|
||||
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event.
|
||||
`node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
|
||||
`user` | `object` | The person who commented on the issue.
|
||||
`created_at` | `string` | The timestamp indicating when the comment was added.
|
||||
`updated_at` | `string` | The timestamp indicating when the comment was updated or created, if the comment is never updated.
|
||||
|
|
@ -155,7 +155,7 @@ A commit was added to the pull request's `HEAD` branch.
|
|||
Name | Type | Description
|
||||
-----|------|--------------
|
||||
`sha` | `string` | The SHA of the commit in the pull request.
|
||||
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event.
|
||||
`node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
|
||||
`url` | `string` | The REST API URL to retrieve the commit.
|
||||
`html_url` | `string` | The HTML URL of the commit.
|
||||
`author` | `object` | The person who authored the commit.
|
||||
|
|
@ -163,7 +163,7 @@ Name | Type | Description
|
|||
`tree` | `object` | The Git tree of the commit.
|
||||
`message` | `string` | The commit message.
|
||||
`parents` | `array of objects` | A list of parent commits.
|
||||
`verfication` | `object` | The result of verifying the commit's signature. For more information, see "[Signature verification object](/v3/git/commits/#signature-verification-object)."
|
||||
`verfication` | `object` | The result of verifying the commit's signature. For more information, see "[Signature verification object](/rest/reference/git#signature-verification-object)."
|
||||
`event` | `string` | The event value is `"committed"`.
|
||||
|
||||
### connected
|
||||
|
|
@ -587,7 +587,7 @@ The pull request was reviewed.
|
|||
Name | Type | Description
|
||||
-----|------|--------------
|
||||
`id` | `integer` | The unique identifier of the event.
|
||||
`node_id` | `string` | The [Global Node ID](/v4/guides/using-global-node-ids) of the event.
|
||||
`node_id` | `string` | The [Global Node ID](/graphql/guides/using-global-node-ids) of the event.
|
||||
`user` | `object` | The person who commented on the issue.
|
||||
`body` | `string` | The review summary text.
|
||||
`commit_id` | `string` | The SHA of the latest commit in the pull request at the time of the review.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ Key | Type | Description
|
|||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %} For more information, see "[Building {% data variables.product.prodname_github_app %}](/apps/building-github-apps/)."
|
||||
|
||||
The unique properties for a webhook event are the same properties you'll find in the `payload` property when using the [Events API](/v3/activity/events/). One exception is the [`push` event](#push). The unique properties of the `push` event webhook payload and the `payload` property in the Events API differ. The webhook payload contains more detailed information.
|
||||
The unique properties for a webhook event are the same properties you'll find in the `payload` property when using the [Events API](/rest/reference/activity#events). One exception is the [`push` event](#push). The unique properties of the `push` event webhook payload and the `payload` property in the Events API differ. The webhook payload contains more detailed information.
|
||||
|
||||
{% tip %}
|
||||
|
||||
|
|
@ -51,8 +51,8 @@ Header | Description
|
|||
`X-GitHub-Delivery`| A [GUID](http://en.wikipedia.org/wiki/Globally_unique_identifier) to identify the delivery.{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}
|
||||
`X-GitHub-Enterprise-Version` | The version of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.
|
||||
`X-GitHub-Enterprise-Host` | The hostname of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.{% endif %}{% if currentVersion != "github-ae@latest" %}
|
||||
`X-Hub-Signature`| This header is sent if the webhook is configured with a [`secret`](/v3/repos/hooks/#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the `secret` as the HMAC `key`.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} `X-Hub-Signature` is provided for compatibility with existing integrations, and we recommend that you use the more secure `X-Hub-Signature-256` instead.{% endif %}{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
|
||||
`X-Hub-Signature-256`| This header is sent if the webhook is configured with a [`secret`](/v3/repos/hooks/#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the `secret` as the HMAC `key`.{% endif %}
|
||||
`X-Hub-Signature`| This header is sent if the webhook is configured with a [`secret`](/rest/reference/repos#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the `secret` as the HMAC `key`.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} `X-Hub-Signature` is provided for compatibility with existing integrations, and we recommend that you use the more secure `X-Hub-Signature-256` instead.{% endif %}{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
|
||||
`X-Hub-Signature-256`| This header is sent if the webhook is configured with a [`secret`](/rest/reference/repos#create-hook-config-params). This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the `secret` as the HMAC `key`.{% endif %}
|
||||
|
||||
Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
|
||||
|
||||
|
|
@ -195,7 +195,7 @@ Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
|
|||
|
||||
{% data reusables.webhooks.content_reference_short_desc %}
|
||||
|
||||
Webhook events are triggered based on the specificity of the domain you register. For example, if you register a subdomain (`https://subdomain.example.com`) then only URLs for the subdomain trigger this event. If you register a domain (`https://example.com`) then URLs for domain and all subdomains trigger this event. See "[Create a content attachment](/v3/apps/installations/#create-a-content-attachment)" to create a new content attachment.
|
||||
Webhook events are triggered based on the specificity of the domain you register. For example, if you register a subdomain (`https://subdomain.example.com`) then only URLs for the subdomain trigger this event. If you register a domain (`https://example.com`) then URLs for domain and all subdomains trigger this event. See "[Create a content attachment](/rest/reference/apps#create-a-content-attachment)" to create a new content attachment.
|
||||
|
||||
Only {% data variables.product.prodname_github_app %}s can receive this event. {% data variables.product.prodname_github_app %}s must have the `content_references` `write` permission to subscribe to this event.
|
||||
|
||||
|
|
@ -715,7 +715,7 @@ Key | Type | Description
|
|||
|
||||
### package
|
||||
|
||||
Activity related to {% data variables.product.prodname_registry %}. {% data reusables.webhooks.action_type_desc %} For more information, see the "[blocking organization users](/v3/orgs/blocking/)" REST API. For more information, see "[Managing packages with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages)" to learn more about {% data variables.product.prodname_registry %}.
|
||||
Activity related to {% data variables.product.prodname_registry %}. {% data reusables.webhooks.action_type_desc %} For more information, see the "[blocking organization users](/rest/reference/orgs#blocking)" REST API. For more information, see "[Managing packages with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages)" to learn more about {% data variables.product.prodname_registry %}.
|
||||
|
||||
#### Availability
|
||||
|
||||
|
|
@ -775,7 +775,7 @@ Key | Type | Description
|
|||
----|------|------------
|
||||
`zen` | `string` | Random string of GitHub zen.
|
||||
`hook_id` | `integer` | The ID of the webhook that triggered the ping.
|
||||
`hook` | `object` | The [webhook configuration](/v3/repos/hooks/#get-a-repository-webhook).
|
||||
`hook` | `object` | The [webhook configuration](/rest/reference/repos#get-a-repository-webhook).
|
||||
`hook[app_id]` | `integer` | When you register a new {% data variables.product.prodname_github_app %}, {% data variables.product.product_name %} sends a ping event to the **webhook URL** you specified during registration. The event contains the `app_id`, which is required for [authenticating](/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/) an app.
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
|
|
@ -970,10 +970,10 @@ Deliveries for `review_requested` and `review_request_removed` events will have
|
|||
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`ref`|`string` | The full [`git ref`](/v3/git/refs/) that was pushed. Example: `refs/heads/main`.
|
||||
`ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main`.
|
||||
`before`|`string` | The SHA of the most recent commit on `ref` before the push.
|
||||
`after`|`string` | The SHA of the most recent commit on `ref` after the push.
|
||||
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/v3/repos/commits/) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
|
||||
`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
|
||||
`commits[][id]`|`string` | The SHA of the commit.
|
||||
`commits[][timestamp]`|`string` | The ISO 8601 timestamp of the commit.
|
||||
`commits[][message]`|`string` | The commit message.
|
||||
|
|
@ -1021,7 +1021,7 @@ Key | Type | Description
|
|||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.20" or currentVersion == "github-ae@latest" %}
|
||||
### repository_dispatch
|
||||
|
||||
This event occurs when a {% data variables.product.prodname_github_app %} sends a `POST` request to the "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)" endpoint.
|
||||
This event occurs when a {% data variables.product.prodname_github_app %} sends a `POST` request to the "[Create a repository dispatch event](/rest/reference/repos#create-a-repository-dispatch-event)" endpoint.
|
||||
|
||||
#### Availability
|
||||
|
||||
|
|
@ -1046,7 +1046,7 @@ This event occurs when a {% data variables.product.prodname_github_app %} sends
|
|||
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`action` |`string` | The action that was performed. This can be one of:<ul><li>`created` - A repository is created.</li><li>`deleted` - A repository is deleted. This event type is only available to [organization hooks](/rest/reference/orgs#webhooks/)</li><li>`archived` - A repository is archived.</li><li>`unarchived` - A repository is unarchived.</li>{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}<li>`anonymous_access_enabled` - A repository is [enabled for anonymous Git access](/v3/previews/#anonymous-git-access-to-repositories), `anonymous_access_disabled` - A repository is [disabled for anonymous Git access](/v3/previews/#anonymous-git-access-to-repositories)</li>{% endif %}<li>`edited` - A repository's information is edited.</li><li>`renamed` - A repository is renamed.</li><li>`transferred` - A repository is transferred.</li><li>`publicized` - A repository is made public.</li><li> `privatized` - A repository is made private.</li></ul>
|
||||
`action` |`string` | The action that was performed. This can be one of:<ul><li>`created` - A repository is created.</li><li>`deleted` - A repository is deleted. This event type is only available to [organization hooks](/rest/reference/orgs#webhooks/)</li><li>`archived` - A repository is archived.</li><li>`unarchived` - A repository is unarchived.</li>{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}<li>`anonymous_access_enabled` - A repository is [enabled for anonymous Git access](/rest/overview/api-previews#anonymous-git-access-to-repositories), `anonymous_access_disabled` - A repository is [disabled for anonymous Git access](/rest/overview/api-previews#anonymous-git-access-to-repositories)</li>{% endif %}<li>`edited` - A repository's information is edited.</li><li>`renamed` - A repository is renamed.</li><li>`transferred` - A repository is transferred.</li><li>`publicized` - A repository is made public.</li><li> `privatized` - A repository is made private.</li></ul>
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %}
|
||||
|
|
@ -1059,7 +1059,7 @@ Key | Type | Description
|
|||
{% if currentVersion == "free-pro-team@latest"%}
|
||||
### repository_import
|
||||
|
||||
{% data reusables.webhooks.repository_import_short_desc %} To receive this event for a personal repository, you must create an empty repository prior to the import. This event can be triggered using either the [GitHub Importer](/articles/importing-a-repository-with-github-importer/) or the [Source imports API](/v3/migrations/source_imports/).
|
||||
{% data reusables.webhooks.repository_import_short_desc %} To receive this event for a personal repository, you must create an empty repository prior to the import. This event can be triggered using either the [GitHub Importer](/articles/importing-a-repository-with-github-importer/) or the [Source imports API](/rest/reference/migrations#source-imports).
|
||||
|
||||
#### Availability
|
||||
|
||||
|
|
@ -1238,7 +1238,7 @@ Key | Type | Description
|
|||
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`team`|`object` | The [team](/v3/teams/) that was modified. **Note:** Older events may not include this in the payload.
|
||||
`team`|`object` | The [team](/rest/reference/teams) that was modified. **Note:** Older events may not include this in the payload.
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %}
|
||||
|
|
@ -1267,7 +1267,7 @@ When a user is `created` or `deleted`.
|
|||
|
||||
{% data reusables.webhooks.watch_short_desc %}
|
||||
|
||||
The event’s actor is the [user](/v3/users/) who starred a repository, and the event’s repository is the [repository](/v3/repos/) that was starred.
|
||||
The event’s actor is the [user](/rest/reference/users) who starred a repository, and the event’s repository is the [repository](/rest/reference/repos) that was starred.
|
||||
|
||||
#### Availability
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ If a release fixes a security vulnerability, you should publish a security advis
|
|||
You can view the **Dependents** tab of the dependency graph to see which repositories and packages depend on code in your repository, and may therefore be affected by a new release. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)."
|
||||
{% endif %}
|
||||
|
||||
You can also use the Releases API to gather information, such as the number of times people download a release asset. For more information, see "[Releases](/v3/repos/releases/)."
|
||||
You can also use the Releases API to gather information, such as the number of times people download a release asset. For more information, see "[Releases](/rest/reference/repos#releases)."
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
### Storage and bandwidth quotas
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ You can set up either loose or strict status checks, depending on whether you wa
|
|||
|
||||
### Troubleshooting required status checks
|
||||
|
||||
If you have a check and a status with the same name and you select that name as a required status check, both the check and the status are required. For more information, see "[Checks](/v3/checks/)."
|
||||
If you have a check and a status with the same name and you select that name as a required status check, both the check and the status are required. For more information, see "[Checks](/rest/reference/checks)."
|
||||
|
||||
Once you've set up required status checks, your branch must be up to date with the base branch before merging. This ensures that your branch has been tested with the latest code from the base branch. If your branch is out of date, you'll need to merge the base branch into your branch.
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ remote: error: Required status check "ci-build" is failing
|
|||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion == "github-ae@latest" or currentVersion ver_gt "enterprise-server@2.20" %}
|
||||
|
||||
Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, it must pass. Otherwise, the status of the head commit must pass before you can merge the branch. For more information about test merge commits, see "[Pull Requests](/v3/pulls/#response-1)."
|
||||
Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, it must pass. Otherwise, the status of the head commit must pass before you can merge the branch. For more information about test merge commits, see "[Pull Requests](/rest/reference/pulls#response-1)."
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
|
|
|||
|
|
@ -15,11 +15,14 @@ versions:
|
|||
github-ae: '*'
|
||||
---
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion ver_gt "github-ae@latest" %}
|
||||
|
||||
### About release management
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
You can also publish an action from a specific release in {% data variables.product.prodname_marketplace %}. For more information, see "<a href="/actions/creating-actions/publishing-actions-in-github-marketplace" class="dotcom-only">Publishing an action in the {% data variables.product.prodname_marketplace %}</a>."
|
||||
{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
|
||||
You can choose whether {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in the ZIP files and tarballs that {% data variables.product.product_name %} creates for each release. For more information, see "[Managing {% data variables.large_files.product_name_short %} objects in archives of your repository](/github/administering-a-repository/managing-git-lfs-objects-in-archives-of-your-repository)."
|
||||
{% endif %}
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ redirect_from:
|
|||
versions:
|
||||
free-pro-team: '*'
|
||||
---
|
||||
You can retrieve a list of {% data variables.product.prodname_dotcom %}'s IP addresses from the [meta](https://api.github.com/meta) API endpoint. For more information, see "[Meta](/v3/meta/)."
|
||||
You can retrieve a list of {% data variables.product.prodname_dotcom %}'s IP addresses from the [meta](https://api.github.com/meta) API endpoint. For more information, see "[Meta](/rest/reference/meta)."
|
||||
|
||||
These ranges are in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). You can use an online conversion tool such as this [CIDR / VLSM Supernet Calculator](http://www.subnet-calculator.com/cidr.php) to convert from CIDR notation to IP address ranges.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ versions:
|
|||
github-ae: '*'
|
||||
---
|
||||
|
||||
Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/v3/auth/#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line).
|
||||
Personal access tokens (PATs) are an alternative to using passwords for authentication to {% data variables.product.product_name %} when using the [GitHub API](/rest/overview/other-authentication-methods#via-oauth-and-personal-access-tokens) or the [command line](#using-a-token-on-the-command-line).
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}If you want to use a PAT to access resources owned by an organization that uses SAML SSO, you must authorize the PAT. For more information, see "[About authentication with SAML single sign-on](/articles/about-authentication-with-saml-single-sign-on)" and "[Authorizing a personal access token for use with SAML single sign-on](/articles/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."{% endif %}
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ There are two types of status checks on {% data variables.product.product_name %
|
|||
|
||||
_Checks_ are different from _statuses_ in that they provide line annotations, more detailed messaging, and are only available for use with {% data variables.product.prodname_github_app %}s.
|
||||
|
||||
Organization owners and users with push access to a repository can create checks and statuses with {% data variables.product.product_name %}'s API. For more information, see "[Checks](/v3/checks/)" and "[Statuses](/v3/repos/statuses/)."
|
||||
Organization owners and users with push access to a repository can create checks and statuses with {% data variables.product.product_name %}'s API. For more information, see "[Checks](/rest/reference/checks)" and "[Statuses](/rest/reference/repos#statuses)."
|
||||
|
||||
### Checks
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ versions:
|
|||
---
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
|
||||
To download an archive of your repository, you can use the API for user or organization migrations. For more information, see "[Migrations](/v3/migrations/)."
|
||||
To download an archive of your repository, you can use the API for user or organization migrations. For more information, see "[Migrations](/rest/reference/migrations)."
|
||||
{% else %}
|
||||
|
||||
You can download and back up your repositories manually:
|
||||
|
|
@ -20,15 +20,15 @@ You can download and back up your repositories manually:
|
|||
|
||||
When you clone a repository or wiki, only Git data, such as project files and commit history, is downloaded. You can use our API to export other elements of your {% data variables.product.product_name %} repository to your local machine:
|
||||
|
||||
- [Issues](/v3/issues/#list-issues-for-a-repository)
|
||||
- [Pull requests](/v3/pulls/#list-pull-requests)
|
||||
- [Issues](/rest/reference/issues#list-issues-for-a-repository)
|
||||
- [Pull requests](/rest/reference/pulls#list-pull-requests)
|
||||
- [Forks](/rest/reference/repos#list-forks)
|
||||
- [Comments](/rest/reference/issues#list-issue-comments-for-a-repository)
|
||||
- [Milestones](/rest/reference/issues#list-milestones)
|
||||
- [Labels](/rest/reference/issues#list-labels-for-a-repository)
|
||||
- [Watchers](/rest/reference/activity#list-watchers)
|
||||
- [Stargazers](/rest/reference/activity#list-stargazers)
|
||||
- [Projects](/v3/projects/#list-repository-projects)
|
||||
- [Projects](/rest/reference/projects#list-repository-projects)
|
||||
{% endif %}
|
||||
|
||||
Once you have {% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}a local version of all the content you want to back up, you can create a zip archive and {% else %}downloaded your archive, you can {% endif %}copy it to an external hard drive and/or upload it to a cloud-based backup service such as [Google Drive](https://www.google.com/drive/) or [Dropbox](https://www.dropbox.com/).
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ When you search by a family license, your results will include all licenses in t
|
|||
|
||||
### Detecting a license
|
||||
|
||||
[The open source Ruby gem Licensee](https://github.com/benbalter/licensee) compares the repository's *LICENSE* file to a short list of known licenses. Licensee also provides the [Licenses API](/v3/licenses/) and [gives us insight into how repositories on {% data variables.product.product_name %} are licensed](https://github.com/blog/1964-open-source-license-usage-on-github-com). If your repository is using a license that isn't listed on the [Choose a License website](http://choosealicense.com/appendix/), you can [request including the license](https://github.com/github/choosealicense.com/blob/gh-pages/CONTRIBUTING.md#adding-a-license).
|
||||
[The open source Ruby gem Licensee](https://github.com/benbalter/licensee) compares the repository's *LICENSE* file to a short list of known licenses. Licensee also provides the [Licenses API](/rest/reference/licenses) and [gives us insight into how repositories on {% data variables.product.product_name %} are licensed](https://github.com/blog/1964-open-source-license-usage-on-github-com). If your repository is using a license that isn't listed on the [Choose a License website](http://choosealicense.com/appendix/), you can [request including the license](https://github.com/github/choosealicense.com/blob/gh-pages/CONTRIBUTING.md#adding-a-license).
|
||||
|
||||
If your repository is using a license that is listed on the Choose a License website and it's not displaying clearly at the top of the repository page, it may contain multiple licenses or other complexity. To have your license detected, simplify your *LICENSE* file and note the complexity somewhere else, such as your repository's *README* file.
|
||||
|
||||
|
|
|
|||
|
|
@ -43,4 +43,4 @@ To avoid these prompts, you can use Git password caching. For information, see "
|
|||
|
||||
### Further reading
|
||||
|
||||
- "[Authorizing OAuth Apps](/v3/oauth/)"
|
||||
- "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps)"
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ You can use {% data variables.product.prodname_code_scanning %} to find, triage,
|
|||
If {% data variables.product.prodname_code_scanning %} finds a potential vulnerability or error in your code, {% data variables.product.prodname_dotcom %} displays an alert in the repository. After you fix the code that triggered the alert, {% data variables.product.prodname_dotcom %} closes the alert. For more information, see "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository)."
|
||||
|
||||
To monitor results from {% data variables.product.prodname_code_scanning %} across your repositories or your organization, you can use the {% data variables.product.prodname_code_scanning %} API.
|
||||
For more information about API endpoints, see "[{% data variables.product.prodname_code_scanning_capc %}](/v3/code-scanning)."
|
||||
For more information about API endpoints, see "[{% data variables.product.prodname_code_scanning_capc %}](/rest/reference/code-scanning)."
|
||||
|
||||
To get started with {% data variables.product.prodname_code_scanning %}, see "[Enabling {% data variables.product.prodname_code_scanning %} for a repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository)."
|
||||
|
||||
|
|
|
|||
|
|
@ -167,7 +167,7 @@ You can use the `project` qualifier to find issues that are associated with a sp
|
|||
|
||||
### Search by commit status
|
||||
|
||||
You can filter pull requests based on the status of the commits. This is especially useful if you are using [the Status API](/v3/repos/statuses/) or a CI service.
|
||||
You can filter pull requests based on the status of the commits. This is especially useful if you are using [the Status API](/rest/reference/repos#statuses) or a CI service.
|
||||
|
||||
| Qualifier | Example
|
||||
| ------------- | -------------
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ Some IdPs support provisioning access to a {% data variables.product.prodname_d
|
|||
|
||||
### Adding members to an organization using SAML SSO
|
||||
|
||||
After you enable SAML SSO, there are multiple ways you can add new members to your organization. Organization owners can invite new members manually on {% data variables.product.product_name %} or using the API. For more information, see "[Inviting users to join your organization](/articles/inviting-users-to-join-your-organization)" and "[Members](/v3/orgs/members/#add-or-update-organization-membership)."
|
||||
After you enable SAML SSO, there are multiple ways you can add new members to your organization. Organization owners can invite new members manually on {% data variables.product.product_name %} or using the API. For more information, see "[Inviting users to join your organization](/articles/inviting-users-to-join-your-organization)" and "[Members](/rest/reference/orgs#add-or-update-organization-membership)."
|
||||
|
||||
{% data reusables.organizations.team-synchronization %}
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ If you use [SAML SSO](/articles/about-identity-and-access-management-with-saml-s
|
|||
|
||||
If you use SAML SSO without implementing SCIM, you won't have automatic deprovisioning. When organization members' sessions expire after their access is removed from the IdP, they aren't automatically removed from the organization. Authorized tokens grant access to the organization even after their sessions expire. To remove access, organization administrators can either manually remove the authorized token from the organization or automate its removal with SCIM.
|
||||
|
||||
These identity providers are compatible with the {% data variables.product.product_name %} SCIM API for organizations. For more information, see [SCIM](/v3/scim/) in the {% data variables.product.product_name %} API documentation.
|
||||
These identity providers are compatible with the {% data variables.product.product_name %} SCIM API for organizations. For more information, see [SCIM](/rest/reference/scim) in the {% data variables.product.product_name %} API documentation.
|
||||
- Azure AD
|
||||
- Okta
|
||||
- OneLogin
|
||||
|
|
|
|||
|
|
@ -428,9 +428,9 @@ For more information, see "[Restricting publication of {% data variables.product
|
|||
| Action | Description
|
||||
|------------------|-------------------
|
||||
| `close` | Triggered when someone closes a security advisory. For more information, see "[About {% data variables.product.prodname_dotcom %} Security Advisories](/github/managing-security-vulnerabilities/about-github-security-advisories)."
|
||||
| `cve_request` | Triggered when someone requests a CVE (Common Vulnerabilities and Exposures) number from {% data.variables.product.prodname_dotcom %} for a draft security advisory.
|
||||
| `github_broadcast` | Triggered when {% data.variables.product.prodname_dotcom %} makes a security advisory public in the {% data variables.product.prodname_advisory_database %}.
|
||||
| `github_withdraw` | Triggered when {% data.variables.product.prodname_dotcom %} withdraws a security advisory that was published in error.
|
||||
| `cve_request` | Triggered when someone requests a CVE (Common Vulnerabilities and Exposures) number from {% data variables.product.prodname_dotcom %} for a draft security advisory.
|
||||
| `github_broadcast` | Triggered when {% data variables.product.prodname_dotcom %} makes a security advisory public in the {% data variables.product.prodname_advisory_database %}.
|
||||
| `github_withdraw` | Triggered when {% data variables.product.prodname_dotcom %} withdraws a security advisory that was published in error.
|
||||
| `open` | Triggered when someone opens a draft security advisory.
|
||||
| `publish` | Triggered when someone publishes a security advisory.
|
||||
| `reopen` | Triggered when someone reopens as draft security advisory.
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ Parent teams cannot synchronize with IdP groups. If the team you want to connect
|
|||
|
||||
To manage repository access for any {% data variables.product.prodname_dotcom %} team, including teams connected to an IdP group, you must make changes with {% data variables.product.product_name %}. For more information, see "[About teams](/articles/about-teams)" and "[Managing team access to an organization repository](/articles/managing-team-access-to-an-organization-repository)."
|
||||
|
||||
You can also manage team synchronization with the API. For more information, see "[Team synchronization](/v3/teams/team_sync/)."
|
||||
You can also manage team synchronization with the API. For more information, see "[Team synchronization](/rest/reference/teams#team-sync)."
|
||||
|
||||
### Requirements for members of synchronized teams
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ For more information about the differences between {% data variables.product.pro
|
|||
|
||||
For more information about member access and management, see "{% if currentVersion == "free-pro-team@latest" %}[Managing users in your enterprise](/github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise){% elsif currentVersion == "enterprise-ae@latest" or enterpriseServerVersions contains currentVersion %}[Managing users, organizations, and repositories](/admin/user-management){% endif %}."
|
||||
|
||||
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)."
|
||||
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/graphql/guides/managing-enterprise-accounts)."
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ versions:
|
|||
{% data reusables.user_settings.access_settings %}
|
||||
{% data reusables.user_settings.developer_settings %}
|
||||
3. In the left sidebar, click **{% data variables.product.prodname_oauth_app %}s**.
|
||||
|
||||
|
||||
3. Click **Register a new application**.
|
||||
4. Under **Application name**, type "Jira".
|
||||
5. Under **Homepage URL**, type the full URL to your Jira instance.
|
||||
|
|
|
|||
|
|
@ -201,7 +201,7 @@ Please contact the Account owners for more information about how they might proc
|
|||
|
||||
#### Third party applications
|
||||
|
||||
You have the option of enabling or adding third-party applications, known as "Developer Products," to your Account. These Developer Products are not necessary for your use of GitHub. We will share your User Personal Information with third parties when you ask us to, such as by purchasing a Developer Product from the Marketplace; however, you are responsible for your use of the third-party Developer Product and for the amount of User Personal Information you choose to share with it. You can check our [API documentation](/v3/users/) to see what information is provided when you authenticate into a Developer Product using your GitHub profile.
|
||||
You have the option of enabling or adding third-party applications, known as "Developer Products," to your Account. These Developer Products are not necessary for your use of GitHub. We will share your User Personal Information with third parties when you ask us to, such as by purchasing a Developer Product from the Marketplace; however, you are responsible for your use of the third-party Developer Product and for the amount of User Personal Information you choose to share with it. You can check our [API documentation](/rest/reference/users) to see what information is provided when you authenticate into a Developer Product using your GitHub profile.
|
||||
|
||||
#### GitHub Pages
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ With respect to their personal information, California residents may exercise th
|
|||
|
||||
California residents have the right to request from a business disclosure of the categories and specific pieces of personal information it has collected from them in the preceding 12 months, the categories of sources from which such personal information is collected, the business or commercial purpose for collecting or selling such personal information, and the categories of third parties with whom the business shares personal information.
|
||||
|
||||
If you request that a business disclose categories and specific pieces of personal information collected about you, you have the right to receive that information, free of charge, twice a year. The information may be delivered by mail or electronically and, if provided electronically, shall be in a portable and, to the extent technically feasible, readily usable format that allows the California resident to relatively easily transmit this information to another entity. You can use GitHub’s [User Migration API](/v3/migrations/users/) to access and download your data. Learn more [here](https://github.blog/2018-12-19-download-your-data/).
|
||||
If you request that a business disclose categories and specific pieces of personal information collected about you, you have the right to receive that information, free of charge, twice a year. The information may be delivered by mail or electronically and, if provided electronically, shall be in a portable and, to the extent technically feasible, readily usable format that allows the California resident to relatively easily transmit this information to another entity. You can use GitHub’s [User Migration API](/rest/reference/migrations#users) to access and download your data. Learn more [here](https://github.blog/2018-12-19-download-your-data/).
|
||||
|
||||
### 2. Right to know whether your personal information is sold or disclosed for a business purpose and to whom
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ versions:
|
|||
|
||||
{% data variables.product.product_name %} stores repository and profile metadata from your personal account's activity. You can export your personal account's data through settings on {% data variables.product.prodname_dotcom_the_website %} or with the User Migration API.
|
||||
|
||||
For more information about the data {% data variables.product.product_name %} stores that is available for exporting, see "[Download a user migration archive](/v3/migrations/users/#download-a-user-migration-archive)" and "[About {% data variables.product.product_name %}'s use of your data](/articles/about-github-s-use-of-your-data).
|
||||
For more information about the data {% data variables.product.product_name %} stores that is available for exporting, see "[Download a user migration archive](/rest/reference/migrations#download-a-user-migration-archive)" and "[About {% data variables.product.product_name %}'s use of your data](/articles/about-github-s-use-of-your-data).
|
||||
|
||||
When you request an export of your personal data through settings on {% data variables.product.prodname_dotcom_the_website %}, {% data variables.product.product_name %} packages your personal data in a `tar.gz` file and sends you an email to your primary email address with a download link.
|
||||
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ When you `git clone`, `git fetch`, `git pull`, or `git push` to a remote reposit
|
|||
|
||||
{% tip %}
|
||||
|
||||
**Tip**: You can use an SSH URL to clone a repository to your computer, or as a secure way of deploying your code to production servers. You can also use SSH agent forwarding with your deploy script to avoid managing keys on the server. For more information, see "[Using SSH Agent Forwarding](/v3/guides/using-ssh-agent-forwarding/)."
|
||||
**Tip**: You can use an SSH URL to clone a repository to your computer, or as a secure way of deploying your code to production servers. You can also use SSH agent forwarding with your deploy script to avoid managing keys on the server. For more information, see "[Using SSH Agent Forwarding](/developers/overview/using-ssh-agent-forwarding)."
|
||||
|
||||
{% endtip %}
|
||||
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ If you don't appear in a repository's contributors graph, it may be because:
|
|||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** To list all commit contributors in a repository, see "[Repositories](/v3/repos/#list-contributors)."
|
||||
**Tip:** To list all commit contributors in a repository, see "[Repositories](/rest/reference/repos#list-contributors)."
|
||||
|
||||
{% endtip %}
|
||||
|
||||
|
|
|
|||
|
|
@ -146,4 +146,4 @@ While you can't specify custom MIME types on a per-file or per-repository basis,
|
|||
### Further reading
|
||||
|
||||
- [{% data variables.product.prodname_pages %}](https://lab.github.com/githubtraining/github-pages) on {% data variables.product.prodname_learning %}
|
||||
- "[{% data variables.product.prodname_pages %}](/v3/repos/pages)"
|
||||
- "[{% data variables.product.prodname_pages %}](/rest/reference/repos#pages)"
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ versions:
|
|||
|
||||
Sometimes, {% data variables.product.prodname_pages %} will not attempt to build your site after you push changes to your site's publishing source.{% if currentVersion == "free-pro-team@latest" %}
|
||||
- The person who pushed the changes hasn't verified their email address. For more information, see "[Verifying your email address](/articles/verifying-your-email-address)."{% endif %}
|
||||
- You're pushing with a deploy key. If you want to automate pushes to your site's repository, you can set up a machine user instead. For more information, see "[Managing deploy keys](/v3/guides/managing-deploy-keys/#machine-users)."
|
||||
- You're pushing with a deploy key. If you want to automate pushes to your site's repository, you can set up a machine user instead. For more information, see "[Managing deploy keys](/developers/overview/managing-deploy-keys#machine-users)."
|
||||
- You're using a CI service that isn't configured to build your publishing source. For example, Travis CI won't build the `gh-pages` branch unless you add the branch to a safelist. For more information, see "[Customizing the build](https://docs.travis-ci.com/user/customizing-the-build/#safelisting-or-blocklisting-branches)" on Travis CI, or your CI service's documentation.
|
||||
|
||||
{% note %}
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Follow the steps in "[Creating a personal access token](/github/authenticating-t
|
|||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
|
||||
To match the behavior of the [GraphQL Explorer](/v4/guides/using-the-explorer), request the following scopes:
|
||||
To match the behavior of the [GraphQL Explorer](/graphql/guides/using-the-explorer), request the following scopes:
|
||||
|
||||
{% else %}
|
||||
|
||||
|
|
@ -50,9 +50,9 @@ The endpoint remains constant no matter what operation you perform.
|
|||
|
||||
### Communicating with GraphQL
|
||||
|
||||
Because GraphQL operations consist of multiline JSON, GitHub recommends using the [Explorer](/v4/guides/using-the-explorer) to make GraphQL calls. You can also use cURL or any other HTTP-speaking library.
|
||||
Because GraphQL operations consist of multiline JSON, GitHub recommends using the [Explorer](/graphql/guides/using-the-explorer) to make GraphQL calls. You can also use cURL or any other HTTP-speaking library.
|
||||
|
||||
In REST, [HTTP verbs](/v3/#http-verbs) determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`. The exception is an [introspection query](/v4/guides/intro-to-graphql#discovering-the-graphql-api), which is a simple `GET` to the endpoint. For more information on GraphQL versus REST, see "[Migrating from REST to GraphQL](/v4/guides/migrating-from-rest)."
|
||||
In REST, [HTTP verbs](/rest#http-verbs) determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`. The exception is an [introspection query](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), which is a simple `GET` to the endpoint. For more information on GraphQL versus REST, see "[Migrating from REST to GraphQL](/graphql/guides/migrating-from-rest-to-graphql)."
|
||||
|
||||
To query GraphQL using cURL, make a `POST` request with a JSON payload. The payload must contain a string called `query`:
|
||||
|
||||
|
|
@ -72,15 +72,15 @@ curl -H "Authorization: bearer <em>token</em>" -X POST -d " \
|
|||
|
||||
#### About query and mutation operations
|
||||
|
||||
The two types of allowed operations in GitHub's GraphQL API are _queries_ and _mutations_. Comparing GraphQL to REST, queries operate like `GET` requests, while mutations operate like `POST`/`PATCH`/`DELETE`. The [mutation name](/v4/mutation/) determines which modification is executed.
|
||||
The two types of allowed operations in GitHub's GraphQL API are _queries_ and _mutations_. Comparing GraphQL to REST, queries operate like `GET` requests, while mutations operate like `POST`/`PATCH`/`DELETE`. The [mutation name](/graphql/reference/mutations) determines which modification is executed.
|
||||
|
||||
For information about rate limiting, see "[GraphQL resource limitations](/v4/guides/resource-limitations/)."
|
||||
For information about rate limiting, see "[GraphQL resource limitations](/graphql/overview/resource-limitations)."
|
||||
|
||||
Queries and mutations share similar forms, with some important differences.
|
||||
|
||||
#### About queries
|
||||
|
||||
GraphQL queries return only the data you specify. To form a query, you must specify [fields within fields](/v4/guides/intro-to-graphql#field) (also known as _nested subfields_) until you return only [scalars](/v4/scalar/).
|
||||
GraphQL queries return only the data you specify. To form a query, you must specify [fields within fields](/graphql/guides/introduction-to-graphql#field) (also known as _nested subfields_) until you return only [scalars](/graphql/reference/scalars).
|
||||
|
||||
Queries are structured like this:
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ Mutations are structured like this:
|
|||
|
||||
The input object in this example is `MutationNameInput`, and the payload object is `MutationNamePayload`.
|
||||
|
||||
In the [mutations](/v4/mutation/) reference, the listed _input fields_ are what you pass as the input object. The listed _return fields_ are what you pass as the payload object.
|
||||
In the [mutations](/graphql/reference/mutations) reference, the listed _input fields_ are what you pass as the input object. The listed _return fields_ are what you pass as the payload object.
|
||||
|
||||
For a real-world example, see "[Example mutation](#example-mutation)."
|
||||
|
||||
|
|
@ -117,7 +117,7 @@ For a real-world example, see "[Example mutation](#example-mutation)."
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note**: If you're using the Explorer, make sure to enter variables in the separate [Query Variables pane](/v4/guides/using-the-explorer/#using-the-variable-pane), and do not include the word `variables` before the JSON object.
|
||||
**Note**: If you're using the Explorer, make sure to enter variables in the separate [Query Variables pane](/graphql/guides/using-the-explorer#using-the-variable-pane), and do not include the word `variables` before the JSON object.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -207,7 +207,7 @@ Looking at the composition line by line:
|
|||
|
||||
* `repository(owner:"octocat", name:"Hello-World") {`
|
||||
|
||||
To begin the query, we want to find a [`repository`](/v4/object/repository/) object. The schema validation indicates this object requires an `owner` and a `name` argument.
|
||||
To begin the query, we want to find a [`repository`](/graphql/reference/objects#repository) object. The schema validation indicates this object requires an `owner` and a `name` argument.
|
||||
|
||||
* `issues(last:20, states:CLOSED) {`
|
||||
|
||||
|
|
@ -215,9 +215,9 @@ Looking at the composition line by line:
|
|||
|
||||
Some details about the `issues` object:
|
||||
|
||||
- The [docs](/v4/object/repository/) tell us this object has the type `IssueConnection`.
|
||||
- The [docs](/graphql/reference/objects#repository) tell us this object has the type `IssueConnection`.
|
||||
- Schema validation indicates this object requires a `last` or `first` number of results as an argument, so we provide `20`.
|
||||
- The [docs](/v4/object/repository/) also tell us this object accepts a `states` argument, which is an [`IssueState`](/v4/enum/issuestate/) enum that accepts `OPEN` or `CLOSED` values. To find only closed issues, we give the `states` key a value of `CLOSED`.
|
||||
- The [docs](/graphql/reference/objects#repository) also tell us this object accepts a `states` argument, which is an [`IssueState`](/graphql/reference/enums#issuestate) enum that accepts `OPEN` or `CLOSED` values. To find only closed issues, we give the `states` key a value of `CLOSED`.
|
||||
|
||||
* `edges {`
|
||||
|
||||
|
|
@ -225,9 +225,9 @@ Looking at the composition line by line:
|
|||
|
||||
* `node {`
|
||||
|
||||
Here we retrieve the node at the end of the edge. The [`IssueConnection` docs](/v4/object/issueconnection) indicate the node at the end of the `IssueConnection` type is an `Issue` object.
|
||||
Here we retrieve the node at the end of the edge. The [`IssueConnection` docs](/graphql/reference/objects#issueconnection) indicate the node at the end of the `IssueConnection` type is an `Issue` object.
|
||||
|
||||
* Now that we know we're retrieving an `Issue` object, we can look at the [docs](/v4/object/issue) and specify the fields we want to return:
|
||||
* Now that we know we're retrieving an `Issue` object, we can look at the [docs](/graphql/reference/objects#issue) and specify the fields we want to return:
|
||||
|
||||
```graphql
|
||||
title
|
||||
|
|
@ -243,7 +243,7 @@ Looking at the composition line by line:
|
|||
|
||||
Here we specify the `title`, `url`, and `labels` fields of the `Issue` object.
|
||||
|
||||
The `labels` field has the type [`LabelConnection`](/v4/object/labelconnection/). As with the `issues` object, because `labels` is a connection, we must travel its edges to a connected node: the `label` object. At the node, we can specify the `label` object fields we want to return, in this case, `name`.
|
||||
The `labels` field has the type [`LabelConnection`](/graphql/reference/objects#labelconnection). As with the `issues` object, because `labels` is a connection, we must travel its edges to a connected node: the `label` object. At the node, we can specify the `label` object fields we want to return, in this case, `name`.
|
||||
|
||||
You may notice that running this query on the Octocat's public `Hello-World` repository won't return many labels. Try running it on one of your own repositories that does use labels, and you'll likely see a difference.
|
||||
|
||||
|
|
@ -285,7 +285,7 @@ Let's walk through the example. The task sounds simple: add an emoji reaction to
|
|||
|
||||
So how do we know to begin with a query? We don't, yet.
|
||||
|
||||
Because we want to modify data on the server (attach an emoji to an issue), we begin by searching the schema for a helpful mutation. The reference docs show the [`addReaction`](/v4/mutation/addreaction) mutation, with this description: `Adds a reaction to a subject.` Perfect!
|
||||
Because we want to modify data on the server (attach an emoji to an issue), we begin by searching the schema for a helpful mutation. The reference docs show the [`addReaction`](/graphql/reference/mutations#addreaction) mutation, with this description: `Adds a reaction to a subject.` Perfect!
|
||||
|
||||
The docs for the mutation list three input fields:
|
||||
|
||||
|
|
@ -337,13 +337,13 @@ With the ID known, we can proceed with the mutation:
|
|||
|
||||
- `addReaction` is the name of the mutation.
|
||||
- `input` is the required argument key. This will always be `input` for a mutation.
|
||||
- `{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}` is the required argument value. This will always be an [input object](/v4/input_object/) (hence the curly braces) composed of input fields (`subjectId` and `content` in this case) for a mutation.
|
||||
- `{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}` is the required argument value. This will always be an [input object](/graphql/reference/input-objects) (hence the curly braces) composed of input fields (`subjectId` and `content` in this case) for a mutation.
|
||||
|
||||
How do we know which value to use for the content? The [`addReaction` docs](/v4/mutation/addreaction/) tell us the `content` field has the type [`ReactionContent`](/v4/enum/reactioncontent/), which is an [enum](/v4/enum) because only certain emoji reactions are supported on GitHub issues. These are the allowed values for reactions (note some values differ from their corresponding emoji names):
|
||||
How do we know which value to use for the content? The [`addReaction` docs](/graphql/reference/mutations#addreaction) tell us the `content` field has the type [`ReactionContent`](/graphql/reference/enums#reactioncontent), which is an [enum](/graphql/reference/enums) because only certain emoji reactions are supported on GitHub issues. These are the allowed values for reactions (note some values differ from their corresponding emoji names):
|
||||
|
||||
{% data reusables.repositories.reaction_list %}
|
||||
|
||||
* The rest of the call is composed of the payload object. This is where we specify the data we want the server to return after we've performed the mutation. These lines come from the [`addReaction` docs](/v4/mutation/addreaction), which three possible return fields:
|
||||
* The rest of the call is composed of the payload object. This is where we specify the data we want the server to return after we've performed the mutation. These lines come from the [`addReaction` docs](/graphql/reference/mutations#addreaction), which three possible return fields:
|
||||
|
||||
- `clientMutationId` (`String`)
|
||||
- `reaction` (`Reaction!`)
|
||||
|
|
@ -394,7 +394,7 @@ variables {
|
|||
{% note %}
|
||||
|
||||
You may notice that the `content` field value in the earlier example (where it's used directly in the mutation) does not have quotes around `HOORAY`, but it does have quotes when used in the variable. There's a reason for this:
|
||||
* When you use `content` directly in the mutation, the schema expects the value to be of type [`ReactionContent`](/v4/enum/reactioncontent/), which is an _enum_, not a string. Schema validation will throw an error if you add quotes around the enum value, as quotes are reserved for strings.
|
||||
* When you use `content` directly in the mutation, the schema expects the value to be of type [`ReactionContent`](/graphql/reference/enums#reactioncontent), which is an _enum_, not a string. Schema validation will throw an error if you add quotes around the enum value, as quotes are reserved for strings.
|
||||
* When you use `content` in a variable, the variables section must be valid JSON, so the quotes are required. Schema validation correctly interprets the `ReactionContent` type when the variable is passed into the mutation during execution.
|
||||
|
||||
For more information on the difference between enums and strings, see the [official GraphQL spec](https://graphql.github.io/graphql-spec/June2018/#sec-Enums).
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ versions:
|
|||
|
||||
### GraphQL terminology
|
||||
|
||||
The GitHub GraphQL API represents an architectural and conceptual shift from the GitHub REST API. You will likely encounter some new terminology in the GraphQL API [reference docs](/v4/).
|
||||
The GitHub GraphQL API represents an architectural and conceptual shift from the GitHub REST API. You will likely encounter some new terminology in the GraphQL API [reference docs](/graphql).
|
||||
|
||||
### Schema
|
||||
|
||||
|
|
@ -31,11 +31,11 @@ This means that if you try to return a field that is not a scalar, schema valida
|
|||
|
||||
### Argument
|
||||
|
||||
An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. [Mutations](/v4/guides/forming-calls#about-mutations) require an input object as an argument.
|
||||
An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. [Mutations](/graphql/guides/forming-calls-with-graphql#about-mutations) require an input object as an argument.
|
||||
|
||||
### Implementation
|
||||
|
||||
A GraphQL schema may use the term _implements_ to define how an object inherits from an [interface](/v4/interface).
|
||||
A GraphQL schema may use the term _implements_ to define how an object inherits from an [interface](/graphql/reference/interfaces).
|
||||
|
||||
Here's a contrived example of a schema that defines interface `X` and object `Y`:
|
||||
|
||||
|
|
@ -56,13 +56,13 @@ This means object `Y` requires the same fields/arguments/return types that inter
|
|||
|
||||
In the reference docs, you'll find that:
|
||||
|
||||
* Each [object](/v4/object) lists the interface(s) _from which it inherits_ under **Implements**.
|
||||
* Each [object](/graphql/reference/objects) lists the interface(s) _from which it inherits_ under **Implements**.
|
||||
|
||||
* Each [interface](/v4/interface) lists the objects _that inherit from it_ under **Implementations**.
|
||||
* Each [interface](/graphql/reference/interfaces) lists the objects _that inherit from it_ under **Implementations**.
|
||||
|
||||
### Connection
|
||||
|
||||
Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API. For more information, see "[Migrating from REST to GraphQL](/v4/guides/migrating-from-rest)."
|
||||
Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API. For more information, see "[Migrating from REST to GraphQL](/graphql/guides/migrating-from-rest-to-graphql)."
|
||||
|
||||
It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ Edges represent connections between nodes. When you query a connection, you trav
|
|||
|
||||
### Node
|
||||
|
||||
_Node_ is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a `node` that does not return a [scalar](/v4/scalar), you must include subfields until all fields return scalars. For information on accessing node IDs via the REST API and using them in GraphQL queries, see "[Using Global Node IDs](/v4/guides/using-global-node-ids)."
|
||||
_Node_ is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a `node` that does not return a [scalar](/graphql/reference/scalars), you must include subfields until all fields return scalars. For information on accessing node IDs via the REST API and using them in GraphQL queries, see "[Using Global Node IDs](/graphql/guides/using-global-node-ids)."
|
||||
|
||||
## Discovering the GraphQL API
|
||||
|
||||
|
|
@ -131,4 +131,4 @@ query {
|
|||
|
||||
{% endnote %}
|
||||
|
||||
For more information about performing queries, see "[Forming calls with GraphQL](/v4/guides/forming-calls)."
|
||||
For more information about performing queries, see "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)."
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ With the Enterprise Accounts API, you can:
|
|||
- Invite administrators to your enterprise account.
|
||||
- Create new organizations in your enterprise account.
|
||||
|
||||
For a list of the fields available with the Enterprise Accounts API, see "[GraphQL fields and types for the Enterprise account API](/v4/guides/managing-enterprise-accounts/#graphql-fields-and-types-for-the-enterprise-accounts-api)."
|
||||
For a list of the fields available with the Enterprise Accounts API, see "[GraphQL fields and types for the Enterprise account API](/graphql/guides/managing-enterprise-accounts#graphql-fields-and-types-for-the-enterprise-accounts-api)."
|
||||
|
||||
### Getting started using GraphQL for enterprise accounts
|
||||
|
||||
|
|
@ -199,13 +199,13 @@ This GraphQL query requests the last 5 log entries for an enterprise organizatio
|
|||
}
|
||||
```
|
||||
|
||||
For more information about getting started with GraphQL, see "[Introduction to GraphQL](/v4/guides/intro-to-graphql/)" and "[Forming Calls with GraphQL](/v4/guides/forming-calls/)."
|
||||
For more information about getting started with GraphQL, see "[Introduction to GraphQL](/graphql/guides/introduction-to-graphql)" and "[Forming Calls with GraphQL](/graphql/guides/forming-calls-with-graphql)."
|
||||
|
||||
### GraphQL fields and types for the Enterprise Accounts API
|
||||
|
||||
Here's an overview of the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API.
|
||||
|
||||
For more details about the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API, see the sidebar with detailed GraphQL definitions from any [GraphQL reference page](/v4/).
|
||||
For more details about the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API, see the sidebar with detailed GraphQL definitions from any [GraphQL reference page](/graphql).
|
||||
|
||||
You can access the reference docs from within the GraphQL explorer on GitHub. For more information, see "[Using the explorer](/v4/guides/using-the-explorer#accessing-the-sidebar-docs)."
|
||||
For other information, such as authentication and rate limit details, check out the [guides](/v4/guides).
|
||||
You can access the reference docs from within the GraphQL explorer on GitHub. For more information, see "[Using the explorer](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs)."
|
||||
For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides).
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ versions:
|
|||
|
||||
Migrating from REST to GraphQL represents a significant shift in API logic. The differences between REST as a style and GraphQL as a specification make it difficult—and often undesirable—to replace REST API calls with GraphQL API queries on a one-to-one basis. We've included specific examples of migration below.
|
||||
|
||||
To migrate your code from the [REST API](/v3) to the GraphQL API:
|
||||
To migrate your code from the [REST API](/rest) to the GraphQL API:
|
||||
|
||||
- Review the [GraphQL spec](https://graphql.github.io/graphql-spec/June2018/)
|
||||
- Review GitHub's [GraphQL schema](/v4/reference/)
|
||||
- Review GitHub's [GraphQL schema](/graphql/reference)
|
||||
- Consider how any existing code you have currently interacts with the GitHub REST API
|
||||
- Use [Global Node IDs](/v4/guides/using-global-node-ids) to reference objects between API versions
|
||||
- Use [Global Node IDs](/graphql/guides/using-global-node-ids) to reference objects between API versions
|
||||
|
||||
Significant advantages of GraphQL include:
|
||||
|
||||
|
|
@ -53,12 +53,12 @@ query {
|
|||
}
|
||||
```
|
||||
|
||||
Consider another example: retrieving a list of pull requests and checking if each one is mergeable. A call to the REST API retrieves a list of pull requests and their [summary representations](/v3/#summary-representations):
|
||||
Consider another example: retrieving a list of pull requests and checking if each one is mergeable. A call to the REST API retrieves a list of pull requests and their [summary representations](/rest#summary-representations):
|
||||
```shell
|
||||
curl -v {% data variables.product.api_url_pre %}/repos/:owner/:repo/pulls
|
||||
```
|
||||
|
||||
Determining if a pull request is mergeable requires retrieving each pull request individually for its [detailed representation](/v3/#detailed-representations) (a large payload) and checking whether its `mergeable` attribute is true or false:
|
||||
Determining if a pull request is mergeable requires retrieving each pull request individually for its [detailed representation](/rest#detailed-representations) (a large payload) and checking whether its `mergeable` attribute is true or false:
|
||||
```shell
|
||||
curl -v {% data variables.product.api_url_pre %}/repos/:owner/:repo/pulls/:number
|
||||
```
|
||||
|
|
@ -128,13 +128,13 @@ Using the **GraphQL API**, you can retrieve the data with a single query using n
|
|||
}
|
||||
```
|
||||
|
||||
You can also extend the power of this query by [substituting a variable](/v4/guides/forming-calls/#working-with-variables) for the pull request number.
|
||||
You can also extend the power of this query by [substituting a variable](/graphql/guides/forming-calls-with-graphql#working-with-variables) for the pull request number.
|
||||
|
||||
## Example: Strong typing
|
||||
|
||||
GraphQL schemas are strongly typed, making data handling safer.
|
||||
|
||||
Consider an example of adding a comment to an issue or pull request using a GraphQL [mutation](/v4/mutation), and mistakenly specifying an integer rather than a string for the value of [`clientMutationId`](/v4/mutation/addcomment/):
|
||||
Consider an example of adding a comment to an issue or pull request using a GraphQL [mutation](/graphql/reference/mutations), and mistakenly specifying an integer rather than a string for the value of [`clientMutationId`](/graphql/reference/mutations#addcomment):
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ You can access most objects in GitHub (users, issues, pull requests, etc.) using
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note:** In REST, the global node ID field is named `node_id`. In GraphQL, it's an `id` field on the `node` interface. For a refresher on what "node" means in GraphQL, see "[Introduction to GraphQL](/v4/guides/intro-to-graphql/#node)."
|
||||
**Note:** In REST, the global node ID field is named `node_id`. In GraphQL, it's an `id` field on the `node` interface. For a refresher on what "node" means in GraphQL, see "[Introduction to GraphQL](/graphql/guides/introduction-to-graphql#node)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ Let's walk through an example.
|
|||
|
||||
### 1. Call a REST endpoint that returns an object's node ID
|
||||
|
||||
If you [request the authenticated user](/v3/users/#get-the-authenticated-user):
|
||||
If you [request the authenticated user](/rest/reference/users#get-the-authenticated-user):
|
||||
|
||||
```shell
|
||||
$ curl -i -u <em>username:token</em> {% data variables.product.api_url_pre %}/user
|
||||
|
|
@ -101,7 +101,7 @@ query {
|
|||
|
||||
This type of query—that is, finding the node by ID—is known as a "direct node lookup."
|
||||
|
||||
When you run this query, you'll see that the `__typename` is [`User`](/v4/object/user/).
|
||||
When you run this query, you'll see that the `__typename` is [`User`](/graphql/reference/objects#user).
|
||||
|
||||
### 3. Do a direct node lookup in GraphQL
|
||||
|
||||
|
|
@ -122,4 +122,4 @@ This type of query is the standard approach for looking up an object by its glob
|
|||
|
||||
### Using global node IDs in migrations
|
||||
|
||||
When building integrations that use either the REST API or the GraphQL API, it's best practice to persist the global node ID so you can easily reference objects across API versions. For more information on handling the transition between REST and GraphQL, see "[Migrating from REST to GraphQL](/v4/guides/migrating-from-rest/)."
|
||||
When building integrations that use either the REST API or the GraphQL API, it's best practice to persist the global node ID so you can easily reference objects across API versions. For more information on handling the transition between REST and GraphQL, see "[Migrating from REST to GraphQL](/graphql/guides/migrating-from-rest-to-graphql)."
|
||||
|
|
|
|||
|
|
@ -13,11 +13,11 @@ versions:
|
|||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
|
||||
[GraphQL Explorer](/v4/explorer) is an instance of [GraphiQL](https://github.com/graphql/graphiql), which is a "graphical interactive in-browser GraphQL IDE."
|
||||
[GraphQL Explorer](/graphql/overview/explorer) is an instance of [GraphiQL](https://github.com/graphql/graphiql), which is a "graphical interactive in-browser GraphQL IDE."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data variables.product.prodname_dotcom %} has disabled [mutations](/v4/mutation/) in the Explorer, but you can use them in your own GraphiQL instance.
|
||||
**Note**: {% data variables.product.prodname_dotcom %} has disabled [mutations](/graphql/reference/mutations) in the Explorer, but you can use them in your own GraphiQL instance.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -33,7 +33,7 @@ To use the GraphiQL app, download and install it from https://github.com/skevy/g
|
|||
|
||||
#### Configuring GraphiQL
|
||||
|
||||
1. Get an [OAuth token](/v4/guides/forming-calls#authenticating-with-graphql).
|
||||
1. Get an [OAuth token](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql).
|
||||
1. Launch GraphiQL.
|
||||
1. In the upper-right corner of GraphiQL, click **Edit HTTP Headers**.
|
||||
1. In the **Key** field, enter `Authorization`. In the **Value** field, enter `Bearer <token>`, where `<token>` is your generated OAuth token.
|
||||
|
|
@ -45,7 +45,7 @@ To use the GraphiQL app, download and install it from https://github.com/skevy/g
|
|||
|
||||
{% note %}
|
||||
|
||||
**Note**: For more information about why `POST` is the method, see "[Communicating with GraphQL](/v4/guides/forming-calls#communicating-with-graphql)."
|
||||
**Note**: For more information about why `POST` is the method, see "[Communicating with GraphQL](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
|
@ -67,13 +67,13 @@ All types in a GraphQL schema include a `description` field compiled into docume
|
|||
|
||||
{% note %}
|
||||
|
||||
The **Docs** sidebar contains the same content that is automatically generated from the schema under "[Reference](/v4/)," though it is formatted differently in places.
|
||||
The **Docs** sidebar contains the same content that is automatically generated from the schema under "[Reference](/graphql)," though it is formatted differently in places.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Using the variable pane
|
||||
|
||||
Some example calls include [variables](/v4/guides/forming-calls#working-with-variables) written like this:
|
||||
Some example calls include [variables](/graphql/guides/forming-calls-with-graphql#working-with-variables) written like this:
|
||||
|
||||
```graphql
|
||||
query($number_of_repos:Int!){
|
||||
|
|
@ -91,7 +91,7 @@ variables {
|
|||
}
|
||||
```
|
||||
|
||||
This is the correct format to submit the call via a cURL `POST` (as long as you [escape newlines](/v4/guides/forming-calls#communicating-with-graphql)).
|
||||
This is the correct format to submit the call via a cURL `POST` (as long as you [escape newlines](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)).
|
||||
|
||||
If you want to run the call in the Explorer, enter the `query` segment in the main pane and the variables in the **Query Variables** pane below it. Omit the word `variables` from the Explorer:
|
||||
|
||||
|
|
@ -107,12 +107,12 @@ If you want to run the call in the Explorer, enter the `query` segment in the ma
|
|||
|
||||
### Troubleshooting errors
|
||||
|
||||
Because GraphQL is [introspective](/v4/guides/intro-to-graphql#discovering-the-graphql-api), the Explorer supports:
|
||||
Because GraphQL is [introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), the Explorer supports:
|
||||
|
||||
* Intelligent typeaheads aware of the current schema
|
||||
* Validation error previews as you type
|
||||
|
||||
If you enter a query that is not well-formed or does not pass [schema validation](/v4/guides/intro-to-graphql#schema), a popup warns you of an error. If you run the query, the error returns in the response pane.
|
||||
If you enter a query that is not well-formed or does not pass [schema validation](/graphql/guides/introduction-to-graphql#schema), a popup warns you of an error. If you run the query, the error returns in the response pane.
|
||||
|
||||
A GraphQL response contains several keys: a `data` hash and an `errors` array.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,25 +11,25 @@ versions:
|
|||
|
||||
Here are some quick links to get you up and running with the GraphQL API v4:
|
||||
|
||||
* [Authentication](/v4/guides/forming-calls/#authenticating-with-graphql)
|
||||
* [Root endpoint](/v4/guides/forming-calls/#the-graphql-endpoint)
|
||||
* [Schema introspection](/v4/guides/intro-to-graphql/#discovering-the-graphql-api)
|
||||
* [Rate limits](/v4/guides/resource-limitations/)
|
||||
* [Migrating from REST](/v4/guides/migrating-from-rest)
|
||||
* [Authentication](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql)
|
||||
* [Root endpoint](/graphql/guides/forming-calls-with-graphql#the-graphql-endpoint)
|
||||
* [Schema introspection](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api)
|
||||
* [Rate limits](/graphql/overview/resource-limitations)
|
||||
* [Migrating from REST](/graphql/guides/migrating-from-rest-to-graphql)
|
||||
|
||||
### About GraphQL
|
||||
|
||||
The [GraphQL](https://graphql.github.io/) data query language is:
|
||||
|
||||
* **A [specification](https://graphql.github.io/graphql-spec/June2018/).** The spec determines the validity of the [schema](/v4/guides/intro-to-graphql#schema) on the API server. The schema determines the validity of client calls.
|
||||
* **A [specification](https://graphql.github.io/graphql-spec/June2018/).** The spec determines the validity of the [schema](/graphql/guides/introduction-to-graphql#schema) on the API server. The schema determines the validity of client calls.
|
||||
|
||||
* **[Strongly typed](#about-the-graphql-schema-reference).** The schema defines an API's type system and all object relationships.
|
||||
|
||||
* **[Introspective](/v4/guides/intro-to-graphql#discovering-the-graphql-api).** A client can query the schema for details about the schema.
|
||||
* **[Introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api).** A client can query the schema for details about the schema.
|
||||
|
||||
* **[Hierarchical](/v4/guides/forming-calls).** The shape of a GraphQL call mirrors the shape of the JSON data it returns. [Nested fields](/v4/guides/migrating-from-rest/#example-nesting) let you query for and receive only the data you specify in a single round trip.
|
||||
* **[Hierarchical](/graphql/guides/forming-calls-with-graphql).** The shape of a GraphQL call mirrors the shape of the JSON data it returns. [Nested fields](/graphql/guides/migrating-from-rest-to-graphql#example-nesting) let you query for and receive only the data you specify in a single round trip.
|
||||
|
||||
* **An application layer.** GraphQL is not a storage model or a database query language. The _graph_ refers to graph structures defined in the schema, where [nodes](/v4/guides/intro-to-graphql#node) define objects and [edges](/v4/guides/intro-to-graphql#edge) define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.
|
||||
* **An application layer.** GraphQL is not a storage model or a database query language. The _graph_ refers to graph structures defined in the schema, where [nodes](/graphql/guides/introduction-to-graphql#node) define objects and [edges](/graphql/guides/introduction-to-graphql#edge) define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.
|
||||
|
||||
### Why GitHub is using GraphQL
|
||||
|
||||
|
|
@ -39,15 +39,15 @@ For more details about why GitHub has moved to GraphQL, see the original [announ
|
|||
|
||||
### About the GraphQL schema reference
|
||||
|
||||
The docs in the sidebar are generated from the {% data variables.product.prodname_dotcom %} GraphQL [schema](/v4/guides/intro-to-graphql/#discovering-the-graphql-api). All calls are validated and executed against the schema. Use these docs to find out what data you can call:
|
||||
The docs in the sidebar are generated from the {% data variables.product.prodname_dotcom %} GraphQL [schema](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api). All calls are validated and executed against the schema. Use these docs to find out what data you can call:
|
||||
|
||||
* Allowed operations: [queries](/v4/query) and [mutations](/v4/mutation).
|
||||
* Allowed operations: [queries](/graphql/reference/queries) and [mutations](/graphql/reference/mutations).
|
||||
|
||||
* Schema-defined types: [scalars](/v4/scalar), [objects](/v4/object), [enums](/v4/enum), [interfaces](/v4/interface), [unions](/v4/union), and [input objects](/v4/input_object).
|
||||
* Schema-defined types: [scalars](/graphql/reference/scalars), [objects](/graphql/reference/objects), [enums](/graphql/reference/enums), [interfaces](/graphql/reference/interfaces), [unions](/graphql/reference/unions), and [input objects](/graphql/reference/input-objects).
|
||||
|
||||
You can access this same content via the [Explorer Docs sidebar](/v4/guides/using-the-explorer#accessing-the-sidebar-docs). Note that you may need to rely on both the docs and the schema validation to successfully call the GraphQL API.
|
||||
You can access this same content via the [Explorer Docs sidebar](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs). Note that you may need to rely on both the docs and the schema validation to successfully call the GraphQL API.
|
||||
|
||||
For other information, such as authentication and rate limit details, check out the [guides](/v4/guides).
|
||||
For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides).
|
||||
|
||||
### Requesting support
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Breaking changes are any changes that might require action from our integrators.
|
|||
- **Breaking:** Changes that will break existing queries to the GraphQL API. For example, removing a field would be a breaking change.
|
||||
- **Dangerous:** Changes that won't break existing queries but could affect the runtime behavior of clients. Adding an enum value is an example of a dangerous change.
|
||||
|
||||
We strive to provide stable APIs for our integrators. When a new feature is still evolving, we release it behind a [schema preview](/v4/previews/).
|
||||
We strive to provide stable APIs for our integrators. When a new feature is still evolving, we release it behind a [schema preview](/graphql/overview/schema-previews).
|
||||
|
||||
We'll announce upcoming breaking changes at least three months before making changes to the GraphQL schema, to give integrators time to make the necessary adjustments. Changes go into effect on the first day of a quarter (January 1st, April 1st, July 1st, or October 1st). For example, if we announce a change on January 15th, it will be made on July 1st.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ versions:
|
|||
github-ae: '*'
|
||||
---
|
||||
|
||||
Breaking changes include changes that will break existing queries or could affect the runtime behavior of clients. For a list of breaking changes and when they will occur, see our [breaking changes log](/v4/breaking_changes).
|
||||
Breaking changes include changes that will break existing queries or could affect the runtime behavior of clients. For a list of breaking changes and when they will occur, see our [breaking changes log](/graphql/overview/breaking-changes).
|
||||
|
||||
{% for entry in graphql.changelog %}
|
||||
### Schema Changes for {{ entry.date }}
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ versions:
|
|||
github-ae: '*'
|
||||
---
|
||||
|
||||
You can [perform introspection](/v4/guides/intro-to-graphql/#discovering-the-graphql-api) against the GraphQL API directly.
|
||||
You can [perform introspection](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api) against the GraphQL API directly.
|
||||
|
||||
Alternatively, you can download the latest version of the public schema here:
|
||||
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@ versions:
|
|||
|
||||
## Node limit
|
||||
|
||||
To pass [schema](/v4/guides/intro-to-graphql#schema) validation, all GraphQL API v4 [calls](/v4/guides/forming-calls) must meet these standards:
|
||||
To pass [schema](/graphql/guides/introduction-to-graphql#schema) validation, all GraphQL API v4 [calls](/graphql/guides/forming-calls-with-graphql) must meet these standards:
|
||||
|
||||
* Clients must supply a `first` or `last` argument on any [connection](/v4/guides/intro-to-graphql#connection).
|
||||
* Clients must supply a `first` or `last` argument on any [connection](/graphql/guides/introduction-to-graphql#connection).
|
||||
* Values of `first` and `last` must be within 1-100.
|
||||
* Individual calls cannot request more than 500,000 total [nodes](/v4/guides/intro-to-graphql#node).
|
||||
* Individual calls cannot request more than 500,000 total [nodes](/graphql/guides/introduction-to-graphql#node).
|
||||
|
||||
#### Calculating nodes in a call
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ These two examples show how to calculate the total nodes in a call.
|
|||
|
||||
The GraphQL API v4 limit is different from the REST API v3's [rate limits](/rest/overview/resources-in-the-rest-api#rate-limiting).
|
||||
|
||||
Why are the API rate limits different? With [GraphQL](/v4/), one GraphQL call can replace [multiple REST calls](/v4/guides/migrating-from-rest/). A single complex GraphQL call could be the equivalent of thousands of REST requests. While a single GraphQL call would fall well below the REST API rate limit, the query might be just as expensive for GitHub's servers to compute.
|
||||
Why are the API rate limits different? With [GraphQL](/graphql), one GraphQL call can replace [multiple REST calls](/graphql/guides/migrating-from-rest-to-graphql). A single complex GraphQL call could be the equivalent of thousands of REST requests. While a single GraphQL call would fall well below the REST API rate limit, the query might be just as expensive for GitHub's servers to compute.
|
||||
|
||||
To accurately represent the server cost of a query, the GraphQL API v4 calculates a call's **rate limit score** based on a normalized scale of points. A query's score factors in first and last arguments on a parent connection and its children.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ versions:
|
|||
|
||||
During the preview period, we may change some features based on developer feedback. If we do make changes, we'll announce them on the [developer blog](https://developer.github.com/changes/) without advance notice.
|
||||
|
||||
To access a schema preview, you'll need to provide a custom [media type](/v3/media) in the `Accept` header for your requests. Feature documentation for each preview specifies which custom media type to provide.
|
||||
To access a schema preview, you'll need to provide a custom [media type](/rest/overview/media-types) in the `Accept` header for your requests. Feature documentation for each preview specifies which custom media type to provide.
|
||||
|
||||
{% note %}
|
||||
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ versions:
|
|||
|
||||
[Enums](https://graphql.github.io/graphql-spec/June2018/#sec-Enums) represent possible sets of values for a field.
|
||||
|
||||
For example, the [`Issue`](/v4/object/issue) object has a field called `state`. The state is an enum (specifically, of type [`IssueState`](/v4/enum/issuestate/)) because it may be `OPEN` or `CLOSED`.
|
||||
For example, the [`Issue`](/graphql/reference/objects#issue) object has a field called `state`. The state is an enum (specifically, of type [`IssueState`](/graphql/reference/enums#issuestate)) because it may be `OPEN` or `CLOSED`.
|
||||
|
||||
For more information, see "[Introduction to GraphQL](/v4/guides/intro-to-graphql)."
|
||||
For more information, see "[Introduction to GraphQL](/graphql/guides/introduction-to-graphql)."
|
||||
|
||||
{% for item in graphql.schemaForCurrentVersion.enums %}
|
||||
{% include graphql-enum %}
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ versions:
|
|||
|
||||
[Input objects](https://graphql.github.io/graphql-spec/June2018/#sec-Input-Objects) can be described as "composable objects" because they include a set of input fields that define the object.
|
||||
|
||||
For example, [`CommitAuthor`](/v4/input_object/commitauthor/) takes a field called `emails`. Providing a value for `emails` transforms `CommitAuthor` into a list of `User` objects containing that email address. Note that [objects](/v4/object) **may** have input objects, whereas [mutations](/v4/mutation) **require** input objects.
|
||||
For example, [`CommitAuthor`](/graphql/reference/input-objects#commitauthor) takes a field called `emails`. Providing a value for `emails` transforms `CommitAuthor` into a list of `User` objects containing that email address. Note that [objects](/graphql/reference/objects) **may** have input objects, whereas [mutations](/graphql/reference/mutations) **require** input objects.
|
||||
|
||||
For more information, see "[About mutations](/v4/guides/forming-calls#about-mutations)."
|
||||
For more information, see "[About mutations](/graphql/guides/forming-calls-with-graphql#about-mutations)."
|
||||
|
||||
{% for item in graphql.schemaForCurrentVersion.inputObjects %}
|
||||
{% include graphql-input-object %}
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ versions:
|
|||
|
||||
[Interfaces](https://graphql.github.io/graphql-spec/June2018/#sec-Interfaces) serve as parent objects from which other objects can inherit.
|
||||
|
||||
For example, [`Lockable`](/v4/interface/lockable/) is an interface because both [`Issue`](/v4/object/issue/) and [`PullRequest`](/v4/object/pullrequest/) objects can be locked. An interface has its own list of named fields that are shared by implementing objects.
|
||||
For example, [`Lockable`](/graphql/reference/interfaces#lockable) is an interface because both [`Issue`](/graphql/reference/objects#issue) and [`PullRequest`](/graphql/reference/objects#pullrequest) objects can be locked. An interface has its own list of named fields that are shared by implementing objects.
|
||||
|
||||
For more information, see "[Implementation](/v4/guides/intro-to-graphql#implementation)."
|
||||
For more information, see "[Implementation](/graphql/guides/introduction-to-graphql#implementation)."
|
||||
|
||||
{% for item in graphql.schemaForCurrentVersion.interfaces %}
|
||||
{% include graphql-interface %}
|
||||
|
|
|
|||
Некоторые файлы не были показаны из-за слишком большого количества измененных файлов Показать больше
Загрузка…
Ссылка в новой задаче