break up large rest pages (#23652)
This commit is contained in:
Rachael Sewell
@@ -6,6 +6,7 @@ import { SmallFooter } from 'components/page-footer/SmallFooter'
|
||||
import { ScrollButton } from 'components/ui/ScrollButton'
|
||||
import { SupportSection } from 'components/page-footer/SupportSection'
|
||||
import { DeprecationBanner } from 'components/page-header/DeprecationBanner'
|
||||
import { RestRepoBanner } from 'components/page-header/RestRepoBanner'
|
||||
import { useMainContext } from 'components/context/MainContext'
|
||||
import { useTranslation } from 'components/hooks/useTranslation'
|
||||
import { useRouter } from 'next/router'
|
||||
@@ -86,6 +87,7 @@ export const DefaultLayout = (props: Props) => {
|
||||
<main className="flex-1 min-width-0">
|
||||
<Header />
|
||||
<DeprecationBanner />
|
||||
<RestRepoBanner />
|
||||
|
||||
{props.children}
|
||||
|
||||
|
||||
52
components/page-header/RestRepoBanner.tsx
Normal file
52
components/page-header/RestRepoBanner.tsx
Normal file
@@ -0,0 +1,52 @@
|
||||
import { Flash } from '@primer/components'
|
||||
import { useRouter } from 'next/router'
|
||||
import { Link } from 'components/Link'
|
||||
const restDisplayPages = [
|
||||
'/rest/reference/branches',
|
||||
'/rest/reference/collaborators',
|
||||
'/rest/reference/commits',
|
||||
'/rest/reference/deployments',
|
||||
'/rest/reference/pages',
|
||||
'/rest/reference/repos',
|
||||
'/rest/reference/repository-metrics',
|
||||
'/rest/reference/webhooks',
|
||||
]
|
||||
const restRepoCategoryExceptions = [
|
||||
'Branches',
|
||||
'Collaborators',
|
||||
'Commits',
|
||||
'Deployments',
|
||||
'Github Pages',
|
||||
'Repository metrics',
|
||||
'Webhooks',
|
||||
]
|
||||
|
||||
export const RestRepoBanner = () => {
|
||||
const router = useRouter()
|
||||
const asPathRoot = router.asPath.split('?')[0].split('#')[0]
|
||||
if (!restDisplayPages.includes(asPathRoot)) {
|
||||
return null
|
||||
}
|
||||
|
||||
const newRestPagesText = restRepoCategoryExceptions.map((page, i) => [
|
||||
<Link href={`/rest/references/${page}`}>
|
||||
{page}
|
||||
{i < restRepoCategoryExceptions.length - 1 && ', '}
|
||||
</Link>,
|
||||
])
|
||||
|
||||
return (
|
||||
<div data-testid="rest-api-repos-banner" className="container-xl mt-3 mx-auto p-responsive">
|
||||
<Flash variant="warning">
|
||||
<p>
|
||||
<b className="text-bold">
|
||||
<span>
|
||||
We've recently moved some of the REST API documentation. If you can't find what you're
|
||||
looking for, you might try the new {newRestPagesText} REST API pages.
|
||||
</span>
|
||||
</b>{' '}
|
||||
</p>
|
||||
</Flash>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
@@ -24,6 +24,6 @@ To view current and past deployments, click **Environments** on the home page of
|
||||
|
||||
The deployments page displays the last active deployment of each environment for your repository. If the deployment includes an environment URL, a **View deployment** button that links to the URL is shown next to the deployment.
|
||||
|
||||
The activity log shows the deployment history for your environments. By default, only the most recent deployment for an environment has an `Active` status; all previously active deployments have an `Inactive` status. For more information on automatic inactivation of deployments, see "[Inactive deployments](/rest/reference/repos#inactive-deployments)."
|
||||
The activity log shows the deployment history for your environments. By default, only the most recent deployment for an environment has an `Active` status; all previously active deployments have an `Inactive` status. For more information on automatic inactivation of deployments, see "[Inactive deployments](/rest/reference/deployments#inactive-deployments)."
|
||||
|
||||
You can also use the REST API to get information about deployments. For more information, see "[Repositories](/rest/reference/repos#deployments)."
|
||||
|
||||
@@ -307,7 +307,7 @@ on:
|
||||
|
||||
### `deployment_status`
|
||||
|
||||
Runs your workflow anytime a third party provides a deployment status, which triggers the `deployment_status` event. Deployments created with a commit SHA may not have a Git ref. For information about the REST API, see "[Create a deployment status](/rest/reference/repos#create-a-deployment-status)."
|
||||
Runs your workflow anytime a third party provides a deployment status, which triggers the `deployment_status` event. Deployments created with a commit SHA may not have a Git ref. For information about the REST API, see "[Create a deployment status](/rest/reference/deployments#create-a-deployment-status)."
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| --------------------- | -------------- | ------------ | -------------|
|
||||
@@ -701,7 +701,7 @@ on:
|
||||
|
||||
{% 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 commit](/rest/reference/repos#get-a-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 commit](/rest/reference/commits#get-a-commit)".
|
||||
|
||||
{% endnote %}
|
||||
|
||||
|
||||
@@ -82,14 +82,14 @@ The `$GITHUB_VIA` variable is available in the pre-receive hook environment when
|
||||
|
||||
| Value | Action | More information |
|
||||
| :- | :- | :- |
|
||||
| <pre>auto-merge deployment api</pre> | Automatic merge of the base branch via a deployment created with the API | "[Repositories](/rest/reference/repos#create-a-deployment)" in the REST API documentation |
|
||||
| <pre>auto-merge deployment api</pre> | Automatic merge of the base branch via a deployment created with the API | "[Create a deployment](/rest/reference/deployments#create-a-deployment)" in the REST API documentation |
|
||||
| <pre>blob#save</pre> | Change to a file's contents in the web interface | "[Editing files](/repositories/working-with-files/managing-files/editing-files)" |
|
||||
| <pre>branch merge api</pre> | Merge of a branch via the API | "[Repositories](/rest/reference/repos#merge-a-branch)" in the REST API documentation |
|
||||
| <pre>branch merge api</pre> | Merge of a branch via the API | "[Merge a branch](/rest/reference/branches#merge-a-branch)" in the REST API documentation |
|
||||
| <pre>branches page delete button</pre> | Deletion of a branch in the web interface | "[Creating and deleting branches within your repository](/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch)" |
|
||||
| <pre>git refs create api</pre> | Creation of a ref via the API | "[Git database](/rest/reference/git#create-a-reference)" in the REST API documentation |
|
||||
| <pre>git refs delete api</pre> | Deletion of a ref via the API | "[Git database](/rest/reference/git#delete-a-reference)" in the REST API documentation |
|
||||
| <pre>git refs update api</pre> | Update of a ref via the API | "[Git database](/rest/reference/git#update-a-reference)" in the REST API documentation |
|
||||
| <pre>git repo contents api</pre> | Change to a file's contents via the API | "[Repositories](/rest/reference/repos#create-or-update-file-contents)" in the REST API documentation |
|
||||
| <pre>git repo contents api</pre> | Change to a file's contents via the API | "[Create or update file contents](/rest/reference/repos#create-or-update-file-contents)" in the REST API documentation |
|
||||
| <pre>merge base into head</pre> | Update of the topic branch from the base branch when the base branch requires strict status checks (via **Update branch** in a pull request, for example) | "[About protected branches](/github/administering-a-repository/about-protected-branches#require-status-checks-before-merging)" |
|
||||
| <pre>pull request branch delete button</pre> | Deletion of a topic branch from a pull request in the web interface | "[Deleting and restoring branches in a pull request](/github/administering-a-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request)" |
|
||||
| <pre>pull request branch undo button</pre> | Restoration of a topic branch from a pull request in the web interface | "[Deleting and restoring branches in a pull request](/github/administering-a-repository/deleting-and-restoring-branches-in-a-pull-request#restoring-a-deleted-branch)" |
|
||||
|
||||
@@ -239,16 +239,16 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
|
||||
#### Deployment Statuses
|
||||
|
||||
* [List deployment statuses](/rest/reference/repos#list-deployment-statuses)
|
||||
* [Create a deployment status](/rest/reference/repos#create-a-deployment-status)
|
||||
* [Get a deployment status](/rest/reference/repos#get-a-deployment-status)
|
||||
* [List deployment statuses](/rest/reference/deployments#list-deployment-statuses)
|
||||
* [Create a deployment status](/rest/reference/deployments#create-a-deployment-status)
|
||||
* [Get a deployment status](/rest/reference/deployments#get-a-deployment-status)
|
||||
|
||||
#### Deployments
|
||||
|
||||
* [List deployments](/rest/reference/repos#list-deployments)
|
||||
* [Create a deployment](/rest/reference/repos#create-a-deployment)
|
||||
* [Get a deployment](/rest/reference/repos#get-a-deployment){% ifversion fpt or ghes or ghae or ghec %}
|
||||
* [Delete a deployment](/rest/reference/repos#delete-a-deployment){% endif %}
|
||||
* [List deployments](/rest/reference/deployments#list-deployments)
|
||||
* [Create a deployment](/rest/reference/deployments#create-a-deployment)
|
||||
* [Get a deployment](/rest/reference/deployments#get-a-deployment){% ifversion fpt or ghes or ghae or ghec %}
|
||||
* [Delete a deployment](/rest/reference/deployments#delete-a-deployment){% endif %}
|
||||
|
||||
#### Events
|
||||
|
||||
@@ -609,7 +609,7 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
* [Get a repository](/rest/reference/repos#get-a-repository)
|
||||
* [Update a repository](/rest/reference/repos#update-a-repository)
|
||||
* [Delete a repository](/rest/reference/repos#delete-a-repository)
|
||||
* [Compare two commits](/rest/reference/repos#compare-two-commits)
|
||||
* [Compare two commits](/rest/reference/commits#compare-two-commits)
|
||||
* [List repository contributors](/rest/reference/repos#list-repository-contributors)
|
||||
* [List forks](/rest/reference/repos#list-forks)
|
||||
* [Create a fork](/rest/reference/repos#create-a-fork)
|
||||
@@ -641,68 +641,68 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
|
||||
#### Repository Branches
|
||||
|
||||
* [List branches](/rest/reference/repos#list-branches)
|
||||
* [Get a branch](/rest/reference/repos#get-a-branch)
|
||||
* [Get branch protection](/rest/reference/repos#get-branch-protection)
|
||||
* [Update branch protection](/rest/reference/repos#update-branch-protection)
|
||||
* [Delete branch protection](/rest/reference/repos#delete-branch-protection)
|
||||
* [Get admin branch protection](/rest/reference/repos#get-admin-branch-protection)
|
||||
* [Set admin branch protection](/rest/reference/repos#set-admin-branch-protection)
|
||||
* [Delete admin branch protection](/rest/reference/repos#delete-admin-branch-protection)
|
||||
* [Get pull request review protection](/rest/reference/repos#get-pull-request-review-protection)
|
||||
* [Update pull request review protection](/rest/reference/repos#update-pull-request-review-protection)
|
||||
* [Delete pull request review protection](/rest/reference/repos#delete-pull-request-review-protection)
|
||||
* [Get commit signature protection](/rest/reference/repos#get-commit-signature-protection)
|
||||
* [Create commit signature protection](/rest/reference/repos#create-commit-signature-protection)
|
||||
* [Delete commit signature protection](/rest/reference/repos#delete-commit-signature-protection)
|
||||
* [Get status checks protection](/rest/reference/repos#get-status-checks-protection)
|
||||
* [Update status check protection](/rest/reference/repos#update-status-check-protection)
|
||||
* [Remove status check protection](/rest/reference/repos#remove-status-check-protection)
|
||||
* [Get all status check contexts](/rest/reference/repos#get-all-status-check-contexts)
|
||||
* [Add status check contexts](/rest/reference/repos#add-status-check-contexts)
|
||||
* [Set status check contexts](/rest/reference/repos#set-status-check-contexts)
|
||||
* [Remove status check contexts](/rest/reference/repos#remove-status-check-contexts)
|
||||
* [Get access restrictions](/rest/reference/repos#get-access-restrictions)
|
||||
* [Delete access restrictions](/rest/reference/repos#delete-access-restrictions)
|
||||
* [List branches](/rest/reference/branches#list-branches)
|
||||
* [Get a branch](/rest/reference/branches#get-a-branch)
|
||||
* [Get branch protection](/rest/reference/branches#get-branch-protection)
|
||||
* [Update branch protection](/rest/reference/branches#update-branch-protection)
|
||||
* [Delete branch protection](/rest/reference/branches#delete-branch-protection)
|
||||
* [Get admin branch protection](/rest/reference/branches#get-admin-branch-protection)
|
||||
* [Set admin branch protection](/rest/reference/branches#set-admin-branch-protection)
|
||||
* [Delete admin branch protection](/rest/reference/branches#delete-admin-branch-protection)
|
||||
* [Get pull request review protection](/rest/reference/branches#get-pull-request-review-protection)
|
||||
* [Update pull request review protection](/rest/reference/branches#update-pull-request-review-protection)
|
||||
* [Delete pull request review protection](/rest/reference/branches#delete-pull-request-review-protection)
|
||||
* [Get commit signature protection](/rest/reference/branches#get-commit-signature-protection)
|
||||
* [Create commit signature protection](/rest/reference/branches#create-commit-signature-protection)
|
||||
* [Delete commit signature protection](/rest/reference/branches#delete-commit-signature-protection)
|
||||
* [Get status checks protection](/rest/reference/branches#get-status-checks-protection)
|
||||
* [Update status check protection](/rest/reference/branches#update-status-check-protection)
|
||||
* [Remove status check protection](/rest/reference/branches#remove-status-check-protection)
|
||||
* [Get all status check contexts](/rest/reference/branches#get-all-status-check-contexts)
|
||||
* [Add status check contexts](/rest/reference/branches#add-status-check-contexts)
|
||||
* [Set status check contexts](/rest/reference/branches#set-status-check-contexts)
|
||||
* [Remove status check contexts](/rest/reference/branches#remove-status-check-contexts)
|
||||
* [Get access restrictions](/rest/reference/branches#get-access-restrictions)
|
||||
* [Delete access restrictions](/rest/reference/branches#delete-access-restrictions)
|
||||
* [List teams with access to the protected branch](/rest/reference/repos#list-teams-with-access-to-the-protected-branch)
|
||||
* [Add team access restrictions](/rest/reference/repos#add-team-access-restrictions)
|
||||
* [Set team access restrictions](/rest/reference/repos#set-team-access-restrictions)
|
||||
* [Remove team access restriction](/rest/reference/repos#remove-team-access-restrictions)
|
||||
* [Add team access restrictions](/rest/reference/branches#add-team-access-restrictions)
|
||||
* [Set team access restrictions](/rest/reference/branches#set-team-access-restrictions)
|
||||
* [Remove team access restriction](/rest/reference/branches#remove-team-access-restrictions)
|
||||
* [List user restrictions of protected branch](/rest/reference/repos#list-users-with-access-to-the-protected-branch)
|
||||
* [Add user access restrictions](/rest/reference/repos#add-user-access-restrictions)
|
||||
* [Set user access restrictions](/rest/reference/repos#set-user-access-restrictions)
|
||||
* [Remove user access restrictions](/rest/reference/repos#remove-user-access-restrictions)
|
||||
* [Merge a branch](/rest/reference/repos#merge-a-branch)
|
||||
* [Add user access restrictions](/rest/reference/branches#add-user-access-restrictions)
|
||||
* [Set user access restrictions](/rest/reference/branches#set-user-access-restrictions)
|
||||
* [Remove user access restrictions](/rest/reference/branches#remove-user-access-restrictions)
|
||||
* [Merge a branch](/rest/reference/branches#merge-a-branch)
|
||||
|
||||
#### Repository Collaborators
|
||||
|
||||
* [List repository collaborators](/rest/reference/repos#list-repository-collaborators)
|
||||
* [Check if a user is a repository collaborator](/rest/reference/repos#check-if-a-user-is-a-repository-collaborator)
|
||||
* [Add a repository collaborator](/rest/reference/repos#add-a-repository-collaborator)
|
||||
* [Remove a repository collaborator](/rest/reference/repos#remove-a-repository-collaborator)
|
||||
* [Get repository permissions for a user](/rest/reference/repos#get-repository-permissions-for-a-user)
|
||||
* [List repository collaborators](/rest/reference/collaborators#list-repository-collaborators)
|
||||
* [Check if a user is a repository collaborator](/rest/reference/collaborators#check-if-a-user-is-a-repository-collaborator)
|
||||
* [Add a repository collaborator](/rest/reference/collaborators#add-a-repository-collaborator)
|
||||
* [Remove a repository collaborator](/rest/reference/collaborators#remove-a-repository-collaborator)
|
||||
* [Get repository permissions for a user](/rest/reference/collaborators#get-repository-permissions-for-a-user)
|
||||
|
||||
#### Repository Commit Comments
|
||||
|
||||
* [List commit comments for a repository](/rest/reference/repos#list-commit-comments-for-a-repository)
|
||||
* [Get a commit comment](/rest/reference/repos#get-a-commit-comment)
|
||||
* [Update a commit comment](/rest/reference/repos#update-a-commit-comment)
|
||||
* [Delete a commit comment](/rest/reference/repos#delete-a-commit-comment)
|
||||
* [List commit comments](/rest/reference/repos#list-commit-comments)
|
||||
* [Create a commit comment](/rest/reference/repos#create-a-commit-comment)
|
||||
* [List commit comments for a repository](/rest/reference/commits#list-commit-comments-for-a-repository)
|
||||
* [Get a commit comment](/rest/reference/commits#get-a-commit-comment)
|
||||
* [Update a commit comment](/rest/reference/commits#update-a-commit-comment)
|
||||
* [Delete a commit comment](/rest/reference/commits#delete-a-commit-comment)
|
||||
* [List commit comments](/rest/reference/commits#list-commit-comments)
|
||||
* [Create a commit comment](/rest/reference/commits#create-a-commit-comment)
|
||||
|
||||
#### Repository Commits
|
||||
|
||||
* [List commits](/rest/reference/repos#list-commits)
|
||||
* [Get a commit](/rest/reference/repos#get-a-commit)
|
||||
* [List branches for head commit](/rest/reference/repos#list-branches-for-head-commit)
|
||||
* [List commits](/rest/reference/commits#list-commits)
|
||||
* [Get a commit](/rest/reference/commits#get-a-commit)
|
||||
* [List branches for head commit](/rest/reference/commits#list-branches-for-head-commit)
|
||||
* [List pull requests associated with commit](/rest/reference/repos#list-pull-requests-associated-with-commit)
|
||||
|
||||
#### Repository Community
|
||||
|
||||
* [Get the code of conduct for a repository](/rest/reference/codes-of-conduct#get-the-code-of-conduct-for-a-repository)
|
||||
{% ifversion fpt or ghec %}
|
||||
* [Get community profile metrics](/rest/reference/repos#get-community-profile-metrics)
|
||||
* [Get community profile metrics](/rest/reference/repository-metrics#get-community-profile-metrics)
|
||||
{% endif %}
|
||||
|
||||
#### Repository Contents
|
||||
@@ -722,40 +722,40 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
|
||||
#### Repository Hooks
|
||||
|
||||
* [List repository webhooks](/rest/reference/repos#list-repository-webhooks)
|
||||
* [Create a repository webhook](/rest/reference/repos#create-a-repository-webhook)
|
||||
* [Get a repository webhook](/rest/reference/repos#get-a-repository-webhook)
|
||||
* [Update a repository webhook](/rest/reference/repos#update-a-repository-webhook)
|
||||
* [Delete a repository webhook](/rest/reference/repos#delete-a-repository-webhook)
|
||||
* [Ping a repository webhook](/rest/reference/repos#ping-a-repository-webhook)
|
||||
* [List repository webhooks](/rest/reference/webhooks#list-repository-webhooks)
|
||||
* [Create a repository webhook](/rest/reference/webhooks#create-a-repository-webhook)
|
||||
* [Get a repository webhook](/rest/reference/webhooks#get-a-repository-webhook)
|
||||
* [Update a repository webhook](/rest/reference/webhooks#update-a-repository-webhook)
|
||||
* [Delete a repository webhook](/rest/reference/webhooks#delete-a-repository-webhook)
|
||||
* [Ping a repository webhook](/rest/reference/webhooks#ping-a-repository-webhook)
|
||||
* [Test the push repository webhook](/rest/reference/repos#test-the-push-repository-webhook)
|
||||
|
||||
#### Repository Invitations
|
||||
|
||||
* [List repository invitations](/rest/reference/repos#list-repository-invitations)
|
||||
* [Update a repository invitation](/rest/reference/repos#update-a-repository-invitation)
|
||||
* [Delete a repository invitation](/rest/reference/repos#delete-a-repository-invitation)
|
||||
* [List repository invitations for the authenticated user](/rest/reference/repos#list-repository-invitations-for-the-authenticated-user)
|
||||
* [Accept a repository invitation](/rest/reference/repos#accept-a-repository-invitation)
|
||||
* [Decline a repository invitation](/rest/reference/repos#decline-a-repository-invitation)
|
||||
* [List repository invitations](/rest/reference/collaborators#list-repository-invitations)
|
||||
* [Update a repository invitation](/rest/reference/collaborators#update-a-repository-invitation)
|
||||
* [Delete a repository invitation](/rest/reference/collaborators#delete-a-repository-invitation)
|
||||
* [List repository invitations for the authenticated user](/rest/reference/collaborators#list-repository-invitations-for-the-authenticated-user)
|
||||
* [Accept a repository invitation](/rest/reference/collaborators#accept-a-repository-invitation)
|
||||
* [Decline a repository invitation](/rest/reference/collaborators#decline-a-repository-invitation)
|
||||
|
||||
#### Repository Keys
|
||||
|
||||
* [List deploy keys](/rest/reference/repos#list-deploy-keys)
|
||||
* [Create a deploy key](/rest/reference/repos#create-a-deploy-key)
|
||||
* [Get a deploy key](/rest/reference/repos#get-a-deploy-key)
|
||||
* [Delete a deploy key](/rest/reference/repos#delete-a-deploy-key)
|
||||
* [List deploy keys](/rest/reference/deployments#list-deploy-keys)
|
||||
* [Create a deploy key](/rest/reference/deployments#create-a-deploy-key)
|
||||
* [Get a deploy key](/rest/reference/deployments#get-a-deploy-key)
|
||||
* [Delete a deploy key](/rest/reference/deployments#delete-a-deploy-key)
|
||||
|
||||
#### Repository Pages
|
||||
|
||||
* [Get a GitHub Pages site](/rest/reference/repos#get-a-github-pages-site)
|
||||
* [Create a GitHub Pages site](/rest/reference/repos#create-a-github-pages-site)
|
||||
* [Update information about a GitHub Pages site](/rest/reference/repos#update-information-about-a-github-pages-site)
|
||||
* [Delete a GitHub Pages site](/rest/reference/repos#delete-a-github-pages-site)
|
||||
* [List GitHub Pages builds](/rest/reference/repos#list-github-pages-builds)
|
||||
* [Request a GitHub Pages build](/rest/reference/repos#request-a-github-pages-build)
|
||||
* [Get GitHub Pages build](/rest/reference/repos#get-github-pages-build)
|
||||
* [Get latest pages build](/rest/reference/repos#get-latest-pages-build)
|
||||
* [Get a GitHub Pages site](/rest/reference/pages#get-a-github-pages-site)
|
||||
* [Create a GitHub Pages site](/rest/reference/pages#create-a-github-pages-site)
|
||||
* [Update information about a GitHub Pages site](/rest/reference/pages#update-information-about-a-github-pages-site)
|
||||
* [Delete a GitHub Pages site](/rest/reference/pages#delete-a-github-pages-site)
|
||||
* [List GitHub Pages builds](/rest/reference/pages#list-github-pages-builds)
|
||||
* [Request a GitHub Pages build](/rest/reference/pages#request-a-github-pages-build)
|
||||
* [Get GitHub Pages build](/rest/reference/pages#get-github-pages-build)
|
||||
* [Get latest pages build](/rest/reference/pages#get-latest-pages-build)
|
||||
|
||||
{% ifversion ghes %}
|
||||
#### Repository Pre Receive Hooks
|
||||
@@ -782,11 +782,11 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
|
||||
#### Repository Stats
|
||||
|
||||
* [Get the weekly commit activity](/rest/reference/repos#get-the-weekly-commit-activity)
|
||||
* [Get the last year of commit activity](/rest/reference/repos#get-the-last-year-of-commit-activity)
|
||||
* [Get all contributor commit activity](/rest/reference/repos#get-all-contributor-commit-activity)
|
||||
* [Get the weekly commit count](/rest/reference/repos#get-the-weekly-commit-count)
|
||||
* [Get the hourly commit count for each day](/rest/reference/repos#get-the-hourly-commit-count-for-each-day)
|
||||
* [Get the weekly commit activity](/rest/reference/repository-metrics#get-the-weekly-commit-activity)
|
||||
* [Get the last year of commit activity](/rest/reference/repository-metrics#get-the-last-year-of-commit-activity)
|
||||
* [Get all contributor commit activity](/rest/reference/repository-metrics#get-all-contributor-commit-activity)
|
||||
* [Get the weekly commit count](/rest/reference/repository-metrics#get-the-weekly-commit-count)
|
||||
* [Get the hourly commit count for each day](/rest/reference/repository-metrics#get-the-hourly-commit-count-for-each-day)
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
#### Repository Vulnerability Alerts
|
||||
@@ -812,9 +812,9 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
|
||||
#### Statuses
|
||||
|
||||
* [Get the combined status for a specific reference](/rest/reference/repos#get-the-combined-status-for-a-specific-reference)
|
||||
* [List commit statuses for a reference](/rest/reference/repos#list-commit-statuses-for-a-reference)
|
||||
* [Create a commit status](/rest/reference/repos#create-a-commit-status)
|
||||
* [Get the combined status for a specific reference](/rest/reference/commits#get-the-combined-status-for-a-specific-reference)
|
||||
* [List commit statuses for a reference](/rest/reference/commits#list-commit-statuses-for-a-reference)
|
||||
* [Create a commit status](/rest/reference/commits#create-a-commit-status)
|
||||
|
||||
#### Team Discussions
|
||||
|
||||
@@ -837,10 +837,10 @@ While most of your API interaction should occur using your server-to-server inst
|
||||
{% ifversion fpt or ghec %}
|
||||
#### Traffic
|
||||
|
||||
* [Get repository clones](/rest/reference/repos#get-repository-clones)
|
||||
* [Get top referral paths](/rest/reference/repos#get-top-referral-paths)
|
||||
* [Get top referral sources](/rest/reference/repos#get-top-referral-sources)
|
||||
* [Get page views](/rest/reference/repos#get-page-views)
|
||||
* [Get repository clones](/rest/reference/repository-metrics#get-repository-clones)
|
||||
* [Get top referral paths](/rest/reference/repository-metrics#get-top-referral-paths)
|
||||
* [Get top referral sources](/rest/reference/repository-metrics#get-top-referral-sources)
|
||||
* [Get page views](/rest/reference/repository-metrics#get-page-views)
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
|
||||
@@ -97,7 +97,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](/rest/reference/repos#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/deployments#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
|
||||
|
||||
@@ -98,7 +98,7 @@ You'll need to replace `YOUR_APP_NAME` with the name of your GitHub App, `ID_OF_
|
||||
|
||||
### 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](/rest/reference/repos#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/webhooks#delete-a-repository-webhook) on those repositories that were created by your OAuth App.
|
||||
|
||||
### Encourage users to revoke access to your OAuth app
|
||||
|
||||
|
||||
@@ -327,7 +327,7 @@ Webhook events are triggered based on the specificity of the domain you register
|
||||
Key | Type | Description
|
||||
----|------|-------------{% ifversion fpt or ghes or ghae or ghec %}
|
||||
`action` |`string` | The action performed. Can be `created`.{% endif %}
|
||||
`deployment` |`object` | The [deployment](/rest/reference/repos#list-deployments).
|
||||
`deployment` |`object` | The [deployment](/rest/reference/deployments#list-deployments).
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %}
|
||||
@@ -352,11 +352,11 @@ Key | Type | Description
|
||||
Key | Type | Description
|
||||
----|------|-------------{% ifversion fpt or ghes or ghae or ghec %}
|
||||
`action` |`string` | The action performed. Can be `created`.{% endif %}
|
||||
`deployment_status` |`object` | The [deployment status](/rest/reference/repos#list-deployment-statuses).
|
||||
`deployment_status` |`object` | The [deployment status](/rest/reference/deployments#list-deployment-statuses).
|
||||
`deployment_status["state"]` |`string` | The new state. Can be `pending`, `success`, `failure`, or `error`.
|
||||
`deployment_status["target_url"]` |`string` | The optional link added to the status.
|
||||
`deployment_status["description"]`|`string` | The optional human-readable description added to the status.
|
||||
`deployment` |`object` | The [deployment](/rest/reference/repos#list-deployments) that this status is associated with.
|
||||
`deployment` |`object` | The [deployment](/rest/reference/deployments#list-deployments) that this status is associated with.
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %}
|
||||
@@ -820,7 +820,7 @@ Activity related to {% data variables.product.prodname_registry %}. {% data reus
|
||||
Key | Type | Description
|
||||
----|------|------------
|
||||
`id` | `integer` | The unique identifier of the page build.
|
||||
`build` | `object` | The [List GitHub Pages builds](/rest/reference/repos#list-github-pages-builds) itself.
|
||||
`build` | `object` | The [List GitHub Pages builds](/rest/reference/pages#list-github-pages-builds) itself.
|
||||
{% data reusables.webhooks.repo_desc %}
|
||||
{% data reusables.webhooks.org_desc %}
|
||||
{% data reusables.webhooks.app_desc %}
|
||||
@@ -846,7 +846,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](/rest/reference/repos#get-a-repository-webhook).
|
||||
`hook` | `object` | The [webhook configuration](/rest/reference/webhooks#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 %}
|
||||
|
||||
@@ -263,4 +263,4 @@ puts "The next page link is #{next_page_href}"
|
||||
[octokit.rb]: https://github.com/octokit/octokit.rb
|
||||
[personal token]: /articles/creating-an-access-token-for-command-line-use
|
||||
[hypermedia-relations]: https://github.com/octokit/octokit.rb#pagination
|
||||
[listing commits]: /rest/reference/repos#list-commits
|
||||
[listing commits]: /rest/reference/commits#list-commits
|
||||
|
||||
@@ -126,4 +126,4 @@ on the entire commit.
|
||||
[personal token]: /articles/creating-an-access-token-for-command-line-use
|
||||
[octokit.rb]: https://github.com/octokit/octokit.rb
|
||||
[PR Review API]: /rest/reference/pulls#comments
|
||||
[commit comment API]: /rest/reference/repos#get-a-commit-comment
|
||||
[commit comment API]: /rest/reference/commits#get-a-commit-comment
|
||||
|
||||
@@ -165,7 +165,7 @@ GitHub App Manifests allow people to create preconfigured GitHub Apps. See "[Cre
|
||||
|
||||
## Deployment statuses
|
||||
|
||||
You can now update the `environment` of a [deployment status](/rest/reference/repos#create-a-deployment-status) and use the `in_progress` and `queued` states. When you create deployment statuses, you can now use the `auto_inactive` parameter to mark old `production` deployments as `inactive`.
|
||||
You can now update the `environment` of a [deployment status](/rest/reference/deployments#create-a-deployment-status) and use the `in_progress` and `queued` states. When you create deployment statuses, you can now use the `auto_inactive` parameter to mark old `production` deployments as `inactive`.
|
||||
|
||||
**Custom media type:** `flash-preview`
|
||||
**Announced:** [2018-10-16](https://developer.github.com/changes/2018-10-16-deployments-environments-states-and-auto-inactive-updates/)
|
||||
|
||||
30
content/rest/reference/branches.md
Normal file
30
content/rest/reference/branches.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Branches
|
||||
intro: 'The branches API allows you to modify branches and their protection settings.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
## Branches
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'branches' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Merging
|
||||
|
||||
The Repo Merging API supports merging branches in a repository. This accomplishes
|
||||
essentially the same thing as merging one branch into another in a local repository
|
||||
and then pushing to {% data variables.product.product_name %}. The benefit is that the merge is done on the server side and a local repository is not needed. This makes it more appropriate for automation and other tools where maintaining local repositories would be cumbersome and inefficient.
|
||||
|
||||
The authenticated user will be the author of any merges done through this endpoint.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'merging' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
35
content/rest/reference/collaborators.md
Normal file
35
content/rest/reference/collaborators.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Collaborators
|
||||
intro: 'The collaborators API allows you to add, invite, and remove collaborators from a repository.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
## Collaborators
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'collaborators' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Invitations
|
||||
|
||||
The Repository Invitations API allows users or external services to invite other users to collaborate on a repo. The invited users (or external services on behalf of invited users) can choose to accept or decline the invitations.
|
||||
|
||||
Note that the `repo:invite` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted
|
||||
access to invitations **without** also granting access to repository code, while the
|
||||
`repo` scope grants permission to code as well as invitations.
|
||||
|
||||
### Invite a user to a repository
|
||||
|
||||
Use the API endpoint for adding a collaborator. For more information, see "[Add a repository collaborator](/rest/reference/collaborators#add-a-repository-collaborator)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'invitations' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
68
content/rest/reference/commits.md
Normal file
68
content/rest/reference/commits.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Commits
|
||||
intro: 'The commits API allows you to retrieve information and commits, create commit comments, and create commit statuses.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
## Commits
|
||||
|
||||
The Repo Commits API supports listing, viewing, and comparing commits in a repository.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'commits' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Commit comments
|
||||
|
||||
### Custom media types for commit comments
|
||||
|
||||
These are the supported media types for commit comments. You can read more
|
||||
about the use of media types in the API [here](/rest/overview/media-types).
|
||||
|
||||
application/vnd.github-commitcomment.raw+json
|
||||
application/vnd.github-commitcomment.text+json
|
||||
application/vnd.github-commitcomment.html+json
|
||||
application/vnd.github-commitcomment.full+json
|
||||
|
||||
For more information, see "[Custom media types](/rest/overview/media-types)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'comments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Commit statuses
|
||||
|
||||
The status API allows external services to mark commits with an `error`,
|
||||
`failure`, `pending`, or `success` state, which is then reflected in pull requests
|
||||
involving those commits.
|
||||
|
||||
Statuses can also include an optional `description` and `target_url`, and
|
||||
we highly recommend providing them as they make statuses much more
|
||||
useful in the GitHub UI.
|
||||
|
||||
As an example, one common use is for continuous integration
|
||||
services to mark commits as passing or failing builds using status. The
|
||||
`target_url` would be the full URL to the build output, and the
|
||||
`description` would be the high level summary of what happened with the
|
||||
build.
|
||||
|
||||
Statuses can include a `context` to indicate what service is providing that status.
|
||||
For example, you may have your continuous integration service push statuses with a context of `ci`, and a security audit tool push statuses with a context of `security`. You can
|
||||
then use the [Get the combined status for a specific reference](/rest/reference/commits#get-the-combined-status-for-a-specific-reference) to retrieve the whole status for a commit.
|
||||
|
||||
Note that the `repo:status` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to statuses **without** also granting access to repository code, while the
|
||||
`repo` scope grants permission to code as well as statuses.
|
||||
|
||||
If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the [Checks API](/rest/reference/checks).
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'statuses' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
90
content/rest/reference/deployments.md
Normal file
90
content/rest/reference/deployments.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Deployments
|
||||
intro: 'The deployments API allows you to create and delete deploy keys, deployments, and deployment environments.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
## Deploy keys
|
||||
|
||||
{% data reusables.repositories.deploy-keys %}
|
||||
|
||||
Deploy keys can either be setup using the following API endpoints, or by using GitHub. To learn how to set deploy keys up in GitHub, see "[Managing deploy keys](/developers/overview/managing-deploy-keys)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'keys' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Deployments
|
||||
|
||||
Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a [`deployment` event](/developers/webhooks-and-events/webhook-events-and-payloads#deployment) that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).
|
||||
|
||||
Deployment statuses allow external services to mark deployments with an `error`, `failure`, `pending`, `in_progress`, `queued`, or `success` state that systems listening to [`deployment_status` events](/developers/webhooks-and-events/webhook-events-and-payloads#deployment_status) can consume.
|
||||
|
||||
Deployment statuses can also include an optional `description` and `log_url`, which are highly recommended because they make deployment statuses more useful. The `log_url` is the full URL to the deployment output, and
|
||||
the `description` is a high-level summary of what happened with the deployment.
|
||||
|
||||
GitHub dispatches `deployment` and `deployment_status` events when new deployments and deployment statuses are created. These events allows third-party integrations to receive respond to deployment requests and update the status of a deployment as progress is made.
|
||||
|
||||
Below is a simple sequence diagram for how these interactions would work.
|
||||
|
||||
```
|
||||
+---------+ +--------+ +-----------+ +-------------+
|
||||
| Tooling | | GitHub | | 3rd Party | | Your Server |
|
||||
+---------+ +--------+ +-----------+ +-------------+
|
||||
| | | |
|
||||
| Create Deployment | | |
|
||||
|--------------------->| | |
|
||||
| | | |
|
||||
| Deployment Created | | |
|
||||
|<---------------------| | |
|
||||
| | | |
|
||||
| | Deployment Event | |
|
||||
| |---------------------->| |
|
||||
| | | SSH+Deploys |
|
||||
| | |-------------------->|
|
||||
| | | |
|
||||
| | Deployment Status | |
|
||||
| |<----------------------| |
|
||||
| | | |
|
||||
| | | Deploy Completed |
|
||||
| | |<--------------------|
|
||||
| | | |
|
||||
| | Deployment Status | |
|
||||
| |<----------------------| |
|
||||
| | | |
|
||||
```
|
||||
|
||||
Keep in mind that GitHub is never actually accessing your servers. It's up to your third-party integration to interact with deployment events. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether they're responsible for pushing the code out to your servers, building native code, etc.
|
||||
|
||||
Note that the `repo_deployment` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to deployments and deployment statuses **without** granting access to repository code, while the {% ifversion not ghae %}`public_repo` and{% endif %}`repo` scopes grant permission to code as well.
|
||||
|
||||
|
||||
### Inactive deployments
|
||||
|
||||
When you set the state of a deployment to `success`, then all prior non-transient, non-production environment deployments in the same repository with the same environment name will become `inactive`. To avoid this, you can set `auto_inactive` to `false` when creating the deployment status.
|
||||
|
||||
You can communicate that a transient environment no longer exists by setting its `state` to `inactive`. Setting the `state` to `inactive` shows the deployment as `destroyed` in {% data variables.product.prodname_dotcom %} and removes access to it.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'deployments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.1 or ghae or ghec %}
|
||||
## Environments
|
||||
|
||||
The Environments API allows you to create, configure, and delete environments. For more information about environments, see "[Using environments for deployment](/actions/deployment/using-environments-for-deployment)." To manage environment secrets, see "[Secrets](/rest/reference/actions#secrets)."
|
||||
|
||||
{% data reusables.gated-features.environments %}
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'environments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
@@ -14,14 +14,19 @@ children:
|
||||
- /activity
|
||||
- /apps
|
||||
- /billing
|
||||
- /branches
|
||||
- /checks
|
||||
- /codes-of-conduct
|
||||
- /code-scanning
|
||||
- /codespaces
|
||||
- /commits
|
||||
- /collaborators
|
||||
- /deployments
|
||||
- /emojis
|
||||
- /enterprise-admin
|
||||
- /gists
|
||||
- /git
|
||||
- /pages
|
||||
- /gitignore
|
||||
- /interactions
|
||||
- /issues
|
||||
@@ -36,12 +41,15 @@ children:
|
||||
- /pulls
|
||||
- /rate-limit
|
||||
- /reactions
|
||||
- /releases
|
||||
- /repos
|
||||
- /repository-metrics
|
||||
- /scim
|
||||
- /search
|
||||
- /secret-scanning
|
||||
- /teams
|
||||
- /users
|
||||
- /webhooks
|
||||
- /permissions-required-for-github-apps
|
||||
---
|
||||
|
||||
|
||||
32
content/rest/reference/pages.md
Normal file
32
content/rest/reference/pages.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Pages
|
||||
intro: 'The GitHub Pages API allows you to interact with GitHub Pages sites and build information.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
The {% data variables.product.prodname_pages %} API retrieves information about your {% data variables.product.prodname_pages %} configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners{% ifversion not ghae %}, even if the websites are public{% endif %}. For more information, see "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages)."
|
||||
|
||||
In {% data variables.product.prodname_pages %} API endpoints with a `status` key in their response, the value can be one of:
|
||||
* `null`: The site has yet to be built.
|
||||
* `queued`: The build has been requested but not yet begun.
|
||||
* `building`:The build is in progress.
|
||||
* `built`: The site has been built.
|
||||
* `errored`: Indicates an error occurred during the build.
|
||||
|
||||
In {% data variables.product.prodname_pages %} API endpoints that return GitHub Pages site information, the JSON responses include these fields:
|
||||
* `html_url`: The absolute URL (including scheme) of the rendered Pages site. For example, `https://username.github.io`.
|
||||
* `source`: An object that contains the source branch and directory for the rendered Pages site. This includes:
|
||||
- `branch`: The repository branch used to publish your [site's source files](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). For example, _main_ or _gh-pages_.
|
||||
- `path`: The repository directory from which the site publishes. Will be either `/` or `/docs`.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'pages' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
@@ -41,18 +41,18 @@ GitHub Apps have the `Read-only` metadata permission by default. The metadata pe
|
||||
- [`GET /rate_limit`](/rest/reference/rate-limit#get-rate-limit-status-for-the-authenticated-user)
|
||||
- [`GET /repos/:owner/:repo`](/rest/reference/repos#get-a-repository)
|
||||
{% ifversion fpt -%}
|
||||
- [`GET /repos/:owner/:repo/community/profile`](/rest/reference/repos#get-community-profile-metrics)
|
||||
- [`GET /repos/:owner/:repo/community/profile`](/rest/reference/repository-metrics#get-community-profile-metrics)
|
||||
{% endif -%}
|
||||
- [`GET /repos/:owner/:repo/contributors`](/rest/reference/repos#list-repository-contributors)
|
||||
- [`GET /repos/:owner/:repo/forks`](/rest/reference/repos#list-forks)
|
||||
- [`GET /repos/:owner/:repo/languages`](/rest/reference/repos#list-repository-languages)
|
||||
- [`GET /repos/:owner/:repo/license`](/rest/reference/licenses#get-the-license-for-a-repository)
|
||||
- [`GET /repos/:owner/:repo/stargazers`](/rest/reference/activity#list-stargazers)
|
||||
- [`GET /repos/:owner/:repo/stats/code_frequency`](/rest/reference/repos#get-the-weekly-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/commit_activity`](/rest/reference/repos#get-the-last-year-of-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/contributors`](/rest/reference/repos#get-all-contributor-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/participation`](/rest/reference/repos#get-the-weekly-commit-count)
|
||||
- [`GET /repos/:owner/:repo/stats/punch_card`](/rest/reference/repos#get-the-hourly-commit-count-for-each-day)
|
||||
- [`GET /repos/:owner/:repo/stats/code_frequency`](/rest/reference/repository-metrics#get-the-weekly-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/commit_activity`](/rest/reference/repository-metrics#get-the-last-year-of-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/contributors`](/rest/reference/repository-metrics#get-all-contributor-commit-activity)
|
||||
- [`GET /repos/:owner/:repo/stats/participation`](/rest/reference/repository-metrics#get-the-weekly-commit-count)
|
||||
- [`GET /repos/:owner/:repo/stats/punch_card`](/rest/reference/repository-metrics#get-the-hourly-commit-count-for-each-day)
|
||||
- [`GET /repos/:owner/:repo/subscribers`](/rest/reference/activity#list-watchers)
|
||||
- [`GET /repos/:owner/:repo/tags`](/rest/reference/repos#list-repository-tags)
|
||||
- [`GET /repos/:owner/:repo/topics`](/rest/reference/repos#get-all-repository-topics)
|
||||
@@ -73,14 +73,14 @@ GitHub Apps have the `Read-only` metadata permission by default. The metadata pe
|
||||
- [`GET /users/:username/subscriptions`](/rest/reference/activity#list-repositories-watched-by-a-user)
|
||||
|
||||
_Collaborators_
|
||||
- [`GET /repos/:owner/:repo/collaborators`](/rest/reference/repos#list-repository-collaborators)
|
||||
- [`GET /repos/:owner/:repo/collaborators/:username`](/rest/reference/repos#check-if-a-user-is-a-repository-collaborator)
|
||||
- [`GET /repos/:owner/:repo/collaborators`](/rest/reference/collaborators#list-repository-collaborators)
|
||||
- [`GET /repos/:owner/:repo/collaborators/:username`](/rest/reference/collaborators#check-if-a-user-is-a-repository-collaborator)
|
||||
|
||||
_Commit comments_
|
||||
- [`GET /repos/:owner/:repo/comments`](/rest/reference/repos#list-commit-comments-for-a-repository)
|
||||
- [`GET /repos/:owner/:repo/comments/:comment_id`](/rest/reference/repos#get-a-commit-comment)
|
||||
- [`GET /repos/:owner/:repo/comments`](/rest/reference/commits#list-commit-comments-for-a-repository)
|
||||
- [`GET /repos/:owner/:repo/comments/:comment_id`](/rest/reference/commits#get-a-commit-comment)
|
||||
- [`GET /repos/:owner/:repo/comments/:comment_id/reactions`](/rest/reference/reactions#list-reactions-for-a-commit-comment)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha/comments`](/rest/reference/repos#list-commit-comments)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha/comments`](/rest/reference/commits#list-commit-comments)
|
||||
|
||||
_Events_
|
||||
- [`GET /events`](/rest/reference/activity#list-public-events)
|
||||
@@ -173,7 +173,7 @@ _Search_
|
||||
- [`DELETE /repos/:owner/:repo/interaction-limits`](/rest/reference/interactions#remove-interaction-restrictions-for-a-repository) (:write)
|
||||
{% endif -%}
|
||||
{% ifversion fpt -%}
|
||||
- [`GET /repos/:owner/:repo/pages/health`](/rest/reference/repos#get-a-dns-health-check-for-github-pages) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/health`](/rest/reference/pages#get-a-dns-health-check-for-github-pages) (:write)
|
||||
{% endif -%}
|
||||
- [`PUT /repos/:owner/:repo/topics`](/rest/reference/repos#replace-all-repository-topics) (:write)
|
||||
- [`POST /repos/:owner/:repo/transfer`](/rest/reference/repos#transfer-a-repository) (:write)
|
||||
@@ -186,57 +186,57 @@ _Search_
|
||||
{% ifversion fpt -%}
|
||||
- [`DELETE /repos/:owner/:repo/vulnerability-alerts`](/rest/reference/repos#disable-vulnerability-alerts) (:write)
|
||||
{% endif -%}
|
||||
- [`PATCH /user/repository_invitations/:invitation_id`](/rest/reference/repos#accept-a-repository-invitation) (:write)
|
||||
- [`DELETE /user/repository_invitations/:invitation_id`](/rest/reference/repos#decline-a-repository-invitation) (:write)
|
||||
- [`PATCH /user/repository_invitations/:invitation_id`](/rest/reference/collaborators#accept-a-repository-invitation) (:write)
|
||||
- [`DELETE /user/repository_invitations/:invitation_id`](/rest/reference/collaborators#decline-a-repository-invitation) (:write)
|
||||
|
||||
_Branches_
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/repos#get-branch-protection) (:read)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/repos#update-branch-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/repos#delete-branch-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/repos#get-admin-branch-protection) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/repos#set-admin-branch-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/repos#delete-admin-branch-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/repos#get-pull-request-review-protection) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/repos#update-pull-request-review-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/repos#delete-pull-request-review-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/repos#get-commit-signature-protection) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/repos#create-commit-signature-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/repos#delete-commit-signature-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/repos#get-status-checks-protection) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/repos#update-status-check-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/repos#remove-status-check-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/repos#get-all-status-check-contexts) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/repos#add-status-check-contexts) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/repos#set-status-check-contexts) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/repos#remove-status-check-contexts) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/restrictions`](/rest/reference/repos#get-access-restrictions) (:read)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions`](/rest/reference/repos#delete-access-restrictions) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/branches#get-branch-protection) (:read)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/branches#update-branch-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection`](/rest/reference/branches#delete-branch-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/branches#get-admin-branch-protection) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/branches#set-admin-branch-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/enforce_admins`](/rest/reference/branches#delete-admin-branch-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/branches#get-pull-request-review-protection) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/branches#update-pull-request-review-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_pull_request_reviews`](/rest/reference/branches#delete-pull-request-review-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/branches#get-commit-signature-protection) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/branches#create-commit-signature-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_signatures`](/rest/reference/branches#delete-commit-signature-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/branches#get-status-checks-protection) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/branches#update-status-check-protection) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks`](/rest/reference/branches#remove-status-check-protection) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/branches#get-all-status-check-contexts) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/branches#add-status-check-contexts) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/branches#set-status-check-contexts) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/required_status_checks/contexts`](/rest/reference/branches#remove-status-check-contexts) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/restrictions`](/rest/reference/branches#get-access-restrictions) (:read)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions`](/rest/reference/branches#delete-access-restrictions) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/repos#list-teams-with-access-to-the-protected-branch) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/repos#add-team-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/repos#set-team-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/repos#remove-team-access-restrictions) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/branches#add-team-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/branches#set-team-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/teams`](/rest/reference/branches#remove-team-access-restrictions) (:write)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/repos#list-users-with-access-to-the-protected-branch) (:read)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/repos#add-user-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/repos#set-user-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/repos#remove-user-access-restrictions) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/branches#add-user-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/branches#set-user-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/users`](/rest/reference/branches#remove-user-access-restrictions) (:write)
|
||||
{% ifversion fpt or ghes > 3.0 or ghae -%}
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/rename`](/rest/reference/repos#rename-a-branch) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/rename`](/rest/reference/branches#rename-a-branch) (:write)
|
||||
{% endif %}
|
||||
|
||||
_Collaborators_
|
||||
- [`PUT /repos/:owner/:repo/collaborators/:username`](/rest/reference/repos#add-a-repository-collaborator) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/collaborators/:username`](/rest/reference/repos#remove-a-repository-collaborator) (:write)
|
||||
- [`PUT /repos/:owner/:repo/collaborators/:username`](/rest/reference/collaborators#add-a-repository-collaborator) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/collaborators/:username`](/rest/reference/collaborators#remove-a-repository-collaborator) (:write)
|
||||
|
||||
_Invitations_
|
||||
- [`GET /repos/:owner/:repo/invitations`](/rest/reference/repos#list-repository-invitations) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/invitations/:invitation_id`](/rest/reference/repos#update-a-repository-invitation) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/invitations/:invitation_id`](/rest/reference/repos#delete-a-repository-invitation) (:write)
|
||||
- [`GET /repos/:owner/:repo/invitations`](/rest/reference/collaborators#list-repository-invitations) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/invitations/:invitation_id`](/rest/reference/collaborators#update-a-repository-invitation) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/invitations/:invitation_id`](/rest/reference/collaborators#delete-a-repository-invitation) (:write)
|
||||
|
||||
_Keys_
|
||||
- [`GET /repos/:owner/:repo/keys`](/rest/reference/repos#list-deploy-keys) (:read)
|
||||
- [`POST /repos/:owner/:repo/keys`](/rest/reference/repos#create-a-deploy-key) (:write)
|
||||
- [`GET /repos/:owner/:repo/keys/:key_id`](/rest/reference/repos#get-a-deploy-key) (:read)
|
||||
- [`DELETE /repos/:owner/:repo/keys/:key_id`](/rest/reference/repos#delete-a-deploy-key) (:write)
|
||||
- [`GET /repos/:owner/:repo/keys`](/rest/reference/deployments#list-deploy-keys) (:read)
|
||||
- [`POST /repos/:owner/:repo/keys`](/rest/reference/deployments#create-a-deploy-key) (:write)
|
||||
- [`GET /repos/:owner/:repo/keys/:key_id`](/rest/reference/deployments#get-a-deploy-key) (:read)
|
||||
- [`DELETE /repos/:owner/:repo/keys/:key_id`](/rest/reference/deployments#delete-a-deploy-key) (:write)
|
||||
|
||||
_Teams_
|
||||
- [`GET /repos/:owner/:repo/teams`](/rest/reference/repos#list-repository-teams) (:read)
|
||||
@@ -245,10 +245,10 @@ _Teams_
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
_Traffic_
|
||||
- [`GET /repos/:owner/:repo/traffic/clones`](/rest/reference/repos#get-repository-clones) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/popular/paths`](/rest/reference/repos#get-top-referral-paths) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/popular/referrers`](/rest/reference/repos#get-top-referral-sources) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/views`](/rest/reference/repos#get-page-views) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/clones`](/rest/reference/repository-metrics#get-repository-clones) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/popular/paths`](/rest/reference/repository-metrics#get-top-referral-paths) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/popular/referrers`](/rest/reference/repository-metrics#get-top-referral-sources) (:read)
|
||||
- [`GET /repos/:owner/:repo/traffic/views`](/rest/reference/repository-metrics#get-page-views) (:read)
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
@@ -345,37 +345,37 @@ _Traffic_
|
||||
- [`GET /repos/:owner/:repo/check-suites/:check_suite_id`](/rest/reference/checks#get-a-check-suite) (:read)
|
||||
- [`GET /repos/:owner/:repo/check-suites/:check_suite_id/check-runs`](/rest/reference/checks#list-check-runs-in-a-check-suite) (:read)
|
||||
- [`POST /repos/:owner/:repo/check-suites/:check_suite_id/rerequest`](/rest/reference/checks#rerequest-a-check-suite) (:write)
|
||||
- [`GET /repos/:owner/:repo/commits`](/rest/reference/repos#list-commits) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha`](/rest/reference/repos#get-a-commit) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits`](/rest/reference/commits#list-commits) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha`](/rest/reference/commits#get-a-commit) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha/check-runs`](/rest/reference/checks#list-check-runs-for-a-git-reference) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:sha/check-suites`](/rest/reference/checks#list-check-suites-for-a-git-reference) (:read)
|
||||
- [`GET /repos/:owner/:repo/community/code_of_conduct`](/rest/reference/codes-of-conduct#get-the-code-of-conduct-for-a-repository) (:read)
|
||||
- [`GET /repos/:owner/:repo/compare/:base...:head`](/rest/reference/repos#compare-two-commits) (:read)
|
||||
- [`GET /repos/:owner/:repo/compare/:base...:head`](/rest/reference/commits#compare-two-commits) (:read)
|
||||
- [`GET /repos/:owner/:repo/contents/:path`](/rest/reference/repos#get-repository-content) (:read)
|
||||
{% ifversion fpt or ghes or ghae -%}
|
||||
- [`POST /repos/:owner/:repo/dispatches`](/rest/reference/repos#create-a-repository-dispatch-event) (:write)
|
||||
{% endif -%}
|
||||
- [`POST /repos/:owner/:repo/forks`](/rest/reference/repos#create-a-fork) (:read)
|
||||
- [`POST /repos/:owner/:repo/merges`](/rest/reference/repos#merge-a-branch) (:write)
|
||||
- [`POST /repos/:owner/:repo/merges`](/rest/reference/branches#merge-a-branch) (:write)
|
||||
- [`PUT /repos/:owner/:repo/pulls/:pull_number/merge`](/rest/reference/pulls#merge-a-pull-request) (:write)
|
||||
- [`GET /repos/:owner/:repo/readme(?:/(.*))?`](/rest/reference/repos#get-a-repository-readme) (:read)
|
||||
|
||||
_Branches_
|
||||
- [`GET /repos/:owner/:repo/branches`](/rest/reference/repos#list-branches) (:read)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch`](/rest/reference/repos#get-a-branch) (:read)
|
||||
- [`GET /repos/:owner/:repo/branches`](/rest/reference/branches#list-branches) (:read)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch`](/rest/reference/branches#get-a-branch) (:read)
|
||||
- [`GET /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/repos#list-apps-with-access-to-the-protected-branch) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/repos#add-app-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/repos#set-app-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/repos#remove-user-access-restrictions) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/branches#add-app-access-restrictions) (:write)
|
||||
- [`PUT /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/branches#set-app-access-restrictions) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/branches/:branch/protection/restrictions/apps`](/rest/reference/branches#remove-user-access-restrictions) (:write)
|
||||
{% ifversion fpt or ghes > 3.0 or ghae -%}
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/rename`](/rest/reference/repos#rename-a-branch) (:write)
|
||||
- [`POST /repos/:owner/:repo/branches/:branch/rename`](/rest/reference/branches#rename-a-branch) (:write)
|
||||
{% endif %}
|
||||
|
||||
_Commit comments_
|
||||
- [`PATCH /repos/:owner/:repo/comments/:comment_id`](/rest/reference/repos#update-a-commit-comment) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/comments/:comment_id`](/rest/reference/repos#delete-a-commit-comment) (:write)
|
||||
- [`PATCH /repos/:owner/:repo/comments/:comment_id`](/rest/reference/commits#update-a-commit-comment) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/comments/:comment_id`](/rest/reference/commits#delete-a-commit-comment) (:write)
|
||||
- [`POST /repos/:owner/:repo/comments/:comment_id/reactions`](/rest/reference/reactions#create-reaction-for-a-commit-comment) (:read)
|
||||
- [`POST /repos/:owner/:repo/commits/:sha/comments`](/rest/reference/repos#create-a-commit-comment) (:read)
|
||||
- [`POST /repos/:owner/:repo/commits/:sha/comments`](/rest/reference/commits#create-a-commit-comment) (:read)
|
||||
|
||||
_Git_
|
||||
- [`POST /repos/:owner/:repo/git/blobs`](/rest/reference/git#create-a-blob) (:write)
|
||||
@@ -435,15 +435,15 @@ _Releases_
|
||||
|
||||
### Permission on "deployments"
|
||||
|
||||
- [`GET /repos/:owner/:repo/deployments`](/rest/reference/repos#list-deployments) (:read)
|
||||
- [`POST /repos/:owner/:repo/deployments`](/rest/reference/repos#create-a-deployment) (:write)
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id`](/rest/reference/repos#get-a-deployment) (:read)
|
||||
- [`GET /repos/:owner/:repo/deployments`](/rest/reference/deployments#list-deployments) (:read)
|
||||
- [`POST /repos/:owner/:repo/deployments`](/rest/reference/deployments#create-a-deployment) (:write)
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id`](/rest/reference/deployments#get-a-deployment) (:read)
|
||||
{% ifversion fpt or ghes or ghae -%}
|
||||
- [`DELETE /repos/:owner/:repo/deployments/:deployment_id`](/rest/reference/repos#delete-a-deployment) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/deployments/:deployment_id`](/rest/reference/deployments#delete-a-deployment) (:write)
|
||||
{% endif -%}
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id/statuses`](/rest/reference/repos#list-deployment-statuses) (:read)
|
||||
- [`POST /repos/:owner/:repo/deployments/:deployment_id/statuses`](/rest/reference/repos#create-a-deployment-status) (:write)
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id/statuses/:status_id`](/rest/reference/repos#get-a-deployment-status) (:read)
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id/statuses`](/rest/reference/deployments#list-deployment-statuses) (:read)
|
||||
- [`POST /repos/:owner/:repo/deployments/:deployment_id/statuses`](/rest/reference/deployments#create-a-deployment-status) (:write)
|
||||
- [`GET /repos/:owner/:repo/deployments/:deployment_id/statuses/:status_id`](/rest/reference/deployments#get-a-deployment-status) (:read)
|
||||
|
||||
{% ifversion fpt or ghes or ghec %}
|
||||
### Permission on "emails"
|
||||
@@ -703,16 +703,16 @@ _Teams_
|
||||
|
||||
### Permission on "pages"
|
||||
|
||||
- [`GET /repos/:owner/:repo/pages`](/rest/reference/repos#get-a-github-pages-site) (:read)
|
||||
- [`POST /repos/:owner/:repo/pages`](/rest/reference/repos#create-a-github-pages-site) (:write)
|
||||
- [`PUT /repos/:owner/:repo/pages`](/rest/reference/repos#update-information-about-a-github-pages-site) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/pages`](/rest/reference/repos#delete-a-github-pages-site) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/builds`](/rest/reference/repos#list-github-pages-builds) (:read)
|
||||
- [`POST /repos/:owner/:repo/pages/builds`](/rest/reference/repos#request-a-github-pages-build) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/builds/:build_id`](/rest/reference/repos#get-github-pages-build) (:read)
|
||||
- [`GET /repos/:owner/:repo/pages/builds/latest`](/rest/reference/repos#get-latest-pages-build) (:read)
|
||||
- [`GET /repos/:owner/:repo/pages`](/rest/reference/pages#get-a-github-pages-site) (:read)
|
||||
- [`POST /repos/:owner/:repo/pages`](/rest/reference/pages#create-a-github-pages-site) (:write)
|
||||
- [`PUT /repos/:owner/:repo/pages`](/rest/reference/pages#update-information-about-a-github-pages-site) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/pages`](/rest/reference/pages#delete-a-github-pages-site) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/builds`](/rest/reference/pages#list-github-pages-builds) (:read)
|
||||
- [`POST /repos/:owner/:repo/pages/builds`](/rest/reference/pages#request-a-github-pages-build) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/builds/:build_id`](/rest/reference/pages#get-github-pages-build) (:read)
|
||||
- [`GET /repos/:owner/:repo/pages/builds/latest`](/rest/reference/pages#get-latest-pages-build) (:read)
|
||||
{% ifversion fpt -%}
|
||||
- [`GET /repos/:owner/:repo/pages/health`](/rest/reference/repos#get-a-dns-health-check-for-github-pages) (:write)
|
||||
- [`GET /repos/:owner/:repo/pages/health`](/rest/reference/pages#get-a-dns-health-check-for-github-pages) (:write)
|
||||
{% endif %}
|
||||
|
||||
### Permission on "pull requests"
|
||||
@@ -812,12 +812,12 @@ _Reviews_
|
||||
|
||||
### Permission on "repository hooks"
|
||||
|
||||
- [`GET /repos/:owner/:repo/hooks`](/rest/reference/repos#list-repository-webhooks) (:read)
|
||||
- [`POST /repos/:owner/:repo/hooks`](/rest/reference/repos#create-a-repository-webhook) (:write)
|
||||
- [`GET /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/repos#get-a-repository-webhook) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/repos#update-a-repository-webhook) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/repos#delete-a-repository-webhook) (:write)
|
||||
- [`POST /repos/:owner/:repo/hooks/:hook_id/pings`](/rest/reference/repos#ping-a-repository-webhook) (:read)
|
||||
- [`GET /repos/:owner/:repo/hooks`](/rest/reference/webhooks#list-repository-webhooks) (:read)
|
||||
- [`POST /repos/:owner/:repo/hooks`](/rest/reference/webhooks#create-a-repository-webhook) (:write)
|
||||
- [`GET /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/webhooks#get-a-repository-webhook) (:read)
|
||||
- [`PATCH /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/webhooks#update-a-repository-webhook) (:write)
|
||||
- [`DELETE /repos/:owner/:repo/hooks/:hook_id`](/rest/reference/webhooks#delete-a-repository-webhook) (:write)
|
||||
- [`POST /repos/:owner/:repo/hooks/:hook_id/pings`](/rest/reference/webhooks#ping-a-repository-webhook) (:read)
|
||||
- [`POST /repos/:owner/:repo/hooks/:hook_id/tests`](/rest/reference/repos#test-the-push-repository-webhook) (:read)
|
||||
|
||||
{% ifversion ghes %}
|
||||
@@ -930,9 +930,9 @@ _Teams_
|
||||
|
||||
### Permission on "statuses"
|
||||
|
||||
- [`GET /repos/:owner/:repo/commits/:ref/status`](/rest/reference/repos#get-the-combined-status-for-a-specific-reference) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:ref/statuses`](/rest/reference/repos#list-commit-statuses-for-a-reference) (:read)
|
||||
- [`POST /repos/:owner/:repo/statuses/:sha`](/rest/reference/repos#create-a-commit-status) (:write)
|
||||
- [`GET /repos/:owner/:repo/commits/:ref/status`](/rest/reference/commits#get-the-combined-status-for-a-specific-reference) (:read)
|
||||
- [`GET /repos/:owner/:repo/commits/:ref/statuses`](/rest/reference/commits#list-commit-statuses-for-a-reference) (:read)
|
||||
- [`POST /repos/:owner/:repo/statuses/:sha`](/rest/reference/commits#create-a-commit-status) (:write)
|
||||
|
||||
### Permission on "team discussions"
|
||||
|
||||
|
||||
@@ -62,7 +62,7 @@ Request, grouped together with a state and optional body comment.
|
||||
|
||||
## Review comments
|
||||
|
||||
Pull request review comments are comments on a portion of the unified diff made during a pull request review. Commit comments and issue comments are different from pull request review comments. You apply commit comments directly to a commit and you apply issue comments without referencing a portion of the unified diff. For more information, see "[Create a commit comment](/rest/reference/repos#create-a-commit-comment)" and "[Create an issue comment](/rest/reference/issues#create-an-issue-comment)."
|
||||
Pull request review comments are comments on a portion of the unified diff made during a pull request review. Commit comments and issue comments are different from pull request review comments. You apply commit comments directly to a commit and you apply issue comments without referencing a portion of the unified diff. For more information, see "[Create a commit comment](/rest/reference/commits#create-a-commit-comment)" and "[Create an issue comment](/rest/reference/issues#create-an-issue-comment)."
|
||||
|
||||
### Custom media types for pull request review comments
|
||||
|
||||
|
||||
23
content/rest/reference/releases.md
Normal file
23
content/rest/reference/releases.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Releases
|
||||
intro: 'The releases API allows you to create, modify, and delete releases and release assets.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** The Releases API replaces the Downloads API. You can retrieve the download count and browser download URL from the endpoints in this API that return releases and release assets.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'releases' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
@@ -30,52 +30,6 @@ To help streamline your workflow, you can use the API to add autolinks to extern
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
## Branches
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'branches' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Collaborators
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'collaborators' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Comments
|
||||
|
||||
### Custom media types for commit comments
|
||||
|
||||
These are the supported media types for commit comments. You can read more
|
||||
about the use of media types in the API [here](/rest/overview/media-types).
|
||||
|
||||
application/vnd.github-commitcomment.raw+json
|
||||
application/vnd.github-commitcomment.text+json
|
||||
application/vnd.github-commitcomment.html+json
|
||||
application/vnd.github-commitcomment.full+json
|
||||
|
||||
For more information, see "[Custom media types](/rest/overview/media-types)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'comments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Commits
|
||||
|
||||
The Repo Commits API supports listing, viewing, and comparing commits in a repository.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'commits' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
## Community
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'community' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Contents
|
||||
|
||||
@@ -105,105 +59,12 @@ You can read more about the use of media types in the API [here](/rest/overview/
|
||||
{% if operation.subcategory == 'contents' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Deploy keys
|
||||
|
||||
{% data reusables.repositories.deploy-keys %}
|
||||
|
||||
Deploy keys can either be setup using the following API endpoints, or by using GitHub. To learn how to set deploy keys up in GitHub, see "[Managing deploy keys](/developers/overview/managing-deploy-keys)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'keys' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Deployments
|
||||
|
||||
Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a [`deployment` event](/developers/webhooks-and-events/webhook-events-and-payloads#deployment) that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).
|
||||
|
||||
Deployment statuses allow external services to mark deployments with an `error`, `failure`, `pending`, `in_progress`, `queued`, or `success` state that systems listening to [`deployment_status` events](/developers/webhooks-and-events/webhook-events-and-payloads#deployment_status) can consume.
|
||||
|
||||
Deployment statuses can also include an optional `description` and `log_url`, which are highly recommended because they make deployment statuses more useful. The `log_url` is the full URL to the deployment output, and
|
||||
the `description` is a high-level summary of what happened with the deployment.
|
||||
|
||||
GitHub dispatches `deployment` and `deployment_status` events when new deployments and deployment statuses are created. These events allows third-party integrations to receive respond to deployment requests and update the status of a deployment as progress is made.
|
||||
|
||||
Below is a simple sequence diagram for how these interactions would work.
|
||||
|
||||
```
|
||||
+---------+ +--------+ +-----------+ +-------------+
|
||||
| Tooling | | GitHub | | 3rd Party | | Your Server |
|
||||
+---------+ +--------+ +-----------+ +-------------+
|
||||
| | | |
|
||||
| Create Deployment | | |
|
||||
|--------------------->| | |
|
||||
| | | |
|
||||
| Deployment Created | | |
|
||||
|<---------------------| | |
|
||||
| | | |
|
||||
| | Deployment Event | |
|
||||
| |---------------------->| |
|
||||
| | | SSH+Deploys |
|
||||
| | |-------------------->|
|
||||
| | | |
|
||||
| | Deployment Status | |
|
||||
| |<----------------------| |
|
||||
| | | |
|
||||
| | | Deploy Completed |
|
||||
| | |<--------------------|
|
||||
| | | |
|
||||
| | Deployment Status | |
|
||||
| |<----------------------| |
|
||||
| | | |
|
||||
```
|
||||
|
||||
Keep in mind that GitHub is never actually accessing your servers. It's up to your third-party integration to interact with deployment events. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether they're responsible for pushing the code out to your servers, building native code, etc.
|
||||
|
||||
Note that the `repo_deployment` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to deployments and deployment statuses **without** granting access to repository code, while the {% ifversion not ghae %}`public_repo` and{% endif %}`repo` scopes grant permission to code as well.
|
||||
|
||||
|
||||
### Inactive deployments
|
||||
|
||||
When you set the state of a deployment to `success`, then all prior non-transient, non-production environment deployments in the same repository with the same environment name will become `inactive`. To avoid this, you can set `auto_inactive` to `false` when creating the deployment status.
|
||||
|
||||
You can communicate that a transient environment no longer exists by setting its `state` to `inactive`. Setting the `state` to `inactive` shows the deployment as `destroyed` in {% data variables.product.prodname_dotcom %} and removes access to it.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'deployments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.1 or ghae or ghec %}
|
||||
## Environments
|
||||
|
||||
The Environments API allows you to create, configure, and delete environments. For more information about environments, see "[Using environments for deployment](/actions/deployment/using-environments-for-deployment)." To manage environment secrets, see "[Secrets](/rest/reference/actions#secrets)."
|
||||
|
||||
{% data reusables.gated-features.environments %}
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'environments' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
## Forks
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'forks' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Invitations
|
||||
|
||||
The Repository Invitations API allows users or external services to invite other users to collaborate on a repo. The invited users (or external services on behalf of invited users) can choose to accept or decline the invitations.
|
||||
|
||||
Note that the `repo:invite` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted
|
||||
access to invitations **without** also granting access to repository code, while the
|
||||
`repo` scope grants permission to code as well as invitations.
|
||||
|
||||
### Invite a user to a repository
|
||||
|
||||
Use the API endpoint for adding a collaborator. For more information, see "[Add a repository collaborator](/rest/reference/repos#add-a-repository-collaborator)."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'invitations' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghae or ghes > 3.2 or ghec %}
|
||||
|
||||
## Git LFS
|
||||
@@ -214,181 +75,3 @@ Use the API endpoint for adding a collaborator. For more information, see "[Add
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Merging
|
||||
|
||||
The Repo Merging API supports merging branches in a repository. This accomplishes
|
||||
essentially the same thing as merging one branch into another in a local repository
|
||||
and then pushing to {% data variables.product.product_name %}. The benefit is that the merge is done on the server side and a local repository is not needed. This makes it more appropriate for automation and other tools where maintaining local repositories would be cumbersome and inefficient.
|
||||
|
||||
The authenticated user will be the author of any merges done through this endpoint.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'merging' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Pages
|
||||
|
||||
The {% data variables.product.prodname_pages %} API retrieves information about your {% data variables.product.prodname_pages %} configuration, and the statuses of your builds. Information about the site and the builds can only be accessed by authenticated owners{% ifversion not ghae %}, even if the websites are public{% endif %}. For more information, see "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages)."
|
||||
|
||||
In {% data variables.product.prodname_pages %} API endpoints with a `status` key in their response, the value can be one of:
|
||||
* `null`: The site has yet to be built.
|
||||
* `queued`: The build has been requested but not yet begun.
|
||||
* `building`:The build is in progress.
|
||||
* `built`: The site has been built.
|
||||
* `errored`: Indicates an error occurred during the build.
|
||||
|
||||
In {% data variables.product.prodname_pages %} API endpoints that return GitHub Pages site information, the JSON responses include these fields:
|
||||
* `html_url`: The absolute URL (including scheme) of the rendered Pages site. For example, `https://username.github.io`.
|
||||
* `source`: An object that contains the source branch and directory for the rendered Pages site. This includes:
|
||||
- `branch`: The repository branch used to publish your [site's source files](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). For example, _main_ or _gh-pages_.
|
||||
- `path`: The repository directory from which the site publishes. Will be either `/` or `/docs`.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'pages' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Releases
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** The Releases API replaces the Downloads API. You can retrieve the download count and browser download URL from the endpoints in this API that return releases and release assets.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'releases' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Statistics
|
||||
|
||||
The Repository Statistics API allows you to fetch the data that {% data variables.product.product_name %} uses for visualizing different
|
||||
types of repository activity.
|
||||
|
||||
### A word about caching
|
||||
|
||||
Computing repository statistics is an expensive operation, so we try to return cached
|
||||
data whenever possible. If the data hasn't been cached when you query a repository's
|
||||
statistics, you'll receive a `202` response; a background job is also fired to
|
||||
start compiling these statistics. Give the job a few moments to complete, and
|
||||
then submit the request again. If the job has completed, that request will receive a
|
||||
`200` response with the statistics in the response body.
|
||||
|
||||
Repository statistics are cached by the SHA of the repository's default branch; pushing to the default branch resets the statistics cache.
|
||||
|
||||
### Statistics exclude some types of commits
|
||||
|
||||
The statistics exposed by the API match the statistics shown by [different repository graphs](/github/visualizing-repository-data-with-graphs/about-repository-graphs).
|
||||
|
||||
To summarize:
|
||||
- All statistics exclude merge commits.
|
||||
- Contributor statistics also exclude empty commits.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'statistics' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
## Statuses
|
||||
|
||||
The status API allows external services to mark commits with an `error`,
|
||||
`failure`, `pending`, or `success` state, which is then reflected in pull requests
|
||||
involving those commits.
|
||||
|
||||
Statuses can also include an optional `description` and `target_url`, and
|
||||
we highly recommend providing them as they make statuses much more
|
||||
useful in the GitHub UI.
|
||||
|
||||
As an example, one common use is for continuous integration
|
||||
services to mark commits as passing or failing builds using status. The
|
||||
`target_url` would be the full URL to the build output, and the
|
||||
`description` would be the high level summary of what happened with the
|
||||
build.
|
||||
|
||||
Statuses can include a `context` to indicate what service is providing that status.
|
||||
For example, you may have your continuous integration service push statuses with a context of `ci`, and a security audit tool push statuses with a context of `security`. You can
|
||||
then use the [Get the combined status for a specific reference](/rest/reference/repos#get-the-combined-status-for-a-specific-reference) to retrieve the whole status for a commit.
|
||||
|
||||
Note that the `repo:status` [OAuth scope](/developers/apps/scopes-for-oauth-apps) grants targeted access to statuses **without** also granting access to repository code, while the
|
||||
`repo` scope grants permission to code as well as statuses.
|
||||
|
||||
If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the [Checks API](/rest/reference/checks).
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'statuses' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
## Traffic
|
||||
|
||||
For repositories that you have push access to, the traffic API provides access
|
||||
to the information provided in your repository graph. For more information, see "<a href="/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository" class="dotcom-only">Viewing traffic to a repository</a>."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'traffic' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
## Webhooks
|
||||
|
||||
Repository webhooks allow you to receive HTTP `POST` payloads whenever certain events happen in a repository. {% data reusables.webhooks.webhooks-rest-api-links %}
|
||||
|
||||
If you would like to set up a single webhook to receive events from all of your organization's repositories, see our API documentation for [Organization Webhooks](/rest/reference/orgs#webhooks).
|
||||
|
||||
In addition to the REST API, {% data variables.product.prodname_dotcom %} can also serve as a [PubSubHubbub](#pubsubhubbub) hub for repositories.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'webhooks' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
### Receiving Webhooks
|
||||
|
||||
In order for {% data variables.product.product_name %} to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.
|
||||
|
||||
#### Webhook headers
|
||||
|
||||
{% data variables.product.product_name %} will send along several HTTP headers to differentiate between event types and payload identifiers. See [webhook headers](/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers) for details.
|
||||
|
||||
### PubSubHubbub
|
||||
|
||||
GitHub can also serve as a [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub) hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL.
|
||||
Topic URLs for a GitHub repository's pushes are in this format:
|
||||
|
||||
`https://github.com/{owner}/{repo}/events/{event}`
|
||||
|
||||
The event can be any available webhook event. For more information, see "[Webhook events and payloads](/developers/webhooks-and-events/webhook-events-and-payloads)."
|
||||
|
||||
#### Response format
|
||||
|
||||
The default format is what [existing post-receive hooks should expect](/post-receive-hooks/): A JSON body sent as the `payload` parameter in a POST. You can also specify to receive the raw JSON body with either an `Accept` header, or a `.json` extension.
|
||||
|
||||
Accept: application/json
|
||||
https://github.com/{owner}/{repo}/events/push.json
|
||||
|
||||
#### Callback URLs
|
||||
|
||||
Callback URLs can use the `http://` protocol.
|
||||
|
||||
# Send updates to postbin.org
|
||||
http://postbin.org/123
|
||||
|
||||
#### Subscribing
|
||||
|
||||
The GitHub PubSubHubbub endpoint is: `{% data variables.product.api_url_code %}/hub`. A successful request with curl looks like:
|
||||
|
||||
``` shell
|
||||
curl -u "user" -i \
|
||||
{% data variables.product.api_url_pre %}/hub \
|
||||
-F "hub.mode=subscribe" \
|
||||
-F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
|
||||
-F "hub.callback=http://postbin.org/123"
|
||||
```
|
||||
|
||||
PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.
|
||||
|
||||
##### Parameters
|
||||
|
||||
Name | Type | Description
|
||||
-----|------|--------------
|
||||
``hub.mode``|`string` | **Required**. Either `subscribe` or `unsubscribe`.
|
||||
``hub.topic``|`string` |**Required**. The URI of the GitHub repository to subscribe to. The path must be in the format of `/{owner}/{repo}/events/{event}`.
|
||||
``hub.callback``|`string` | The URI to receive the updates to the topic.
|
||||
``hub.secret``|`string` | A shared secret key that generates a hash signature of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the {% ifversion fpt or ghes > 2.22 or ghec %}`X-Hub-Signature` or `X-Hub-Signature-256` headers{% elsif ghes < 3.0 %}`X-Hub-Signature` header{% elsif ghae %}`X-Hub-Signature-256` header{% endif %}. You can see [the PubSubHubbub documentation](https://pubsubhubbub.github.io/PubSubHubbub/pubsubhubbub-core-0.4.html#authednotify) for more details.
|
||||
|
||||
61
content/rest/reference/repository-metrics.md
Normal file
61
content/rest/reference/repository-metrics.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Repository metrics
|
||||
intro: 'The repository metrics API allows you to retrieve community profile, statistics, and traffic for your repository.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
## Community
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'community' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Statistics
|
||||
|
||||
The Repository Statistics API allows you to fetch the data that {% data variables.product.product_name %} uses for visualizing different
|
||||
types of repository activity.
|
||||
|
||||
### A word about caching
|
||||
|
||||
Computing repository statistics is an expensive operation, so we try to return cached
|
||||
data whenever possible. If the data hasn't been cached when you query a repository's
|
||||
statistics, you'll receive a `202` response; a background job is also fired to
|
||||
start compiling these statistics. Give the job a few moments to complete, and
|
||||
then submit the request again. If the job has completed, that request will receive a
|
||||
`200` response with the statistics in the response body.
|
||||
|
||||
Repository statistics are cached by the SHA of the repository's default branch; pushing to the default branch resets the statistics cache.
|
||||
|
||||
### Statistics exclude some types of commits
|
||||
|
||||
The statistics exposed by the API match the statistics shown by [different repository graphs](/github/visualizing-repository-data-with-graphs/about-repository-graphs).
|
||||
|
||||
To summarize:
|
||||
- All statistics exclude merge commits.
|
||||
- Contributor statistics also exclude empty commits.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'statistics' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
## Traffic
|
||||
|
||||
For repositories that you have push access to, the traffic API provides access
|
||||
to the information provided in your repository graph. For more information, see "<a href="/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository" class="dotcom-only">Viewing traffic to a repository</a>."
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'traffic' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
77
content/rest/reference/webhooks.md
Normal file
77
content/rest/reference/webhooks.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Webhooks
|
||||
intro: 'The webhooks API allows you to create and manage webhooks for your repositories.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- API
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
Repository webhooks allow you to receive HTTP `POST` payloads whenever certain events happen in a repository. {% data reusables.webhooks.webhooks-rest-api-links %}
|
||||
|
||||
If you would like to set up a single webhook to receive events from all of your organization's repositories, see our API documentation for [Organization Webhooks](/rest/reference/orgs#webhooks).
|
||||
|
||||
In addition to the REST API, {% data variables.product.prodname_dotcom %} can also serve as a [PubSubHubbub](#pubsubhubbub) hub for repositories.
|
||||
|
||||
{% for operation in currentRestOperations %}
|
||||
{% if operation.subcategory == 'webhooks' %}{% include rest_operation %}{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
### Receiving Webhooks
|
||||
|
||||
In order for {% data variables.product.product_name %} to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.
|
||||
|
||||
#### Webhook headers
|
||||
|
||||
{% data variables.product.product_name %} will send along several HTTP headers to differentiate between event types and payload identifiers. See [webhook headers](/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers) for details.
|
||||
|
||||
### PubSubHubbub
|
||||
|
||||
GitHub can also serve as a [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub) hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL.
|
||||
Topic URLs for a GitHub repository's pushes are in this format:
|
||||
|
||||
`https://github.com/{owner}/{repo}/events/{event}`
|
||||
|
||||
The event can be any available webhook event. For more information, see "[Webhook events and payloads](/developers/webhooks-and-events/webhook-events-and-payloads)."
|
||||
|
||||
#### Response format
|
||||
|
||||
The default format is what [existing post-receive hooks should expect](/post-receive-hooks/): A JSON body sent as the `payload` parameter in a POST. You can also specify to receive the raw JSON body with either an `Accept` header, or a `.json` extension.
|
||||
|
||||
Accept: application/json
|
||||
https://github.com/{owner}/{repo}/events/push.json
|
||||
|
||||
#### Callback URLs
|
||||
|
||||
Callback URLs can use the `http://` protocol.
|
||||
|
||||
# Send updates to postbin.org
|
||||
http://postbin.org/123
|
||||
|
||||
#### Subscribing
|
||||
|
||||
The GitHub PubSubHubbub endpoint is: `{% data variables.product.api_url_code %}/hub`. A successful request with curl looks like:
|
||||
|
||||
``` shell
|
||||
curl -u "user" -i \
|
||||
{% data variables.product.api_url_pre %}/hub \
|
||||
-F "hub.mode=subscribe" \
|
||||
-F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
|
||||
-F "hub.callback=http://postbin.org/123"
|
||||
```
|
||||
|
||||
PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.
|
||||
|
||||
##### Parameters
|
||||
|
||||
Name | Type | Description
|
||||
-----|------|--------------
|
||||
``hub.mode``|`string` | **Required**. Either `subscribe` or `unsubscribe`.
|
||||
``hub.topic``|`string` |**Required**. The URI of the GitHub repository to subscribe to. The path must be in the format of `/{owner}/{repo}/events/{event}`.
|
||||
``hub.callback``|`string` | The URI to receive the updates to the topic.
|
||||
``hub.secret``|`string` | A shared secret key that generates a hash signature of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the {% ifversion fpt or ghes > 2.22 or ghec %}`X-Hub-Signature` or `X-Hub-Signature-256` headers{% elsif ghes < 3.0 %}`X-Hub-Signature` header{% elsif ghae %}`X-Hub-Signature-256` header{% endif %}. You can see [the PubSubHubbub documentation](https://pubsubhubbub.github.io/PubSubHubbub/pubsubhubbub-core-0.4.html#authednotify) for more details.
|
||||
@@ -244,10 +244,10 @@ sections:
|
||||
- heading: API Changes
|
||||
notes:
|
||||
# https://github.com/github/releases/issues/1253
|
||||
- Pagination support has been added to the Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Repositories](/rest/reference/repos#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
- Pagination support has been added to the Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Commits](/rest/reference/commits#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
|
||||
# https://github.com/github/releases/issues/969
|
||||
- The REST API can now be used to programmatically resend or check the status of webhooks. For more information, see "[Repositories](/rest/reference/repos#webhooks)," "[Organizations](/rest/reference/orgs#webhooks)," and "[Apps](/rest/reference/apps#webhooks)" in the REST API documentation.
|
||||
- The REST API can now be used to programmatically resend or check the status of webhooks. For more information, see "[Webhooks](/rest/reference/webhooks)," "[Organizations](/rest/reference/orgs#webhooks)," and "[Apps](/rest/reference/apps#webhooks)" in the REST API documentation.
|
||||
|
||||
# https://github.com/github/releases/issues/1349
|
||||
- |
|
||||
|
||||
@@ -246,7 +246,7 @@ sections:
|
||||
- heading: API Changes
|
||||
notes:
|
||||
# https://github.com/github/releases/issues/1253
|
||||
- Pagination support has been added to the Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Repositories](/rest/reference/repos#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
- Pagination support has been added to the Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Commits](/rest/reference/commits#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
|
||||
# https://github.com/github/releases/issues/969
|
||||
- The REST API can now be used to programmatically resend or check the status of webhooks. For more information, see "[Repositories](/rest/reference/repos#webhooks)," "[Organizations](/rest/reference/orgs#webhooks)," and "[Apps](/rest/reference/apps#webhooks)" in the REST API documentation.
|
||||
|
||||
@@ -210,7 +210,7 @@ sections:
|
||||
- You can now use the REST API to configure custom autolinks to external resources. The REST API now provides beta `GET`/`POST`/`DELETE` endpoints which you can use to view, add, or delete custom autolinks associated with a repository. For more information, see "[Autolinks](/rest/reference/repos#autolinks)."
|
||||
|
||||
# https://github.com/github/releases/issues/1578
|
||||
- You can now use the REST API to sync a forked repository with its upstream repository. For more information, see "[Repositories](/rest/reference/repos#sync-a-fork-branch-with-the-upstream-repository)" in the REST API documentation.
|
||||
- You can now use the REST API to sync a forked repository with its upstream repository. For more information, see "[Branches](/rest/reference/branches#sync-a-fork-branch-with-the-upstream-repository)" in the REST API documentation.
|
||||
|
||||
# https://github.com/github/releases/issues/1527
|
||||
- Enterprise administrators on GitHub Enterprise Server can now use the REST API to enable or disable Git LFS for a repository. For more information, see "[Repositories](/rest/reference/repos#git-lfs)."
|
||||
|
||||
@@ -204,7 +204,7 @@ sections:
|
||||
- You can now use the REST API to configure custom autolinks to external resources. The REST API now provides beta `GET`/`POST`/`DELETE` endpoints which you can use to view, add, or delete custom autolinks associated with a repository. For more information, see "[Autolinks](/rest/reference/repos#autolinks)."
|
||||
|
||||
# https://github.com/github/releases/issues/1578
|
||||
- You can now use the REST API to sync a forked repository with its upstream repository. For more information, see "[Repositories](/rest/reference/repos#sync-a-fork-branch-with-the-upstream-repository)" in the REST API documentation.
|
||||
- You can now use the REST API to sync a forked repository with its upstream repository. For more information, see "[Branches](/rest/reference/branches#sync-a-fork-branch-with-the-upstream-repository)" in the REST API documentation.
|
||||
|
||||
# https://github.com/github/releases/issues/1527
|
||||
- Enterprise administrators on GitHub Enterprise Server can now use the REST API to enable or disable Git LFS for a repository. For more information, see "[Repositories](/rest/reference/repos#git-lfs)."
|
||||
|
||||
@@ -78,7 +78,7 @@ sections:
|
||||
- |
|
||||
With the [latest version of Octicons](https://github.com/primer/octicons/releases), the states of issues and pull requests are now more visually distinct so you can scan status more easily. For more information, see [{% data variables.product.prodname_blog %}](https://github.blog/changelog/2021-06-08-new-issue-and-pull-request-state-icons/).
|
||||
- |
|
||||
You can now see all pull request review comments in the **Files** tab for a pull request by selecting the **Conversations** drop-down. You can also require that all pull request review comments are resolved before anyone merges the pull request. For more information, see "[About pull request reviews](/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#discovering-and-navigating-conversations)" and "[About protected branches](/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-conversation-resolution-before-merging)." For more information about management of branch protection settings with the API, see "[Repositories](/rest/reference/repos#get-branch-protection)" in the REST API documentation and "[Mutations](/graphql/reference/mutations#createbranchprotectionrule)" in the GraphQL API documentation.
|
||||
You can now see all pull request review comments in the **Files** tab for a pull request by selecting the **Conversations** drop-down. You can also require that all pull request review comments are resolved before anyone merges the pull request. For more information, see "[About pull request reviews](/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#discovering-and-navigating-conversations)" and "[About protected branches](/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-conversation-resolution-before-merging)." For more information about management of branch protection settings with the API, see "[Branches](/rest/reference/branches#get-branch-protection)" in the REST API documentation and "[Mutations](/graphql/reference/mutations#createbranchprotectionrule)" in the GraphQL API documentation.
|
||||
- |
|
||||
You can now upload video files everywhere you write Markdown on {% data variables.product.product_name %}. Share demos, show reproduction steps, and more in issue and pull request comments, as well as in Markdown files within repositories, such as READMEs. For more information, see "[Attaching files](/github/writing-on-github/working-with-advanced-formatting/attaching-files)."
|
||||
- |
|
||||
@@ -103,7 +103,7 @@ sections:
|
||||
- |
|
||||
You can now sort the repositories on a user or organization profile by star count.
|
||||
- |
|
||||
The Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another, now supports pagination. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Repositories](/rest/reference/repos#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
The Repositories REST API's "compare two commits" endpoint, which returns a list of commits reachable from one commit or branch, but unreachable from another, now supports pagination. The API can also now return the results for comparisons over 250 commits. For more information, see the "[Commits](/rest/reference/commits#compare-two-commits)" REST API documentation and "[Traversing with pagination](/rest/guides/traversing-with-pagination)."
|
||||
- |
|
||||
When you define a submodule in {% data variables.product.product_location %} with a relative path, the submodule is now clickable in the web UI. Clicking the submodule in the web UI will take you to the linked repository. Previously, only submodules with absolute URLs were clickable. Relative paths for repositories with the same owner that follow the pattern <code>../<em>REPOSITORY</em></code> or relative paths for repositories with a different owner that follow the pattern <code>../<em>OWNER</em>/<em>REPOSITORY</em></code> are supported. For more information about working with submodules, see [Working with submodules](https://github.blog/2016-02-01-working-with-submodules/) on {% data variables.product.prodname_blog %}.
|
||||
- |
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`action`|`string` | The action performed. Can be `created`.
|
||||
`comment`|`object` | The [commit comment](/rest/reference/repos#get-a-commit-comment) resource.
|
||||
`comment`|`object` | The [commit comment](/rest/reference/commits#get-a-commit-comment) resource.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Key | Type | Description
|
||||
----|------|-------------
|
||||
`action` |`string` | The action performed. Can be either `created` or `deleted`.
|
||||
`key` |`object` | The [`deploy key`](/rest/reference/repos#get-a-deploy-key) resource.
|
||||
`key` |`object` | The [`deploy key`](/rest/reference/deployments#get-a-deploy-key) resource.
|
||||
|
||||
@@ -1 +1 @@
|
||||
A deployment is created. {% data reusables.webhooks.action_type_desc %} For more information, see the "[deployment](/rest/reference/repos#list-deployments)" REST API.
|
||||
A deployment is created. {% data reusables.webhooks.action_type_desc %} For more information, see the "[deployment](/rest/reference/deployments#list-deployments)" REST API.
|
||||
|
||||
@@ -1 +1 @@
|
||||
A deployment is created. {% data reusables.webhooks.action_type_desc %} For more information, see the "[deployment statuses](/rest/reference/repos#list-deployment-statuses)" REST API.
|
||||
A deployment is created. {% data reusables.webhooks.action_type_desc %} For more information, see the "[deployment statuses](/rest/reference/deployments#list-deployment-statuses)" REST API.
|
||||
|
||||
@@ -8,6 +8,17 @@ import { readCompressedJsonFileFallback } from '../read-json-file.js'
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url))
|
||||
const schemasPath = path.join(__dirname, 'static/decorated')
|
||||
|
||||
export const restRepoCategoryExceptions = [
|
||||
'branches',
|
||||
'collaborators',
|
||||
'commits',
|
||||
'deployments',
|
||||
'pages',
|
||||
'releases',
|
||||
'repository-metrics',
|
||||
'webhooks',
|
||||
]
|
||||
|
||||
export default async function getRest() {
|
||||
const operations = {}
|
||||
fs.readdirSync(schemasPath).forEach((filename) => {
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import path from 'path'
|
||||
import getRest from '../../lib/rest/index.js'
|
||||
import getRest, { restRepoCategoryExceptions } from '../../lib/rest/index.js'
|
||||
import removeFPTFromPath from '../../lib/remove-fpt-from-path.js'
|
||||
|
||||
// Global cache to avoid calling getRest() more than once
|
||||
@@ -24,11 +24,16 @@ export default async function restContext(req, res, next) {
|
||||
if (!req.pagePath.includes('rest/reference')) return next()
|
||||
|
||||
// e.g. the `activity` from `/en/rest/reference/activity#events`
|
||||
const category = req.pagePath
|
||||
let category = req.pagePath
|
||||
.split('rest/reference')[1]
|
||||
.replace(/^\//, '') // remove leading slash
|
||||
.split('/')[0]
|
||||
|
||||
// override the category if the category is in the restRepoCategoryExceptions list
|
||||
if (restRepoCategoryExceptions.includes(category)) {
|
||||
category = 'repos'
|
||||
}
|
||||
|
||||
// ignore empty strings or bare `/`
|
||||
if (!category || category.length < 2) return next()
|
||||
|
||||
|
||||
4
tests/fixtures/rss-feed.xml
vendored
4
tests/fixtures/rss-feed.xml
vendored
@@ -76,8 +76,8 @@
|
||||
<guid isPermaLink="false">https://github.blog/changelog/2021-03-22-compare-rest-api-now-supports-pagination</guid>
|
||||
|
||||
<description><![CDATA[Compare REST API now supports pagination]]></description>
|
||||
<content:encoded><![CDATA[<p>The <a href="https://docs.github.com/rest/reference/repos#compare-two-commits">"Compare two commits"</a> REST API, which returns a list of commits reachable from one commit (or branch) but not reachable from another, now supports pagination. It can also now return the results for comparisons over 250 commits.</p>
|
||||
<p>To learn more, see the <a href="https://docs.github.com/rest/reference/repos#compare-two-commits">compare two commits</a> API reference or the guide for <a href="https://docs.github.com/en/rest/guides/traversing-with-pagination">using pagination</a>.</p>
|
||||
<content:encoded><![CDATA[<p>The <a href="https://docs.github.com/rest/reference/commits#compare-two-commits">"Compare two commits"</a> REST API, which returns a list of commits reachable from one commit (or branch) but not reachable from another, now supports pagination. It can also now return the results for comparisons over 250 commits.</p>
|
||||
<p>To learn more, see the <a href="https://docs.github.com/rest/reference/commits#compare-two-commits">compare two commits</a> API reference or the guide for <a href="https://docs.github.com/en/rest/guides/traversing-with-pagination">using pagination</a>.</p>
|
||||
]]></content:encoded>
|
||||
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ import fs from 'fs/promises'
|
||||
import { difference, isPlainObject } from 'lodash-es'
|
||||
import { getJSON } from '../helpers/supertest.js'
|
||||
import enterpriseServerReleases from '../../lib/enterprise-server-releases.js'
|
||||
import getRest from '../../lib/rest/index.js'
|
||||
import getRest, { restRepoCategoryExceptions } from '../../lib/rest/index.js'
|
||||
import { jest } from '@jest/globals'
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url))
|
||||
@@ -28,6 +28,7 @@ describe('REST references docs', () => {
|
||||
!excludeFromResourceNameCheck.find((excludedFile) => filename.endsWith(excludedFile))
|
||||
)
|
||||
.map((filename) => filename.replace('.md', ''))
|
||||
.filter((filename) => !restRepoCategoryExceptions.includes(filename))
|
||||
|
||||
const missingResource =
|
||||
'Found a markdown file in content/rest/reference that is not represented by an OpenAPI REST operation category.'
|
||||
|
||||
Reference in New Issue
Block a user