diff --git a/content/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-applications.md b/content/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-applications.md index 443f4086b38e..b2c8c7f69532 100644 --- a/content/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-applications.md +++ b/content/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-applications.md @@ -6,6 +6,7 @@ redirect_from: - /enterprise/admin/configuration/configuring-applications - /admin/configuration/configuring-applications - /admin/configuration/configuring-your-enterprise/configuring-applications + - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-interactive-maps versions: ghes: '*' type: how_to diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md index d598495c0af2..cea0364e0419 100644 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md +++ b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md @@ -8,7 +8,7 @@ type: how_to topics: - Enterprise - Repositories -shortTitle: Access user-owned repos +shortTitle: Access user-owned repositories redirect_from: - /admin/user-management/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise --- diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md index 3d35e07f0b5c..0f6d21bc4524 100644 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md +++ b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md @@ -8,7 +8,7 @@ type: how_to topics: - Enterprise - Repositories -shortTitle: View user-owned repos +shortTitle: View user-owned repositories redirect_from: - /admin/user-management/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise --- diff --git a/content/admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs.md b/content/admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs.md index 9990f94dfb7a..597d3b07cb70 100644 --- a/content/admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs.md +++ b/content/admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs.md @@ -46,10 +46,8 @@ In addition to reviewing your system logs, you can monitor activity on your inst - [Log files for the {% data variables.product.prodname_dotcom %} application](#log-files-for-the-github-application) - [Log files for the HTTP server](#log-files-for-the-http-server) - [Log files for instance configuration](#log-files-for-instance-configuration) -- [Log files for the {% data variables.enterprise.management_console %}](#log-files-for-themanagement-console) +- [Log files for the {% data variables.enterprise.management_console %}](#log-files-for-the-management-console) - [Log files for search](#log-files-for-search) -- [Log files for storage](#log-files-for-storage) -- [Log files for webhooks](#log-files-for-webhooks) - [Log files for system services](#log-files-for-system-services) {% ifversion ghes < 3.9 %} @@ -117,7 +115,10 @@ The following log files contain events related to the configuration of your inst | Path | Description | | :- | :- | -| 
/data/user/common/ghe-config.log
| Records events associated with each configuration run. If a configuration run fails, output to the log stops. This log also records information about migrations that run during the process of upgrading an instance's software. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config-apply)." | +| 
/data/user/common/ghe-config.log
| Records events associated with {% ifversion unique-config-run-logs %}the latest{% else %}each{% endif %} configuration run. If a configuration run fails, output to the log stops. This log also records information about migrations that run during the process of upgrading an instance's software. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config-apply)." | +{%- ifversion unique-config-run-logs %} +| 
/data/user/config-apply/logs/YYYYMMDD/*
| Stores log files for previous configuration runs. The instance stores the files in a directory that reflects the date, and each file name reflects the node and the ID of the run. | +{%- endif %} ### Log files for search @@ -133,7 +134,7 @@ The following log files contain events related to webhooks that your instance se | Service name | Description | | :- | :- | -| `hookshot-go` | Records events for all webhook activity on the instance, including triggered webhooks, deliveries, and failures.| +| 
hookshot-go
| Records events for all webhook activity on the instance, including triggered webhooks, deliveries, and failures.| ### Log files for system services diff --git a/content/billing/managing-billing-for-github-actions/about-billing-for-github-actions.md b/content/billing/managing-billing-for-github-actions/about-billing-for-github-actions.md index 43712a3af634..9de2421a3443 100644 --- a/content/billing/managing-billing-for-github-actions/about-billing-for-github-actions.md +++ b/content/billing/managing-billing-for-github-actions/about-billing-for-github-actions.md @@ -33,7 +33,7 @@ Minutes reset every month, while storage usage does not. {% note %} -**Note**: Included minutes cannot be used for larger runners. These runners will always be charged for, including in public repos. For more information, see "[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates)." +**Note**: Included minutes cannot be used for larger runners. These runners will always be charged for, including in public repositories. For more information, see "[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates)." {% endnote %} diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md index 4a8433b40879..cb2e4645def2 100644 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md +++ b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md @@ -116,7 +116,7 @@ If you want to use the latest {% data variables.product.prodname_codeql %} featu ## Downloading databases from {% data variables.product.prodname_dotcom_the_website %} -{% data variables.product.prodname_dotcom %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repos on {% data variables.product.prodname_dotcom_the_website %}, which you can download using the REST API. The list of repos is constantly growing and evolving to make sure that it includes the most interesting codebases for security research. +{% data variables.product.prodname_dotcom %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repositories on {% data variables.product.prodname_dotcom_the_website %}, which you can download using the REST API. The list of repositories is constantly growing and evolving to make sure that it includes the most interesting codebases for security research. You can also analyze databases from {% data variables.product.prodname_dotcom_the_website %} using the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension. For more information, see "[Analyzing your projects](https://codeql.github.com/docs/codeql-for-visual-studio-code/analyzing-your-projects)." diff --git a/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md b/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md index de341c650d63..228941262967 100644 --- a/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md +++ b/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md @@ -24,7 +24,7 @@ shortTitle: Add a security policy To give people instructions for reporting security vulnerabilities in your project,{% ifversion fpt or ghes or ghec %} you can add a `SECURITY.md` file to your repository's root, `docs`, or `.github` folder.{% else %} you can add a `SECURITY.md` file to your repository's root, or `docs` folder.{% endif %} When someone creates an issue in your repository, they will see a link to your project's security policy. {% ifversion not ghae %} - + You can create a default security policy for your organization or personal account. For more information, see "[AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)." {% endif %} diff --git a/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md b/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md index 6daec1824b2b..af37073327c8 100644 --- a/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md +++ b/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md @@ -7,7 +7,7 @@ versions: type: reference topics: - Codespaces -shortTitle: Authenticating to repos +shortTitle: Authenticating to repositories --- When you create a codespace for a repository, you can generally use `git pull` and `git push` to pull and push changes to that repository without any additional authentication. However, occasionally you may see authentication errors when trying to run these operations. @@ -59,7 +59,7 @@ To use the token to authenticate in your codespace, you have the following optio ``` This will store the access token for the specific repository, so you will be able to push to and pull from the repository without overriding the existing credential helper. - + {% note %} **Note:** If you clone in this way, the token will be visible in your Git configuration. You should only use this method when working in a codespace created from a repository you trust, and you should limit the scope of the access token as much as possible. diff --git a/content/desktop/adding-and-cloning-repositories/index.md b/content/desktop/adding-and-cloning-repositories/index.md index 37235eda89e1..6864ea330b09 100644 --- a/content/desktop/adding-and-cloning-repositories/index.md +++ b/content/desktop/adding-and-cloning-repositories/index.md @@ -11,6 +11,5 @@ children: - /adding-an-existing-project-to-github-using-github-desktop - /cloning-and-forking-repositories-from-github-desktop - /cloning-a-repository-from-github-to-github-desktop -shortTitle: Add & clone repos +shortTitle: Add & clone repositories --- - diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md index dfab0a5f3255..578c8f55980f 100644 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md +++ b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md @@ -102,6 +102,6 @@ Clones starter code repo used by an assignment. By default, the starter code is gh classroom clone student-repos ``` -Clones student repositories from a given assignment. By default, the student repos are cloned into the current directory a directory named after the assignment slug. To clone into a different directory, use the `--directory` flag. If the directory does not exists, it will be created. +Clones student repositories from a given assignment. By default, the student repositories are cloned into the current directory a directory named after the assignment slug. To clone into a different directory, use the `--directory` flag. If the directory does not exists, it will be created. By default, results are paginated by 30. To get a different number of repositories, use the `--per-page NUMBER` flag. diff --git a/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md b/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md index 8c116c45aa49..759ab7b5068a 100644 --- a/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md +++ b/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md @@ -16,7 +16,7 @@ versions: ghec: '*' topics: - Repositories -shortTitle: Save repos with stars +shortTitle: Save repositories with stars --- You can search, sort, and filter your starred repositories and topics on your {% data variables.explore.your_stars_page %}. diff --git a/content/github-cli/github-cli/quickstart.md b/content/github-cli/github-cli/quickstart.md index abeb8a83197c..8a0c0923a52c 100644 --- a/content/github-cli/github-cli/quickstart.md +++ b/content/github-cli/github-cli/quickstart.md @@ -19,26 +19,7 @@ shortTitle: Quickstart ## Prerequisites -1. Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository. -1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %} - - {%- ifversion fpt or ghec %} - - ```shell - gh auth login - ``` - - {%- else %} - - ```shell - gh auth login --hostname HOSTNAME - ``` - - {%- endif %} - -1. Follow the on-screen prompts. - - {% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use `git push`, `git pull`, and so on, without needing to set up a separate credential manager or use SSH. +{% data reusables.rest-api.github-cli-install-and-auth %} ## Some useful commands @@ -101,7 +82,7 @@ You can change configuration settings and add aliases or extensions, to make {% - Enter `gh config set SUBCOMMANDS` to configure {% data variables.product.prodname_cli %}'s settings, replacing `SUBCOMMANDS` with the setting you want to adjust. For example, you can specify the text editor that's used when a {% data variables.product.prodname_cli %} command requires you to edit text - such as when you add the body text for a new issue you're creating. To set your preferred text editor to {% data variables.product.prodname_vscode %} enter `gh config set editor "code -w"`. The `-w` (or `--wait`) flag in this example causes the command to wait for the file to be closed in {% data variables.product.prodname_vscode %} before proceeding with the next step in your terminal. - + For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set). - Define aliases for commands that you commonly run. For example, if you run `gh alias set prd "pr create --draft"`, you will then be able to run `gh prd` to quickly open a draft pull request. For more information, see [`gh alias`](https://cli.github.com/manual/gh_alias). diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md index 6f91de6e345d..1305db75581b 100644 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ b/content/graphql/guides/forming-calls-with-graphql.md @@ -23,7 +23,7 @@ You can authenticate to the GraphQL API using a {% data variables.product.pat_ge To authenticate with a {% data variables.product.pat_generic %}, follow the steps in "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." The data that you are requesting will dictate which scopes {% ifversion pat-v2 %}or permissions {% endif %}you will need. {% ifversion pat-v2 %} -For example, select the "issues:read" permission to read all of the issues in the repos your token has access to. +For example, select the "issues:read" permission to read all of the issues in the repositories your token has access to. All {% data variables.product.pat_v2 %}s include read access to public repositories. To access public repositories with a {% data variables.product.pat_v1 %}, select the "public_repo" scope. diff --git a/content/rest/guides/getting-started-with-the-rest-api.md b/content/rest/guides/getting-started-with-the-rest-api.md index e15943fc7b12..aa7dc9790d36 100644 --- a/content/rest/guides/getting-started-with-the-rest-api.md +++ b/content/rest/guides/getting-started-with-the-rest-api.md @@ -1,5 +1,6 @@ --- title: Getting started with the REST API +shortTitle: Using the API intro: 'Learn how to use the {% data variables.product.prodname_dotcom %} REST API.' versions: fpt: '*' @@ -8,533 +9,450 @@ versions: ghec: '*' topics: - API -shortTitle: Using the API --- -## About the {% data variables.product.prodname_dotcom %} REST API +## Introduction -This article describes how to use the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, JavaScript, or `curl`. For a quickstart guide, see "[AUTOTITLE](/rest/quickstart)." +This article describes how to use the {% data variables.product.prodname_dotcom %} REST API with {% data variables.product.prodname_cli %}, `curl`, or JavaScript. For a quickstart guide, see "[AUTOTITLE](/rest/quickstart)." -When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body. +## About requests to the REST API -The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation. For more information, see the [REST reference documentation](/rest). +This section describes the elements that make up an API request: -For more information about {% data variables.product.company_short %}'s APIs, see "[AUTOTITLE](/rest/overview/about-githubs-apis)." +- [HTTP method](#http-method) +- [Path](#path) +- [Headers](#headers) +- [Media types](#media-types) +- [Authentication](#authentication) +- [Parameters](#parameters) -## Making a request +Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters. -To make a request, first find the HTTP method and the path for the operation that you want to use. For example, the "Get Octocat" operation uses the `GET` method and the `/octocat` path. For the full reference documentation for this operation, see "[AUTOTITLE](/rest/meta#get-octocat)." +The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the [REST reference documentation](/rest). -{% cli %} +### HTTP method -{% note %} +The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are `GET`, `POST`, `DELETE`, and `PATCH`. The REST API reference documentation provides the HTTP method for every endpoint. -**Note**: You must install {% data variables.product.prodname_cli %} in order to use the commands in the {% data variables.product.prodname_cli %} examples. For installation instructions, see the [{% data variables.product.prodname_cli %} repository](https://github.com/cli/cli#installation). +For example, the HTTP method for the ["List repository issues" endpoint]([AUTOTITLE](/rest/issues/issues#list-repository-issues) is `GET`." -{% endnote %} +Where possible, the {% data variables.product.product_name %} REST API strives to use an appropriate HTTP method for each action. -If you are not already authenticated to {% data variables.product.prodname_cli %}, you must use the `gh auth login` subcommand to authenticate before making any requests. For more information, see "[Authenticating](#authenticating)." +- `GET`: Used for retrieving resources. +- `POST`: Used for creating resources. +- `PATCH`: Used for updating properties of resources. +- `PUT`: Used for replacing resources or collections of resources. +- `DELETE`: Used for deleting resources. -To make a request using {% data variables.product.prodname_cli %}, use the `api` subcommand along with the path. Use the `--method` or `-X` flag to specify the method. +### Path -```shell -gh api /octocat --method GET -``` - -{% endcli %} +Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path for the ["List repository issues" endpoint](/rest/issues/issues#list-repository-issues) is `/repos/{owner}/{repo}/issues`. -{% javascript %} +The curly brackets `{}` in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request. For example, the path parameters for the ["List repository issues" endpoint](/rest/issues/issues#list-repository-issues) are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to request a list of issues, and replace `{owner}` with the name of the account that owns the repository. -{% note %} +### Headers -**Note**: You must install and import `octokit` in order to use the Octokit.js library used in the JavaScript examples. For more information, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). +Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the {% data variables.product.prodname_dotcom %} REST API. For an example of a request that uses headers, see "[Making a request](#making-a-request)." -{% endnote %} +#### `Accept` -To make a request using JavaScript, you can use Octokit.js. For more information, see "[AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript)." +Most {% data variables.product.prodname_dotcom %} REST API endpoints specify that you should pass an `Accept` header with a value of `application/vnd.github+json`. The value of the `Accept` header is a media type. For more information about media types, see "[Media types](#media-types)." -First, create an instance of `Octokit`.{% ifversion ghes or ghae %} Set the base URL to `{% data variables.product.api_url_code %}`. Replace `[hostname]` with the name of {% data variables.location.product_location %}.{% endif %} +{% ifversion api-date-versioning %} -```javascript -const octokit = new Octokit({ {% ifversion ghes or ghae %} - baseUrl: "{% data variables.product.api_url_code %}", -{% endif %}}); -``` +#### `X-GitHub-Api-Version` -Then, use the `request` method to make requests. Pass the HTTP method and path as the first argument. +You should use this header to specify a version of the REST API to use for your request. For more information, see "[AUTOTITLE](/rest/overview/api-versions)." -```javascript -await octokit.request("GET /octocat", {}); -``` +{% endif %} -{% endjavascript %} +{% ifversion fpt or ghec %} -{% curl %} +#### `User-Agent` -Prepend the base URL for the {% data variables.product.prodname_dotcom %} REST API, `{% data variables.product.api_url_code %}`, to the path to get the full URL: `{% data variables.product.api_url_code %}/octocat`.{% ifversion ghes or ghae %} Replace `[hostname]` with the name of {% data variables.location.product_location %}.{% endif %} +All API requests must include a valid `User-Agent` header. The `User-Agent` header identifies the user or application that is making the request. -Use the `curl` command in your command line. Use the `--request` or `-X` flag followed by the HTTP method. Use the `--url` flag followed by the full URL. +{% cli %} -```shell -curl --request GET \ ---url "https://api.github.com/octocat" -``` +By default, {% data variables.product.prodname_cli %} sends a valid `User-Agent` header. However, {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.product_name %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. -{% note %} +{% endcli %} -**Note**: If you get a message similar to "command not found: curl", you may need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html). +{% curl %} -{% endnote %} +By default, `curl` sends a valid `User-Agent` header. However {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.product_name %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. {% endcurl %} -Continue reading to learn how to authenticate, send parameters, and use the response. - -## Authenticating - -Many operations require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.{% cli %} Although some REST API operations are accessible without authentication, you must authenticate to {% data variables.product.prodname_cli %} in order to use the `api` subcommand.{% endcli %} - -### About tokens - -You can authenticate your request by adding a token. - -If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. The REST API operations used in this article require `repo` scope for {% data variables.product.pat_v1_plural %}{% ifversion pat-v2 %} or, unless otherwise noted, read-only access to public repositories for {% data variables.product.pat_v2 %}s{% endif %}. Other operations may require different scopes{% ifversion pat-v2%} or permissions{% endif %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." - -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an operation is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require `issues` read and write permissions for {% data variables.product.prodname_github_apps %}. Other operations may require different permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." - -If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)." - -For more information about best practices you can use to keep your tokens secure, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)." +{% javascript %} -### Authentication example +If you use the Octokit.js SDK, the SDK will send a valid `User-Agent` header for you. However, {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.product_name %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. -{% cli %} +{% endjavascript %} -With {% data variables.product.prodname_cli %}, you don't need to create an access token in advance. Use the `auth login` subcommand to authenticate to {% data variables.product.prodname_cli %}: +The following is an example `User-Agent` for an app named `Awesome-Octocat-App`: ```shell -gh auth login +User-Agent: Awesome-Octocat-App ``` -You can use the `--scopes` flag to specify what scopes you want. If you want to authenticate with a token that you created, you can use the `--with-token` flag. For more information, see the [{% data variables.product.prodname_cli %} `auth login` documentation](https://cli.github.com/manual/gh_auth_login). +Requests with no `User-Agent` header will be rejected. If you provide an invalid `User-Agent` header, you will receive a `403 Forbidden` response. -{% endcli %} +{% endif %} -{% javascript %} + + -{% warning %} +### Media types -**Warning**: Treat your access token like a password. +You can specify one or more media types by adding them to the `Accept` header of your request. For more information about the `Accept` header, see "[`Accept`](#accept)." -To keep your token secure, you can store your token as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." +Media types specify the format of the data you want to consume from the API. Media types are specific to resources, allowing them to change independently and support formats that other resources don't. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe the media types that it supports. For more information, see the "[AUTOTITLE](/rest)." -{% ifversion ghec or fpt %}You can also store your token as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."{% endif %} +The most common media types supported by the {% data variables.product.prodname_dotcom %} REST API are `application/vnd.github+json` and `application/json`. -If these options are not possible, consider using another CLI service to store your token securely. +There are other custom media types that you can use with some endpoints. For example, some endpoints support the media types `full`, `raw`, `text`, or `html`. And the REST API to manage [commits](/rest/commits/commits#get-a-commit) and [pull requests](/rest/pulls/pulls) support the media types `diff`, `patch`, and `sha`. -{% endwarning %} +All custom media types for {% data variables.product.product_name %} look like this: `application/vnd.github.PARAM+json`, where `PARAM` is the name of the media type. For example, to specify the `raw` media type, you would use `application/vnd.github.raw+json`. -To authenticate with the Octokit.js library, you can pass your token when you create an instance of `Octokit`. Replace `YOUR-TOKEN` with your token.{% ifversion ghes or ghae %} Replace `[hostname]` with the name of {% data variables.location.product_location %}.{% endif %} +For an example of a request that uses media types, see "[Making a request](#making-a-request)." -```javascript -const octokit = new Octokit({ {% ifversion ghes or ghae %} - baseUrl: "{% data variables.product.api_url_code %}",{% endif %} - auth: 'YOUR-TOKEN', -}); -``` +### Authentication -{% endjavascript %} +Many endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated. {% curl %} -{% warning %} - -**Warning**: Treat your access token like a password. - -To help keep your account secure, you can use {% data variables.product.prodname_cli %} instead of `curl` commands. {% data variables.product.prodname_cli %} will take care of authentication for you. For more information, see the {% data variables.product.prodname_cli %} version of this page. - -{% ifversion ghec or fpt %}You can also store your token as a {% data variables.product.prodname_codespaces %} secret and use the command line through {% data variables.product.prodname_codespaces %}. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."{% endif %} - -If these options are not possible, consider using another CLI service to store your token securely. - -{% endwarning %} - -In `curl` commands, you will send an `Authorization` header with your token. Replace `YOUR-TOKEN` with your token: +To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)." -```shell -curl --request GET \ ---url "https://api.github.com/octocat" \ ---header "Authorization: Bearer YOUR-TOKEN" -``` +For an example of a request that uses an authentication token, see "[Making a request](#making-a-request)." {% note %} -**Note:** {% data reusables.getting-started.bearer-vs-token %} +**Note:** If you don't want to create a token, you can use {% data variables.product.prodname_cli %}. {% data variables.product.prodname_cli %} will take care of authentication for you, and help keep your account secure. For more information, see the [{% data variables.product.prodname_cli %} version of this page](/rest/guides/getting-started-with-the-rest-api?tool=cli). {% endnote %} -{% endcurl %} +{% warning %} -### Authentication example for {% data variables.product.prodname_actions %} +**Warning:** Treat your access token the same way you would treat your passwords or other sensitive credentials. For more information, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)." -{% cli %} +{% endwarning %} -You can also use the `run` keyword to execute {% data variables.product.prodname_cli %} commands in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." +{% endcurl %} -Instead of using the `gh auth login` command, pass your token as an environment variable called `GH_TOKEN`. {% data variables.product.prodname_dotcom %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." +{% cli %} -```yaml -jobs: - use_api: - runs-on: ubuntu-latest - permissions: {} - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - gh api /octocat -``` +Although some REST API endpoints are accessible without authentication, {% data variables.product.prodname_cli %} requires you to authenticate before you can use the `api` subcommand to make an API request. Use the `auth login` subcommand to authenticate to {% data variables.product.product_name %}. For more information, see "[Making a request](#making-a-request)." {% endcli %} {% javascript %} -You can also use the `run` keyword to execute your JavaScript scripts in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." - -{% data variables.product.prodname_dotcom %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." - -The following example workflow: +To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)." -1. Checks out the repository content -1. Sets up Node.js -1. Installs `octokit` -1. Stores the value of `GITHUB_TOKEN` as an environment variable called `TOKEN` and runs `.github/actions-scripts/use-the-api.mjs`, which can access that environment variable as `process.env.TOKEN` +For an example of a request that uses an authentication token, see "[Making a request](#making-a-request)." -Example workflow: +{% warning %} -```yaml -on: - workflow_dispatch: -jobs: - use_api_via_script: - runs-on: ubuntu-latest - permissions: {} - steps: - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} +**Warning:** Treat your access token the same way you would treat your passwords or other sensitive credentials. For more information, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)." - - name: Setup Node - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '16.17.0' - cache: npm +{% endwarning %} - - name: Install dependencies - run: npm install octokit +{% endjavascript %} - - name: Run script - env: - TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - node .github/actions-scripts/use-the-api.mjs -``` +### Parameters -Example JavaScript script, with the file path `.github/actions-scripts/use-the-api.mjs`: +Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, body parameters, and query parameters. -```javascript -import { Octokit } from "octokit"; +#### Path parameters -const octokit = new Octokit({ {% ifversion ghes or ghae %} - baseUrl: "{% data variables.product.api_url_code %}",{% endif %} - auth: process.env.TOKEN, -}); +Path parameters modify the endpoint path. These parameters are required in your request. For more information, see "[Path](#path)." -await octokit.request("GET /octocat", {}); -``` +#### Body parameters -Instead of storing your script in a separate file and executing the script from your workflow, you can use the `actions/github-script` action to run a script. For more information, see the [actions/github-script README](https://github.com/actions/github-script). - -```yaml -jobs: - use_api_via_script: - runs-on: ubuntu-latest - permissions: {} - steps: - - uses: {% data reusables.actions.action-github-script %} - with: - github-token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - script: | - await github.request('GET /octocat', {}) -``` +Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. For example, a body parameter may allow you to specify an issue title when creating a new issue, or specify certain settings when enabling or disabling a feature. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe the body parameters that it supports. For more information, see the "[AUTOTITLE](/rest)." -{% endjavascript %} +For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) requires that you specify a title for the new issue in your request. It also allows you to optionally specify other information, such as text to put in the issue body, users to assign to the new issue, or labels to apply to the new issue. For an example of a request that uses body parameters, see "[Making a request](#making-a-request)." -{% curl %} +You must authenticate your request to pass body parameters. For more information, see "[Authenticating](#authenticating)." -You can also use the `run` keyword to execute `curl` commands in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." - -{% data variables.product.prodname_dotcom %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." - -```yaml -jobs: - use_api: - runs-on: ubuntu-latest - permissions: {} - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - curl --request GET \ - --url "https://api.github.com/octocat" \ - --header "Authorization: Bearer $GH_TOKEN" -``` +#### Query parameters -{% endcurl %} +Query parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe any query parameters that it supports. For more information, see the "[AUTOTITLE](/rest)." -## Using headers +For example, the ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. You can use the `per_page` query parameter to return two issues instead of 30. You can use the `page` query parameter to fetch only the first page of results. For an example of a request that uses query parameters, see "[Making a request](#making-a-request)." -Most operations specify that you should pass an `Accept` header with a value of `application/vnd.github+json`. Other operations may specify that you should send a different `Accept` header or additional headers. +## Making a request {% cli %} -To send a header with {% data variables.product.prodname_cli %}, use the `--header` or `-H` flag followed by the header in `key: value` format. +This section demonstrates how to make an authenticated request to the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}. -```shell -gh api --header 'Accept: application/vnd.github+json'{% ifversion api-date-versioning %} --header 'X-GitHub-Api-Version:{{ allVersions[currentVersion].latestApiVersion }}'{% endif %} --method GET /octocat -``` +### 1. Setup -{% endcli %} +Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository. -{% javascript %} +### 2. Authenticate -The Octokit.js library automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` property to the object that is passed as a second argument to the `request` method. The value of the `headers` property is an object with the header names as keys and header values as values. For example, to send a `content-type` header with a value of `text/plain`: +1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %} -```javascript -await octokit.request("GET /octocat", { - headers: { - "content-type": "text/plain",{% ifversion api-date-versioning %} - "X-GitHub-Api-Version": "{{ allVersions[currentVersion].latestApiVersion }}",{% endif %} - }, -}); -``` + {%- ifversion ghes or ghae %} -{% endjavascript %} + ```shell copy + gh auth login --hostname HOSTNAME + ``` -{% curl %} + {%- else %} -To send a header in a `curl` command, use the `--header` or `-H` flag followed by the header in `key: value` format. + ```shell copy + gh auth login + ``` -```shell -curl --request GET \ ---url "https://api.github.com/octocat" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN"{% ifversion api-date-versioning %} \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %} -``` + {%- endif %} -{% endcurl %} + You can use the `--scopes` option to specify what scopes you want. If you want to authenticate with a token that you created, you can use the `--with-token` option. For more information, see the [{% data variables.product.prodname_cli %} `auth login` documentation](https://cli.github.com/manual/gh_auth_login). -## Using path parameters +1. Follow the on-screen prompts. -Path parameters modify the operation path. For example, the "List repository issues" path is `/repos/{owner}/{repo}/issues`. The curly brackets `{}` denote path parameters that you need to specify. In this case, you must specify the repository owner and name. For the reference documentation for this operation, see "[AUTOTITLE](/rest/issues/issues#list-repository-issues)." + {% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use Git commands like `git push` and `git pull` without needing to set up a separate credential manager or use SSH. -{% cli %} +### 3. Choose an endpoint for your request -{% ifversion ghes or ghae %} -{% note %} +1. Choose an endpoint to make a request to. You can explore {% data variables.product.product_name %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.product_name %}. +1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see "[HTTP method](#http-method)" and "[Path](#path)." -**Note:** In order for this command to work for {% data variables.location.product_location %}, replace `octocat/Spoon-Knife` with a repository owned by {% data variables.location.product_location %}. Otherwise, rerun the `gh auth login` command to authenticate to {% data variables.product.prodname_dotcom_the_website %} instead of {% data variables.location.product_location %}. + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. -{% endnote %} -{% endif %} +1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see "[Path](#path)." -To get issues from the `octocat/Spoon-Knife` repository, replace `{owner}` with `octocat` and `{repo}` with `Spoon-Knife`. + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. -```shell -gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -``` +### 4. Make a request with {% data variables.product.prodname_cli %} -{% endcli %} +Use the {% data variables.product.prodname_cli %} `api` subcommand to make your API request. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api). -{% javascript %} +In your request, specify the following options and values: -{% ifversion ghes or ghae %} -{% note %} +- **--method** followed by the HTTP method and the path of the endpoint. For more information, see "[HTTP method](#http-method)" and "[Path](#path)." +- **--header**: + - **`Accept`**: Pass the media type in an `Accept` header. To pass multiple media types in an `Accept` header, separate the media types with a comma: `Accept: application/vnd.github+json,application/vnd.github.diff`. For more information, see "[`Accept`](#accept)" and "[Media types](#media-types)."{% ifversion api-date-versioning %} + - **`X-GitHub-Api-Version`**: Pass the API version in a `X-GitHub-Api-Version` header. For more information, see "[`X-GitHub-Api-Version`](#x-github-api-version)."{% endif %} +- **`-f`** or **`-F`** followed by any body parameters or query parameters in `key=value` format. Use the `-F` option to pass a parameter that is a number, Boolean, or null. Use the `-f` option to pass string parameters. -**Note:** In order for this example to work for {% data variables.location.product_location %}, replace `octocat/Spoon-Knife` with a repository owned by {% data variables.location.product_location %}. Otherwise, create a new `Octokit` instance and do not specify `baseURL`. + Some endpoints use query parameters that are arrays. To send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID`. -{% endnote %} -{% endif %} + If you do not need to specify any body parameters or query parameters in your request, omit this option. For more information, see "[Body parameters](#body-parameters)" and "[Query parameters](#query-parameters)." For examples, see "[Example request using body parameters](#example-request-using-body-parameters)" and "[Example request using query parameters](#example-request-using-query-parameters)." -When you make a request with Octokit.js, all parameters, including path parameters, are passed in an object as the second argument to the `request` method. To get issues from the `octocat/Spoon-Knife` repository, specify `owner` as `octocat` and `repo` as `Spoon-Knife`. +#### Example request -```javascript -await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife" -}); -``` +The following example request uses the ["Get Octocat" endpoint](/rest/meta/meta#get-octocat) to return the octocat as ASCII art. -{% endjavascript %} +```shell copy +gh api --method GET /octocat \ +--header 'Accept: application/vnd.github+json' \ +--header "X-GitHub-Api-Version: 2022-11-28" +``` -{% curl %} +#### Example request using query parameters -To get issues from the `octocat/Spoon-Knife` repository, replace `{owner}` with `octocat` and `{repo}` with `Spoon-Knife`. To build the full path, prepend the base URL for the {% data variables.product.prodname_dotcom %} REST API, `https://api.github.com`: `https://api.github.com/repos/octocat/Spoon-Knife/issues`. +The ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. The following example uses the `per_page` query parameter to return two issues instead of 30, and the `page` query parameter to fetch only the first page of results. -{% ifversion ghes or ghae %} -{% note %} +```shell copy +gh api --method GET /events -F per_page=2 -F page=1 +--header 'Accept: application/vnd.github+json' \ +``` -**Note:** If you want to use {% data variables.location.product_location %} instead of {% data variables.product.prodname_dotcom_the_website %}, use `{% data variables.product.api_url_code %}` instead of `https://api.github.com` and replace `[hostname]` with the name of {% data variables.location.product_location %}. Replace `octocat/Spoon-Knife` with a repository owned by {% data variables.location.product_location %}. +#### Example request using body parameters -{% endnote %} -{% endif %} +The following example uses the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) to create a new issue in {% ifversion ghes or ghae %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes or ghae %} Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} In the response, find the `html_url` of your issue, and navigate to your issue in the browser. -```shell -curl --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ +```shell copy +gh api --method POST /repos/{% ifversion ghes or ghae %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues \ --header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" +--header "X-GitHub-Api-Version: 2022-11-28" \ +-f title='Created with the REST API' \ +-f body='This is a test issue created by the REST API' \ ``` -{% endcurl %} +{% endcli %} -The operation returns a list of issues and data about each issue. For more information about using the response, see the "[Using the response](#using-the-response)" section. +{% curl %} -## Using query parameters +This section demonstrates how to make an authenticated request to the {% data variables.product.prodname_dotcom %} REST API using `curl`. -Query parameters allow you to control what data is returned for a request. For example, a query parameter may let you specify how many items are returned when the response is paginated. +### 1. Setup -By default, the "List repository issues" operation returns thirty issues, sorted in descending order by the date they were created. You can use the `per_page` parameter to return two issues instead of 30. You can use the `sort` parameter to sort the issues by the date they were last updated instead of by the date they were created. You can use the `direction` parameter to sort the results in ascending order instead of descending order. +You must have `curl` installed on your machine. To check if `curl` is already installed, run `curl --version` on the command line. -{% cli %} +- If the output provides information about the version of `curl`, that means `curl` is installed. +- If you get a message similar to `command not found: curl`, that means `curl` is not installed. Download and install `curl`. For more information, see [the curl download page](https://curl.se/download.html). -For {% data variables.product.prodname_cli %}, use the `-F` flag to pass a parameter that is a number, Boolean, or null. Use `-f` to pass string parameters. +### 2. Choose an endpoint for your request -```shell -gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc -``` +1. Choose an endpoint to make a request to. You can explore {% data variables.product.product_name %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.product_name %}. +1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see "[HTTP method](#http-method)" and "[Path](#path)." -Some operations use query parameters that are arrays. To send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID`. + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. -{% note %} +1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see "[Path](#path)." -In order to use {% data variables.product.prodname_cli %} with query parameters that are arrays, you must use {% data variables.product.prodname_cli %} version 2.31.0 or greater. For upgrade instructions, see the [{% data variables.product.prodname_cli %} repository](https://github.com/cli/cli#installation). + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. -{% endnote %} +### 3. Create authentication credentials -{% endcli %} +Create an access token to authenticate your request. You can save your token and use it for multiple requests. Give the token any scopes or permissions that are required to access the endpoint. You will send this token in an `Authorization` header with your request. For more information, see "[Authentication](#authentication)." -{% javascript %} +### 4. Make a `curl` request -When you make a request with Octokit.js, all parameters, including query parameters, are passed in an object as the second argument to the `request` method. +Use the `curl` command to make your request. For more information, see [the curl documentation](https://curl.se/docs/manpage.html). -```javascript -await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", - per_page: 2, - sort: "updated", - direction: "asc", -}); -``` +Specify the following options and values in your request: -{% endjavascript %} +- **`--request` or `-X`** followed by the HTTP method as the value. For more information, see "[HTTP method](#http-method)." +- **`--url`** followed by the full path as the value. The full path is a URL that includes the base URL for the GitHub REST API (`https://api.github.com`) and the path of the endpoint, like this: `{% data variables.product.api_url_code %}/PATH`.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `PATH` with the path of the endpoint. For more information, see "[Path](#path)." -{% curl %} + To use query parameters, add a `?` to the end of the path, then append your query parameter name and value in the form `parameter_name=value`. Separate multiple query parameters with `&`. If you need to send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID`. For more information, see "[Query parameters](#query-parameters)." For an example, see "[Example request using query parameters](#example-request-using-query-parameters-1)." +- **`--header` or `-H`**: + - **`Accept`**: Pass the media type in an `Accept` header. To pass multiple media types in an `Accept` header, separate the media types with a comma, for example: `Accept: application/vnd.github+json,application/vnd.github.diff`. For more information, see "[`Accept`](#accept)" and "[Media types](#media-types)."{% ifversion api-date-versioning %} + - **`X-GitHub-Api-Version`**: Pass the API version in a `X-GitHub-Api-Version` header. For more information, see "[`X-GitHub-Api-Version`](#x-github-api-version)."{% endif %} + - **`Authorization`**: Pass your authentication token in an `Authorization` header. Note that in most cases you can use `Authorization: Bearer` or `Authorization: token` to pass a token. However, if you are passing a JSON web token (JWT), you must use `Authorization: Bearer`. For more information, see "[Authentication](#authentication)." For an example of a request that uses an `Authorization` header, see "[Example request using body parameters](#example-request-using-body-parameters-1)." +- **`--data` or `-d`** followed by any body parameters within a JSON object. If you do not need to specify any body parameters in your request, omit this option. For more information, see "[Body parameters](#body-parameters)." For an example, see "[Example request using body parameters](#example-request-using-body-parameters-1)." -For `curl` commands, add a `?` to the end of the path, then append your query parameter name and value in the form `parameter_name=value`. Separate multiple query parameters with `&`. +#### Example request -```shell +The following example request uses the ["Get Octocat" endpoint](/rest/meta/meta#get-octocat) to return the octocat as ASCII art. + +```shell copy curl --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2&sort=updated&direction=asc" \ +--url "https://api.github.com/octocat" \ --header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" +--header "X-GitHub-Api-Version: 2022-11-28" ``` -Some operations use query parameters that are arrays. To send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID`. - -{% endcurl %} - -The operation returns a list of issues and data about each issue. For more information about using the response, see the "[Using the response](#using-the-response)" section. +#### Example request using query parameters -## Using body parameters +The ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. The following example uses the `per_page` query parameter to return two issues instead of 30, and the `page` query parameter to fetch only the first page of results. -Body parameters allow you to pass additional data to the API. For example, the "Create an issue" operation requires you to specify a title for the new issue. It also lets you specify other information, such as text to put in the issue body. For the full reference documentation for this operation, see "[AUTOTITLE](/rest/issues/issues#create-an-issue)." +```shell copy +curl --request GET \ +--url "{% data variables.product.api_url_code %}/events?per_page=2&page=1" \ +--header "Accept: application/vnd.github+json" \ +--header "X-GitHub-Api-Version: 2022-11-28" \ + https://api.github.com/events +``` -The "Create an issue" operation uses the same path as the "List repository issues" operation in the examples above, but it uses a `POST` method instead of a `GET` method. +#### Example request using body parameters -{% cli %} +The following example uses the "[Create an issue](/rest/issues/issues#create-an-issue)" endpoint to create a new issue in {% ifversion ghes or ghae %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} Replace `YOUR-TOKEN` with the authentication token you created in a previous step. -For {% data variables.product.prodname_cli %}, use the `-F` flag to pass a parameter that is a number, Boolean, or null. Use `-f` to pass string parameters. If the parameter is an array, you must append `[]` to the parameter name. +{% ifversion pat-v2 %} {% note %} -In order to use {% data variables.product.prodname_cli %} with body parameters that are arrays, you must use {% data variables.product.prodname_cli %} version 2.21.0 or greater. For upgrade instructions, see the [{% data variables.product.prodname_cli %} repository](https://github.com/cli/cli#installation). +**Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes or ghae %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." {% endnote %} -```shell -gh api --header 'Accept: application/vnd.github+json' --method POST /repos/octocat/Spoon-Knife/issues -f title="Created with the REST API" -f body="This is a test issue created by the REST API" -f "labels[]=bug" +{% endif %} + +```shell copy +curl \ +--request POST \ +--url "{% data variables.product.api_url_code %}/repos/{% ifversion ghes or ghae %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues" \ +--header "Accept: application/vnd.github+json" \{% ifversion api-date-versioning %} +--header "X-GitHub-Api-Version: 2022-11-28" \{% endif %} +--header "Authorization: Bearer YOUR-TOKEN" \ +--data '{ + "title": "Created with the REST API", + "body": "This is a test issue created by the REST API" +}' ``` -{% endcli %} +{% endcurl %} {% javascript %} -{% ifversion pat-v2 %} +This section demonstrates how to make a request to the {% data variables.product.prodname_dotcom %} REST API using JavaScript and [Octokit.js](https://github.com/octokit/octokit.js). For a more detailed guide, see "[AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript)." -{% note %} +### 1. Setup -If you are using a {% data variables.product.pat_v2 %}, you must replace `octocat/Spoon-Knife` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information about creating a repository, see "[AUTOTITLE](/get-started/quickstart/create-a-repo)." For more information about granting access and permissions to a {% data variables.product.pat_v2 %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." +You must install `octokit` to use the Octokit.js library shown in the following examples. -{% endnote %} +- Install `octokit`. For example, `npm install octokit`. For other ways to install or load `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). -{% endif %} +### 2. Choose an endpoint for your request -When you make a request with Octokit.js, all parameters, including body parameters, are passed in an object as the second argument to the `request` method. +1. Choose an endpoint to make a request to. You can explore {% data variables.product.product_name %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.product_name %}. +1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see "[HTTP method](#http-method)" and "[Path](#path)." -```javascript -await octokit.request("POST /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", - title: "Created with the REST API", - body: "This is a test issue created by the REST API", -}); -``` + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. -{% endjavascript %} +1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see "[Path](#path)." -{% curl %} + For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. -{% ifversion pat-v2 %} +### 3. Create an access token -{% note %} +Create an access token to authenticate your request. You can save your token and use it for multiple requests. Give the token any scopes or permissions that are required to access the endpoint. You will send this token in an `Authorization` header with your request. For more information, see "[Authentication](#authentication)." -If you are using a {% data variables.product.pat_v2 %}, you must replace `octocat/Spoon-Knife` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information about creating a repository, see "[AUTOTITLE](/get-started/quickstart/create-a-repo)." For more information about granting access and permissions to a {% data variables.product.pat_v2 %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." +### 4. Make a request with Octokit.js -{% endnote %} +1. Import `octokit` in your script. For example, `import { Octokit } from "octokit";`. For other ways to import `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). +1. Create an instance of `Octokit` with your token.{% ifversion ghes or ghae %} Set the base URL to `{% data variables.product.api_url_code %}`. Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `YOUR-TOKEN` with your token. -{% endif %} + ```javascript copy + const octokit = new Octokit({ {% ifversion ghes or ghae %} + baseUrl: "{% data variables.product.api_url_code %}",{% endif %} + auth: 'YOUR-TOKEN' + }); + ``` -For `curl` commands, use the `--data` flag to pass the body parameters in a JSON object. +1. Use `octokit.request` to execute your request. -```shell -curl --request POST \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" \ ---data '{ - "title": "Created with the REST API", - "body": "This is a test issue created by the REST API" -}' -``` + - Send the HTTP method and path as the first argument to the `request` method. For more information, see "[HTTP method](#http-method)" and "[Path](#path)." + - Specify all path, query, and body parameters in an object as the second argument to the `request` method. For more information, see "[Parameters](#parameters)." -{% endcurl %} + In the following example request, the HTTP method is `POST`, the path is `/repos/{owner}/{repo}/issues`, the path parameters are `owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}"` and `repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}"`, and the body parameters are `title: "Created with the REST API"` and `body: "This is a test issue created by the REST API"`.{% ifversion ghes or ghae %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %} + + {% ifversion pat-v2 %} + + {% note %} + + **Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes or ghae %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." + + {% endnote %} + + {% endif %} -The operation creates an issue and returns data about the new issue. In the response, find the `html_url` of your issue and navigate to your issue in the browser. For more information about using the response, see the "[Using the response](#using-the-response)" section. + ```javascript copy + await octokit.request("POST /repos/{owner}/{repo}/issues", { + owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}", + repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}", + title: "Created with the REST API", + body: "This is a test issue created by the REST API", + }); + ``` + + The `request` method automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` property to the object that is passed as a second argument. The value of the `headers` property is an object with the header names as keys and header values as values. + + For example, the following code will send a `content-type` header with a value of `text/plain`{% ifversion api-date-versioning %} and a `X-GitHub-Api-Version` header with a value of `{{ allVersions[currentVersion].latestApiVersion }}`{% endif %}. + + ```javascript copy + await octokit.request("GET /octocat", { + headers: { + "content-type": "text/plain",{% ifversion api-date-versioning %} + "X-GitHub-Api-Version": "{{ allVersions[currentVersion].latestApiVersion }}",{% endif %} + }, + }); + ``` + +{% endjavascript %} ## Using the response +After you make a request, the API will return the response status code, response headers, and potentially a response body. + ### About the response code and headers Every request will return an HTTP status code that indicates the success of the response. For more information about response codes, see [the MDN HTTP response status code documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). @@ -543,15 +461,18 @@ Additionally, the response will include headers that give more details about the {% cli %} -To view the status code and headers, use the `--include` or `--i` flag when you send your request. +To view the status code and headers, use the `--include` or `--i` option when you send your request. -For example, this request: +For example, this request gets a list of issues in {% ifversion ghes or ghae %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository: ```shell -gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 --include +gh api \ +--header 'Accept: application/vnd.github+json' \ +--method GET /repos/{% ifversion ghes or ghae %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues \ +-F per_page=2 --include ``` -returns the response code and headers like: +And it returns a response code and headers that look something like this: ```shell HTTP/2.0 200 OK @@ -593,11 +514,13 @@ When you make a request with Octokit.js, the `request` method returns a promise. You can use a `try/catch` block to catch an error if it occurs. For example, if the request in the following script is successful, the script will log the status code and the value of the `x-ratelimit-remaining` header. If the request was not successful, the script will log the status code, the value of the `x-ratelimit-remaining` header, and the error message. -```javascript +In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. + +```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", + owner: "REPO-OWNER", + repo: "REPO-NAME", per_page: 2, }); @@ -612,19 +535,19 @@ try { {% curl %} -To view the status code and headers, use the `--include` or `--i` flag when you send your request. +To view the status code and headers, use the `--include` or `--i` option when you send your request. -For example, this request: +For example, this request gets a list of issues in {% ifversion ghes or ghae %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository: ```shell curl --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \ +--url "https://api.github.com/repos/{% ifversion ghes or ghae %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" \ --include ``` -returns the response code and headers like: +And it returns a response code and headers that look something like this: ```shell HTTP/2 200 @@ -660,52 +583,24 @@ In this example, the response code is `200`, which indicates a successful reques ### About the response body -Many operations will return a response body. Unless otherwise specified, the response body is in JSON format. For example, this request returns a list of issues with data about each issue: - -{% cli %} - -```shell -gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -``` - -{% endcli %} - -{% javascript %} - -```javascript -await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", - per_page: 2, -}); -``` - -{% endjavascript %} - -{% curl %} - -```shell -curl --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" -``` - -{% endcurl %} +Many endpoints will return a response body. Unless otherwise specified, the response body is in JSON format. Blank fields are included as `null` instead of being omitted. All timestamps return in UTC time, ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Unlike the GraphQL API where you specify what information you want, the REST API typically returns more information than you need. If desired, you can parse the response to pull out specific pieces of information. {% cli %} -For example, you can use `>` to redirect the response to a file: +For example, you can use `>` to redirect the response to a file. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. -```shell -gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 > data.json +```shell copy +gh api \ +--header 'Accept: application/vnd.github+json' \ +--method GET /repos/REPO-OWNER/REPO-NAME/issues \ +-F per_page=2 > data.json ``` Then you can use jq to get the title and author ID of each issue: -```shell +```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` @@ -728,13 +623,13 @@ For more information about jq, see [the jq documentation](https://stedolan.githu {% javascript %} -For example, you can get the title and author ID of each issue: +For example, you can get the title and author ID of each issue. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. -```javascript +```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", + owner: "REPO-OWNER", + repo: "REPO-NAME", per_page: 2, }); @@ -751,18 +646,18 @@ try { {% curl %} -For example, you can use `>` to redirect the response to a file: +For example, you can use `>` to redirect the response to a file. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} -```shell +```shell copy curl --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \ +--url "{% data variables.product.api_url_code %}/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" > data.json ``` Then you can use jq to get the title and author ID of each issue: -```shell +```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` @@ -783,8 +678,22 @@ For more information about jq, see [the jq documentation](https://stedolan.githu {% endcurl %} +#### Detailed versus summary representations + +A response can include all attributes for a resource or only a subset of attributes, depending on whether you fetch an individual resource or a list of resources. + +- When you fetch an _individual resource_, like a specific repository, the response will typically include all attributes for that resource. This is the "detailed" representation of the resource. +- When you fetch a _list of resources_, like a list of multiple repositories, the response will only include a subset of the attributes for each resource. This is the "summary" representation of the resource. + +Note that authorization sometimes influences the amount of detail included in a representation. + +The reason for this is because some attributes are computationally expensive for the API to provide, so {% data variables.product.prodname_dotcom %} excludes those attributes from the summary representation. To obtain those attributes, you can fetch the detailed representation. + +The documentation provides an example response for each API method. The example +response illustrates all attributes that are returned by that method. + ## Next steps -This article demonstrated how to list and create issues in a repository. For more practice, try to comment on an issue, edit the title of an issue, or close an issue. For more information about these operations, see "[AUTOTITLE](/rest/issues#create-an-issue-comment)" and "[AUTOTITLE](/rest/issues/issues#update-an-issue)." +This article demonstrated how to list and create issues in a repository. For more practice, try to comment on an issue, edit the title of an issue, or close an issue. For more information, see the ["Create an issue comment" endpoint](/rest/issues#create-an-issue-comment) and the ["Update an issue" endpoint](/rest/issues/issues#update-an-issue). -For more information about the operations that you can use, see the [REST reference documentation](/rest). +For more information about other endpoints that you can use, see the [REST reference documentation](/rest). diff --git a/content/rest/overview/authenticating-to-the-rest-api.md b/content/rest/overview/authenticating-to-the-rest-api.md index 7dd3f5738eb4..4636a96d4855 100644 --- a/content/rest/overview/authenticating-to-the-rest-api.md +++ b/content/rest/overview/authenticating-to-the-rest-api.md @@ -18,7 +18,9 @@ shortTitle: Authenticating Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated. -You can authenticate your request by sending a token in the `Authorization` header of your request. In the following example, replace `YOUR-TOKEN` with a reference to your token: +To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. + +After creating a token, you can authenticate your request by sending the token in the `Authorization` header of your request. For example, in the folllowing request, replace `YOUR-TOKEN` with a reference to your token: ```shell curl --request GET \ @@ -33,7 +35,11 @@ curl --request GET \ {% endnote %} -If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response. +### Failed login limit + +If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response. Authenticating with invalid credentials will initially return a `401 Unauthorized` response. + +After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with a `403 Forbidden` response. For more information, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)." ## Authenticating with a {% data variables.product.pat_generic %} @@ -93,6 +99,50 @@ If you are the owner of a {% data variables.product.prodname_github_app %} or {% If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)." +If this is not possible, you can store your token as a secret and use the name of your secret in your {% data variables.product.prodname_actions %} workflow. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." + +### Authenticating in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %} + +To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %}, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute the {% data variables.product.prodname_cli %} `api` subcommand. For more information about the `run` keyword, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." + +In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path)."{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} + +```yaml +jobs: + use_api: + runs-on: ubuntu-latest + permissions: {} + steps: + - env: + GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + run: | + gh api /PATH +``` + +### Authenticating in a {% data variables.product.prodname_actions %} workflow using `curl` + +To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using `curl`, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute a `curl` request to the API. For more information about the `run` keyword, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." + +In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path)."{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} + +```yaml copy +jobs: + use_api: + runs-on: ubuntu-latest + permissions: {} + steps: + - env: + GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + run: | + curl --request GET \ + --url "{% data variables.product.api_url_code %}/PATH" \ + --header "Authorization: Bearer $GH_TOKEN" +``` + +### Authenticating in a {% data variables.product.prodname_actions %} workflow using JavaScript + +For an example of how to authenticate in a {% data variables.product.prodname_actions %} workflow using JavaScript, see "[AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-in-github-actions)." + ## Authenticating with username and password {% ifversion ghes %} @@ -114,4 +164,5 @@ Authentication with username and password is not supported. If you try to authen ## Further reading -- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)." +- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)" +- "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#authenticating)" diff --git a/content/rest/overview/resources-in-the-rest-api.md b/content/rest/overview/resources-in-the-rest-api.md index f523bbf7230b..e6b887f102fa 100644 --- a/content/rest/overview/resources-in-the-rest-api.md +++ b/content/rest/overview/resources-in-the-rest-api.md @@ -12,167 +12,6 @@ topics: - API --- -{% ifversion api-date-versioning %} - -## API version - -Available resources may vary between REST API versions. You should use the `X-GitHub-Api-Version` header to specify an API version. For more information, see "[AUTOTITLE](/rest/overview/api-versions)." - -{% endif %} - -## Schema - -{% ifversion fpt or ghec %}All API access is over HTTPS, and{% else %}The API is{% endif %} accessed from `{% data variables.product.api_url_code %}`. All data is -sent and received as JSON. - -```shell -$ curl -I {% data variables.product.api_url_pre %}/users/octocat/orgs - -> HTTP/2 200 -> Server: nginx -> Date: Fri, 12 Oct 2012 23:33:14 GMT -> Content-Type: application/json; charset=utf-8 -> ETag: "a00049ba79152d03380c34652f2cb612" -> X-GitHub-Media-Type: github.v3 -> x-ratelimit-limit: 5000 -> x-ratelimit-remaining: 4987 -> x-ratelimit-reset: 1350085394{% ifversion ghes %} -> X-GitHub-Enterprise-Version: {{ currentVersion | remove: "enterprise-server@" }}.0{% elsif ghae %} -> X-GitHub-Enterprise-Version: GitHub AE{% endif %} -> Content-Length: 5 -> Cache-Control: max-age=0, private, must-revalidate -> X-Content-Type-Options: nosniff -``` - -Blank fields are included as `null` instead of being omitted. - -All timestamps return in UTC time, ISO 8601 format: - - YYYY-MM-DDTHH:MM:SSZ - -For more information about timezones in timestamps, see [this section](#timezones). - -### Summary representations - -When you fetch a list of resources, the response includes a _subset_ of the -attributes for that resource. This is the "summary" representation of the -resource. (Some attributes are computationally expensive for the API to provide. -For performance reasons, the summary representation excludes those attributes. -To obtain those attributes, fetch the "detailed" representation.) - -**Example**: When you get a list of repositories, you get the summary -representation of each repository. Here, we fetch the list of repositories owned -by the [octokit](https://github.com/octokit) organization: - - GET /orgs/octokit/repos - -### Detailed representations - -When you fetch an individual resource, the response typically includes _all_ -attributes for that resource. This is the "detailed" representation of the -resource. (Note that authorization sometimes influences the amount of detail -included in the representation.) - -**Example**: When you get an individual repository, you get the detailed -representation of the repository. Here, we fetch the -[octokit/octokit.rb](https://github.com/octokit/octokit.rb) repository: - - GET /repos/octokit/octokit.rb - -The documentation provides an example response for each API method. The example -response illustrates all attributes that are returned by that method. - -## Authentication - -{% data variables.product.company_short %} recommends that you create a token to authenticate to the REST API. For more information about which type of token to create, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)." - -You can authenticate your request by sending a token in the `Authorization` header of your request: - -```shell -curl --request GET \ ---url "{% data variables.product.api_url_code %}/octocat" \ ---header "Authorization: Bearer YOUR-TOKEN"{% ifversion api-date-versioning %} \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %} -``` - -{% note %} - -**Note:** {% data reusables.getting-started.bearer-vs-token %} - -{% endnote %} - -If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response. - -{% ifversion fpt or ghes or ghec %} - -### OAuth2 key/secret - -{% data reusables.apps.deprecating_auth_with_query_parameters %} - -```shell -curl -u my_client_id:my_client_secret '{% data variables.product.api_url_pre %}/user/repos' -``` - -Using your `client_id` and `client_secret` does _not_ authenticate as a user, it will only identify your {% data variables.product.prodname_oauth_app %} to increase your rate limit. Permissions are only granted to users, not applications, and you will only get back data that an unauthenticated user would see. Don't leak your {% data variables.product.prodname_oauth_app %}'s client secret to your users. - -{% ifversion ghes %} -You will be unable to authenticate using your OAuth2 key and secret while in private mode, and trying to authenticate will return `401 Unauthorized`. For more information, see "[AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-private-mode)". -{% endif %} -{% endif %} - -{% ifversion fpt or ghec %} - -For more information about rate limits for {% data variables.product.prodname_oauth_apps %}, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)." - -{% endif %} - -### Failed login limit - -Authenticating with invalid credentials will return `401 Unauthorized`: - -```shell -$ curl -I {% data variables.product.api_url_pre %} --header "Authorization: Bearer INVALID-TOKEN" -> HTTP/2 401 - -> { -> "message": "Bad credentials", -> "documentation_url": "{% data variables.product.doc_url_pre %}" -> } -``` - -After detecting several requests with invalid credentials within a short period, -the API will temporarily reject all authentication attempts for that user -(including ones with valid credentials) with `403 Forbidden`: - -```shell -> HTTP/2 403 -> { -> "message": "Maximum number of login attempts exceeded. Please try again later.", -> "documentation_url": "{% data variables.product.doc_url_pre %}" -> } -``` - -## Parameters - -Many API methods take optional parameters. For `GET` requests, any parameters not -specified as a segment in the path can be passed as an HTTP query string -parameter: - -```shell -curl -i "{% data variables.product.api_url_pre %}/repos/vmg/redcarpet/issues?state=closed" -``` - -In this example, the 'vmg' and 'redcarpet' values are provided for the `:owner` -and `:repo` parameters in the path while `:state` is passed in the query -string. - -For `POST`, `PATCH`, `PUT`, and `DELETE` requests, parameters not included in the URL should be encoded as JSON -with a Content-Type of 'application/json': - -```shell -curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' {% data variables.product.api_url_pre %}/authorizations -``` - ## Root endpoint You can issue a `GET` request to the root endpoint to get all the endpoint categories that the REST API supports: @@ -186,20 +25,6 @@ $ curl {% ifversion fpt or ghae or ghec %} See the guide on "[AUTOTITLE](/graphql/guides/using-global-node-ids)" for detailed information about how to find `node_id`s via the REST API and use them in GraphQL operations. -## HTTP verbs - -Where possible, the {% data variables.product.product_name %} REST API strives to use appropriate HTTP verbs for each -action. Note that HTTP verbs are case-sensitive. - -Verb | Description ------|----------- -`HEAD` | Can be issued against any resource to get just the HTTP header info. -`GET` | Used for retrieving resources. -`POST` | Used for creating resources. -`PATCH` | Used for updating resources with partial JSON data. For instance, an Issue resource has `title` and `body` attributes. A `PATCH` request may accept one or more of the attributes to update the resource. -`PUT` | Used for replacing resources or collections. For `PUT` requests with no `body` attribute, be sure to set the `Content-Length` header to zero. -`DELETE` |Used for deleting resources. - ## Hypermedia All resources may have one or more `*_url` properties linking to other @@ -221,35 +46,6 @@ gem: >> tmpl.expand all: 1, participating: 1 => "/notifications?all=1&participating=1" -{% ifversion fpt or ghec %} - -## User agent required - -All API requests MUST include a valid `User-Agent` header. Requests with no `User-Agent` -header will be rejected. We request that you use your {% data variables.product.product_name %} username, or the name of your -application, for the `User-Agent` header value. This allows us to contact you if there are problems. - -Here's an example: - -```shell -User-Agent: Awesome-Octocat-App -``` - -curl sends a valid `User-Agent` header by default. If you provide an invalid `User-Agent` header via curl (or via an alternative client), you will receive a `403 Forbidden` response: - -```shell -$ curl -IH 'User-Agent: ' {% data variables.product.api_url_pre %}/meta -> HTTP/1.0 403 Forbidden -> Connection: close -> Content-Type: text/html - -> Request forbidden by administrative rules. -> Please make sure your request has a User-Agent header. -> Check for other possible causes. -``` - -{% endif %} - ## Cross origin resource sharing The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from diff --git a/content/rest/quickstart.md b/content/rest/quickstart.md index 1cf16f400b1a..729107355d17 100644 --- a/content/rest/quickstart.md +++ b/content/rest/quickstart.md @@ -15,52 +15,37 @@ redirect_from: - /v3/guides/getting-started --- -This article describes how to quickly get started with the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, JavaScript, or `curl`. For a more detailed guide, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api)." +## Introduction -{% cli %} +This article describes how to quickly get started with the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, `curl`, or JavaScript. For a more detailed guide, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api)." -## Getting started using {% data variables.product.prodname_cli %} +{% cli %} -### Using {% data variables.product.prodname_cli %} in the command line +## Using {% data variables.product.prodname_cli %} in the command line {% data variables.product.prodname_cli %} is the easiest way to use the {% data variables.product.prodname_dotcom %} REST API from the command line. -{% ifversion ghes or ghae %} -{% note %} - -**Note:** The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. Alternatively, rerun the `gh auth login` command to authenticate to {% data variables.product.prodname_dotcom_the_website %} instead of {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. +{% data reusables.rest-api.github-cli-install-and-auth %} -{% endnote %} -{% endif %} +1. Make a request using the {% data variables.product.prodname_cli %} `api` subcommand, followed by the path. Use the `--method` or `-X` flag to specify the method. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api). -1. Install {% data variables.product.prodname_cli %} if you haven't installed it yet. For installation instructions, see the [{% data variables.product.prodname_cli %} repository](https://github.com/cli/cli#installation). -1. Use the `auth login` subcommand to authenticate to {% data variables.product.prodname_cli %}. For more information, see the [{% data variables.product.prodname_cli %} `auth login` documentation](https://cli.github.com/manual/gh_auth_login). + This example makes a request to the "Get Octocat" endpoint, which uses the method `GET` and the path `/octocat`. For the full reference documentation for this endpoint, see "[AUTOTITLE](/rest/meta/meta#get-octocat)." - ```shell - gh auth login + ```shell copy + gh api /octocat --method GET ``` -1. Use the `api` subcommand to make your API request. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api). - - ```shell - gh api repos/octocat/Spoon-Knife/issues - ``` - -### Using {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %} +## Using {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %} You can also use {% data variables.product.prodname_cli %} in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/using-github-cli-in-workflows)." -Instead of using the `gh auth login` command, pass an access token as an environment variable called `GH_TOKEN`. {% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." - -{% ifversion ghes or ghae %} -{% note %} +### Authenticating with an access token -**Note:** The following example workflows are intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the examples using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}. +Instead of using the `gh auth login` command, pass an access token as an environment variable called `GH_TOKEN`. {% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." -{% endnote %} -{% endif %} +The following example workflow uses the "[List repository issues](/rest/issues/issues#list-repository-issues)" endpoint, and requests a list of issues in {% ifversion ghes or ghae %}a repository you specify{% else %}the `octocat/Spoon-Knife` repository{% endif %}.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} -```yaml +```yaml copy on: workflow_dispatch: jobs: @@ -72,19 +57,21 @@ jobs: - env: GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} run: | - gh api repos/octocat/Spoon-Knife/issues + gh api {% data variables.product.api_url_code %}{% data variables.rest.example_request_url %} ``` +### Authenticating with a {% data variables.product.prodname_github_app %} + If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)" in the REST API documentation. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." 1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." -1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: +1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - ```yaml + ```yaml copy {% ifversion ghes < 3.12 %} {% data reusables.actions.actions-not-certified-by-github-comment %} - + {% data reusables.actions.actions-use-sha-pinning-comment %} {% endif %} on: @@ -103,22 +90,18 @@ If you are authenticating with a {% data variables.product.prodname_github_app % env: GH_TOKEN: {% raw %}${{ steps.generate_token.outputs.token }}{% endraw %} run: | - gh api repos/octocat/Spoon-Knife/issues + gh api {% data variables.product.api_url_code %}{% data variables.rest.example_request_url %} ``` {% endcli %} {% javascript %} -## Getting started using JavaScript +## Using Octokit.js You can use Octokit.js to interact with the {% data variables.product.prodname_dotcom %} REST API in your JavaScript scripts. For more information, see "[Scripting with the REST API and JavaScript](/rest/guides/scripting-with-the-rest-api-and-javascript)." -### Using Octokit.js - -{% data reusables.rest-api.quickstart-location-javascript-admonition %} - -1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. For more information, see "[Creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)." +1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access that endpoint. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)." {% warning %} @@ -136,30 +119,33 @@ You can use Octokit.js to interact with the {% data variables.product.prodname_d 1. Install `octokit`. For example, `npm install octokit`. For other ways to install or load `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). 1. Import `octokit` in your script. For example, `import { Octokit } from "octokit";`. For other ways to import `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). -1. Create an instance of `Octokit` with your token. Replace `YOUR-TOKEN` with your token. +1. Create an instance of `Octokit` with your token.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `YOUR-TOKEN` with your token. - ```javascript - const octokit = new Octokit({ + ```javascript copy + const octokit = new Octokit({ {% ifversion ghes or ghae %} + baseUrl: "{% data variables.product.api_url_code %}",{% endif %} auth: 'YOUR-TOKEN' }); ``` -1. Use `octokit.request` to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For example, in the following request the HTTP method is `GET`, the path is `/repos/{owner}/{repo}/issues`, and the parameters are `owner: "octocat"` and `repo: "Spoon-Knife"`. +1. Use `octokit.request` to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For more information about parameters, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#using-parameters)." + + For example, in the following request the HTTP method is `GET`, the path is `/repos/{owner}/{repo}/issues`, and the parameters are {% ifversion ghes or ghae %}`owner: "REPO-OWNER"` and `repo: "REPO-NAME"`{% else %}`owner: "octocat"` and `repo: "Spoon-Knife"`{% endif %}.{% ifversion ghes or ghae %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %} - ```javascript + ```javascript copy await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", + owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}", + repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}", }); ``` -### Using Octokit.js in {% data variables.product.prodname_actions %} +## Using Octokit.js in {% data variables.product.prodname_actions %} You can also execute your JavaScript scripts in your {% data variables.product.prodname_actions %} workflows. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." -{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." +### Authenticating with an access token -{% data reusables.rest-api.quickstart-location-javascript-admonition %} +{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." The following example workflow: @@ -168,8 +154,6 @@ The following example workflow: 1. Installs `octokit` 1. Stores the value of `GITHUB_TOKEN` as an environment variable called `TOKEN` and runs `.github/actions-scripts/use-the-api.mjs`, which can access that environment variable as `process.env.TOKEN` -Example workflow: - ```yaml on: workflow_dispatch: @@ -198,19 +182,20 @@ jobs: TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} ``` -Example JavaScript script, with the file path `.github/actions-scripts/use-the-api.mjs`: +The following is an example Javascript script with the file path `.github/actions-scripts/use-the-api.mjs`.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} ```javascript import { Octokit } from "octokit" -const octokit = new Octokit({ +const octokit = new Octokit({ {% ifversion ghes or ghae %} + baseUrl: "{% data variables.product.api_url_code %}",{% endif %} auth: process.env.TOKEN }); try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", + owner: "{% ifversion ghes or ghae %}REPO-OWNER{% else %}octocat{% endif %}", + repo: "{% ifversion ghes or ghae %}REPO-NAME{% else %}Spoon-Knife{% endif %}", }); const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id}) @@ -222,6 +207,8 @@ try { } ``` +### Authenticating with a {% data variables.product.prodname_github_app %} + If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." @@ -231,7 +218,7 @@ If you are authenticating with a {% data variables.product.prodname_github_app % ```yaml {% ifversion ghes < 3.12 %} {% data reusables.actions.actions-not-certified-by-github-comment %} - + {% data reusables.actions.actions-use-sha-pinning-comment %} {% endif %} on: @@ -248,17 +235,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app % with: node-version: '16.17.0' cache: npm - + - name: Install dependencies run: npm install octokit - + - name: Generate token id: generate_token uses: {% ifversion ghes < 3.12 %}tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92{% else %}actions/create-github-app-token@v1{% endif %} with: app_id: {% raw %}${{ secrets.APP_ID }}{% endraw %} private_key: {% raw %}${{ secrets.APP_PEM }}{% endraw %} - + - name: Run script run: | node .github/actions-scripts/use-the-api.mjs @@ -271,23 +258,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app % {% curl %} -## Getting started using `curl` - -### Using `curl` in the command line +## Using `curl` in the command line -{% ifversion ghes or ghae %} {% note %} -**Notes:** - -- The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `https://api.github.com` with `{% data variables.product.api_url_code %}`, and replace `HOSTNAME` with the hostname for {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. You must also replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}. -- If you want to make API requests from the command line, {% data variables.product.prodname_dotcom %} recommends that you use {% data variables.product.prodname_cli %}, which simplifies authentication and requests. For more information about getting started with the REST API using {% data variables.product.prodname_cli %}, see the {% data variables.product.prodname_cli %} version of this article. +**Note:** If you want to make API requests from the command line, {% data variables.product.prodname_dotcom %} recommends that you use {% data variables.product.prodname_cli %}, which simplifies authentication and requests. For more information about getting started with the REST API using {% data variables.product.prodname_cli %}, see the {% data variables.product.prodname_cli %} version of this article. {% endnote %} -{% endif %} -1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` in the command line. If the output is information about the version of `curl`, it is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html). -1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. For more information, see "[Creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)" or "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)." +1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` in the command line. If the output provides information about the version of `curl`, that means `curl` is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html). + +1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access the endpoint. For more information, see "[AUTOTITLE](/rest/overview/authenticating-to-the-rest-api)." {% warning %} @@ -303,11 +284,11 @@ If you are authenticating with a {% data variables.product.prodname_github_app % {% endwarning %} -1. Use the `curl` command to make your request. Pass your token in an `Authorization` header. Replace `YOUR-TOKEN` with your token. +1. Use the `curl` command to make your request. Pass your token in an `Authorization` header.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} Replace `YOUR-TOKEN` with your token. - ```shell + ```shell copy curl --request GET \ - --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ + --url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" ``` @@ -318,24 +299,17 @@ If you are authenticating with a {% data variables.product.prodname_github_app % {% endnote %} -### Using `curl` commands in {% data variables.product.prodname_actions %} +## Using `curl` commands in {% data variables.product.prodname_actions %} You can also use `curl` commands in your {% data variables.product.prodname_actions %} workflows. -{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." - -{% ifversion ghes or ghae %} -{% note %} +### Authenticating with an access token -**Note:** The following example workflows are intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the examples using {% data variables.product.product_name %}, note the following differences. - -- You must replace `https://api.github.com` with `{% data variables.product.api_url_code %}`, and replace `HOSTNAME` with the hostname for {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. -- You must replace `octocat/Spoon-Knife` with a repository on {% data variables.product.product_name %}. +{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." -{% endnote %} -{% endif %} +{% ifversion ghes or ghae %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} -```yaml +```yaml copy on: workflow_dispatch: jobs: @@ -348,18 +322,20 @@ jobs: GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} run: | curl --request GET \ - --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ + --url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer $GH_TOKEN" ``` +### Authenticating with a {% data variables.product.prodname_github_app %} + If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." 1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." -1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: +1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - ```yaml + ```yaml copy {% ifversion ghes < 3.12 %} {% data reusables.actions.actions-not-certified-by-github-comment %} @@ -383,7 +359,7 @@ If you are authenticating with a {% data variables.product.prodname_github_app % GH_TOKEN: {% raw %}${{ steps.generate_token.outputs.token }}{% endraw %} run: | curl --request GET \ - --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ + --url "{% data variables.product.api_url_code %}{% data variables.rest.example_request_url %}" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer $GH_TOKEN" diff --git a/content/site-policy/privacy-policies/github-privacy-statement.md b/content/site-policy/privacy-policies/github-privacy-statement.md index e5d00431c2d4..756c891646c3 100644 --- a/content/site-policy/privacy-policies/github-privacy-statement.md +++ b/content/site-policy/privacy-policies/github-privacy-statement.md @@ -410,7 +410,7 @@ The table below contains information about the categories of personal informatio |Usage information and Interactions|Users, customers, website visitors|Provide and personalize our Services; product improvement and development; marketing; and help, secure and troubleshoot|Service providers and user-directed entities| |Geolocation information|Users, customers, website visitors|Provide and personalize our Services; product improvement and development; marketing; and help, secure and troubleshoot|Service providers and user-directed entities| -**Categories of Sensitive Data**. We may collect, process, or disclose certain personal data that qualifies as “sensitive data” under applicable U.S. state data privacy laws. For example, this data may be collected if you participate in a survey, share it in your account profile, or are engaged in certain community-focused repos. Sensitive data is a subset of personal data. In the list below, we outline the categories of sensitive data we collect, the sources of the sensitive data, our purposes of processing, and the categories of third-party recipients with whom we share the sensitive data. Please see the "[What information GitHub collects](#what-information-github-collects)" section for more information about the sensitive data we may collect. +**Categories of Sensitive Data**. We may collect, process, or disclose certain personal data that qualifies as “sensitive data” under applicable U.S. state data privacy laws. For example, this data may be collected if you participate in a survey, share it in your account profile, or are engaged in certain community-focused repositories. Sensitive data is a subset of personal data. In the list below, we outline the categories of sensitive data we collect, the sources of the sensitive data, our purposes of processing, and the categories of third-party recipients with whom we share the sensitive data. Please see the "[What information GitHub collects](#what-information-github-collects)" section for more information about the sensitive data we may collect. |Sensitive Data Type |Purposes of Processing |Recipients | |:---- |:---- |:---- | diff --git a/content/support/contacting-github-support/providing-data-to-github-support.md b/content/support/contacting-github-support/providing-data-to-github-support.md index 005b84b4fb0f..1ae27be18917 100644 --- a/content/support/contacting-github-support/providing-data-to-github-support.md +++ b/content/support/contacting-github-support/providing-data-to-github-support.md @@ -90,7 +90,9 @@ After you submit your support request, we may ask you to share a support bundle - `babeld-logs/babeld.log`: Git proxy logs - `system-logs/haproxy.log`: HAProxy logs - `elasticsearch-logs/github-enterprise.log`: Elasticsearch logs -- `configuration-logs/ghe-config.log`: {% data variables.product.prodname_ghe_server %} configuration logs +- `configuration-logs/{% ifversion unique-config-run-logs %}{% else %}ghe-config.log{% endif %}`: {% data variables.product.prodname_ghe_server %} configuration logs +{%- ifversion unique-config-run-logs %} +{%- endif %} - `collectd/logs/collectd.log`: Collectd logs - `mail-logs/mail.log`: SMTP email delivery logs diff --git a/data/features/unique-config-run-logs.yml b/data/features/unique-config-run-logs.yml new file mode 100644 index 000000000000..fdf4000c15a2 --- /dev/null +++ b/data/features/unique-config-run-logs.yml @@ -0,0 +1,5 @@ +# Reference: #12968 +# Unique logs for configuration runs + +versions: + ghes: '>= 3.11' diff --git a/data/release-notes/enterprise-server/3-11/0-rc1.yml b/data/release-notes/enterprise-server/3-11/0-rc1.yml index 732743e8a451..98144e7cd61c 100644 --- a/data/release-notes/enterprise-server/3-11/0-rc1.yml +++ b/data/release-notes/enterprise-server/3-11/0-rc1.yml @@ -1,6 +1,6 @@ date: '2023-11-14' release_candidate: true -deprecated: false +deprecated: true intro: | {% note %} diff --git a/data/release-notes/enterprise-server/3-11/0.yml b/data/release-notes/enterprise-server/3-11/0.yml new file mode 100644 index 000000000000..12d73c5f7804 --- /dev/null +++ b/data/release-notes/enterprise-server/3-11/0.yml @@ -0,0 +1,344 @@ +date: '2023-12-05' +release_candidate: false +deprecated: false +intro: | + For upgrade instructions, see "[Upgrading {% data variables.product.prodname_ghe_server %}](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server)." + +sections: + features: + - heading: Instance administration + notes: + # https://github.com/github/releases/issues/3439 + - | + Instance administrators can perform administrative tasks using the `gh es` extension for the GitHub CLI. The extension communicates with your instance's management API, so you don't need to SSH into the instance or write a custom application. For more information, see "[AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli)." + + - heading: Authentication + notes: + # https://github.com/github/releases/issues/3320 + - | + To help users discover the required permissions for calls to a REST API endpoint, GitHub Enterprise Server returns the `X-Accepted-GitHub-Permissions` header for requests to endpoints that use fine-grained permissions, including requests from GitHub Apps. For more information, see the following articles. + + - "[AUTOTITLE](/rest/overview/troubleshooting#insufficient-permissions-errors)" + - "[AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)" + - "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps) + + - heading: Audit logs + notes: + # https://github.com/github/releases/issues/3263 + - | + The web interface for enterprise, organization, and user audit logs include an expandable view that displays the full audit log payload for each event. Administrators and users can see the same event metadata when searching the audit log in the web interface or via streaming. For more information, see the following articles. + + - "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise)" + - "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization)" + - "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log)" + + - heading: GitHub Advanced Security + notes: + # https://github.com/github/releases/issues/3066 + - | + On an instance with GitHub Actions enabled, in repositories that use default setup for code scanning, the default setup configuration updates automatically if GitHub detects new languages. Users can view a repository's language configuration for default setup from the repository's "Code security and analysis" settings page. Additionally, users can view information about setup and debug failed languages from the tools status page. For more information, see the following articles. + + - "[AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale#about-adding-languages-to-an-existing-default-setup-configuration)" + - "[AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning)" + - "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page)" + + # https://github.com/github/releases/issues/3258 + - | + On an instance with GitHub Actions enabled, default setup for code scanning at the organization level is now generally available. For more information, see "[AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale)" and "[AUTOTITLE](/rest/orgs/orgs?apiVersion=2022-11-28#enable-or-disable-a-security-feature-for-an-organization)" in the REST API documentation. + + # https://github.com/github/releases/issues/3214 + - | + On an instance with GitHub Actions enabled, during configuration of default setup for code scanning, users can select either the "Extended" or "Default" query suite for eligible repositories in an organization. For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/built-in-codeql-query-suites)" and "[AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning)." + + # https://github.com/github/releases/issues/2841 + - | + On an instance with GitHub Actions enabled, to better protect active and inactive repositories, GitHub Enterprise Server automatically analyzes repositories that use a default setup for code scanning. The analysis runs on a weekly schedule and uses the most recent version of CodeQL. When configuring code scanning, the fixed time for the weekly scan is randomly chosen. The scan will take place at the same time every week, and the schedule is displayed after the setup is completed, so users can easily see when the next scheduled analysis will occur. The scheduled analysis will be automatically disabled if a repository has no activity for six months. Creation of a pull request or pushes to the repository will re-enable scheduled analysis. + + # https://github.com/github/releases/issues/3283 + - | + Code scanning default setup is available for Swift analysis with CodeQL. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically)." + + # https://github.com/github/releases/issues/3355 + - | + CodeQL 2.14.6 and later supports analysis of code written in Go 1.21. For more information, see "[Supported languages and frameworks](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)" in the CodeQL documentation. + + # https://github.com/github/releases/issues/3289 + - | + With CodeQL model packs for Java, users can improve code scanning results by ensuring that any custom Java libraries and frameworks used by their codebase are recognized by CodeQL. For more information, see the following documentation. + + - "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)" + - "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs)" + - "[Using the CodeQL model editor](https://codeql.github.com/docs/codeql-for-visual-studio-code/using-the-codeql-model-editor)" in the CodeQL documentation + + # https://github.com/github/releases/issues/3110 + - | + For instances with GitHub Connect configured, code scanning with CodeQL supports Java codebases that use [Project Lombok](https://projectlombok.org/). Previously, code scanning users were able to scan Java applications that contained Lombok code, but all the contents of files containing Lombok code were either skipped or users had to apply a workaround to prepare the applications for scanning. Lombok features will now be automatically scanned without requiring any workaround. + + For more information about syncing the required GitHub Actions workflow to scan Lombok code, see "[AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-github-connect-to-sync-github-actions)." + + # https://github.com/github/releases/issues/2920 + - | + Push protection for secret scanning is now generally available. For more information, see "[AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)." + + # https://github.com/github/releases/issues/2649 + # https://github.com/github/releases/issues/2866 + # https://github.com/github/releases/issues/3196 + - | + To prevent the leak of tokens where users work outside of code, secret scanning detects tokens in both new and historical issue titles, descriptions, and comments. When a new token type is added to secret scanning, GitHub Enterprise Server scans for matches automatically. This expanded coverage also detects and surfaces secrets that match any custom pattern defined at the repository, organization, or enterprise level. These secrets appear both in the web interface and in queries to the REST API. For more information, see "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)" and "[AUTOTITLE](/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)." + + # https://github.com/github/releases/issues/2868 + - | + Users can view metrics associated with push protection usage across an organization. The overview shows a summary of blocks and bypasses, as well as more granular metrics. For more information, see "[AUTOTITLE](/code-security/security-overview/assessing-code-security-risk)." + + # https://github.com/github/releases/issues/3291 + - | + A new REST API endpoint is available for dataflow analysis using custom CodeQL queries. The new endpoint offers additional flexibility, includes improvements that prevent common pitfalls with the old API, and improves the performance of query evaluation by five percent. For more information, see [New dataflow API for writing custom CodeQL queries](https://github.blog/changelog/2023-08-14-new-dataflow-api-for-writing-custom-codeql-queries/) in the GitHub Changelog. + + - heading: Dependabot + notes: + # https://github.com/github/releases/issues/2919 + - | + For developers who manage Node.js dependencies using the pnpm package manager, pnpm is fully supported by dependency graph, Dependabot alerts, and Dependabot security updates. For more information about securing your supply chain with Dependabot, see "[AUTOTITLE](/code-security/dependabot)." + + # https://github.com/github/releases/issues/3171 + - | + Developers can enforce policies related to vulnerabilities and licenses in pull requests for complex ecosystems with transitive dependencies like Gradle and Scala. Dependency review supports dependencies from the dependency submission API. For more information, see the following articles. + + - "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#best-practices-for-using-the-dependency-review-api-and-the-dependency-submission-api-together)" + - "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" + - "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)" + + # https://github.com/github/releases/issues/3268 + # https://github.com/github/releases/issues/3362 + # https://github.com/github/releases/issues/3363 + # https://github.com/github/releases/issues/3364 + - | + To control how Dependabot structures pull requests and improve mergeability, users can implement flexible grouping options in `dependabot.yml`. You can also control Dependabot's behavior for groups using comment commands. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups)" and "[AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands)." + + # https://github.com/github/releases/issues/3270 + # https://github.com/github/releases/issues/3271 + - | + Dependabot can open pull requests for Swift and Gradle dependencies. + + - Users can also configure scheduled updates for Swift dependencies using `dependabot.yml`. + - If users have used the REST API for dependency submission to upload Gradle dependencies to the dependency graph and receive Dependabot alerts for those dependencies, Dependabot will try to open a pull request to resolve security updates enabled for the repository. + + For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates)." + + # https://github.com/github/releases/issues/3287 + - | + Responses from REST API endpoints for repositories display whether Dependabot security updates are enabled or disabled. Users can also enable or disable security updates for a repository using the REST API. For more information, see "[AUTOTITLE](/rest/repos/repos)" in the REST API documentation. + + - heading: Code security + notes: + # https://github.com/github/releases/issues/3259 + - | + To assess risks to code security and ensure adoption of features to improve code security, the "Security risk" and "Security coverage" pages for organizations and the entire instance are generally available. Additionally, the alert-centric pages for Dependabot, code scanning, and secret scanning are also now generally available. For more information, see "[Assessing your code security risk](/code-security/security-overview/assessing-code-security-risk)" and "[Assessing adoption of code security features](/code-security/security-overview/assessing-adoption-code-security)." + + # https://github.com/github/releases/issues/3126 + - | + Users can take advantage of the [GitHub Advisory Database](https://github.com/advisories) using the REST API. The Advisory Database is a free, open-source list of actionable security advisories and CVEs. API responses include machine-readable mappings to the ecosystem, package name, and affected versions of impacted software. For more information, see "[AUTOTITLE](/rest/security-advisories/global-advisories)" in the REST API documentation. + + - heading: GitHub Actions + notes: + # https://github.com/github/releases/issues/3247 + - | + To better navigate, trace, understand, and monitor deployments, users can view and track the full history of deployments in a repository or filter across environments. For more information, see "[AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history)." + + # https://github.com/github/releases/issues/3402 + - | + Users can improve the security of deployment environments by configuring a branch protection policy to only allow specific branches to deploy to an environment. Additionally, the following security improvements apply to environments. + + - GitHub Enterprise Server blocks runs triggered from forks with branch names that match the protected branch's name. + - Tags with the same name as a protected branch cannot deploy to the environments with a branch protection configuration. + + For more information, see "[AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-branches)." + + # https://github.com/github/releases/issues/3489 + - | + On an instance with GitHub Actions enabled and a configuration for deployment environments, administrators for environments can improve the security of deployments by enforcing a review by someone other than the person who triggered the run. This option prevents required reviewers from self-reviewing to trigger workflows. For more information, see "[AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment#required-reviewers)." + + - heading: Organizations + notes: + # https://github.com/github/releases/issues/3465 + - | + Organization owners can signal that an organization is no longer actively maintained by archiving the organization. For more information, see "[AUTOTITLE](/organizations/managing-organization-settings/archiving-an-organization)." + + - heading: Repositories + notes: + # https://github.com/github/releases/issues/2926 + - | + Users can govern protections for branches and tags in a repository using repository rules. To govern the protections for all of an organization's repositories, users can also enable rulesets for an organization. Contributors to a repository can see which rules apply via the web interface, Git, or the GitHub CLI. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)." + + # https://github.com/github/releases/issues/3081 + - | + Users can create new repositories with predefined attributes using query parameters. For example, a user can create a URL that prepopulates information about the repository like the name, description, visibility, and more. For more information, see "[AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository#creating-a-new-repository-from-a-url-query)." + + # https://github.com/github/releases/issues/2741 + - | + Users can more easily understand changes to a repository using the activity view. For more information, see "[AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository)." + + - heading: Issues + notes: + # https://github.com/github/releases/issues/3324 + - | + Users can automatically add a new issue to projects using a custom issue form by defining `projects` in the issue template. For more information, see "[AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms)." + + - heading: Projects + notes: + # https://github.com/github/releases/issues/3205 + - | + Users can review items in a project view broken down by a certain field value. For more information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-table-layout#slicing-by-field-values)." + + # https://github.com/github/releases/issues/3205 + - | + Users can create charts to visualize current project items, or visualize project items over time. For more information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects)." + + - heading: Accessibility + notes: + # https://github.com/github/releases/issues/3340 + - | + To improve the visibility of links with blocks of text in the web interface for GitHub Enterprise Server, users can apply underline styling. For more information, see "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-accessibility-settings#managing-the-appearance-of-links)." + + changes: + # https://github.com/github/releases/issues/3319 + - | + The speed of restoration operations with GitHub Enterprise Server Backup Utilities has increased. + + # https://github.com/github/ghes/issues/6613 + - | + Configuration runs now correspond with a unique ID. During the run, the log remains at `/data/user/common/ghe-config.log`. After the run, the instance rotates the log's contents into `/data/user/config-apply/logs/YYYYMMDD/ghe-config.HOSTNAME.ID.log`, where YYYYMMDD is the date of the run, HOSTNAME is the hostname of the node, and ID is the ID of the run. For more information, see "[AUTOTITLE](/admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs#log-files-for-instance-configuration)." + + # https://github.com/github/releases/issues/3403 + - | + Field names for some service logs on GitHub Enterprise Server have changed as part of GitHub's gradual migration to internal semantic conventions for [OpenTelemetry](https://opentelemetry.io/). Additional field names were changed in GitHub Enterprise Server 3.9 and 3.10. If any tooling or processes in your environment rely on specific field names within logs, or log entries in specific files, the following changes may affect you. + + - `level` is now `SeverityText`. + - `log_message`, `msg`, or `message` is now `Body`. + - `now` is now `Timestamp`. + - Custom field names such as `gh.repo.id` or `graphql.operation.name` use semantic names. + - Log statements that the instance would previously write to `auth.log`, `ldap.log`, or `ldap-sync.log` now appear in containerized logs for `github-unicorn` if the statement originated from a web request, or in logs for `github-resqued` if the statement originated from a background job. For more information about containerized logs, see "[AUTOTITLE](/admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/about-system-logs#system-logs-in-the-systemd-journal)." + + For a full list of mappings, download the OpenTelemetry attribute mapping CSV for GitHub Enterprise Server [3.9](/assets/ghes-3.9-opentelemetry-attribute-mappings.csv), [3.10](/assets/ghes-3.10-opentelemetry-attribute-mappings.csv), and [3.11](/assets/ghes-3.11-opentelemetry-attribute-mappings.csv). + + # https://github.com/github/releases/issues/3281 + - | + On an instance that uses built-in authentication or LDAP, if two-factor authentication (2FA) is configured for an organization, a user could use a TOTP code multiple times within the code's window of validity during authentication or when entering sudo mode for sensitive actions. To improve security, this reuse is no longer allowed. External systems with a scripted login flow across multiple parallel jobs may stop working as a result of this change. + + For more information about 2FA, see the following articles. + + - "[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization)" + - "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/sudo-mode)" + - "[AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app)" + + # https://github.com/github/releases/issues/3327 + - | + On an instance with a GitHub Advanced Security license, during analysis of Python projects with code scanning using CodeQL and an advanced setup, GitHub Enterprise Server would automatically install dependencies for the project. Due to improvements to CodeQL, GitHub Enterprise Server no longer needs to fetch these dependencies to analyze a codebase. To improve scan times for Python projects, automatic dependency installation is disabled. + + If you configured code scanning with CodeQL via advanced setup to disable dependency installation, GitHub recommends setting `setup-python-dependencies` to `false` for the configuration. For more information, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#analyzing-python-dependencies)." + + # https://github.com/github/releases/issues/3172 + - | + On an instance with Dependabot enabled, due to misconfiguration or incompatible versions, Dependabot jobs for a repository can fail. After 30 failed runs, subsequent scheduled jobs will fail immediately until you trigger a check for updates from the dependency graph, or until you update a manifest file. Jobs for Dependabot security updates will still trigger normally. + + # https://github.com/github/releases/issues/3284 + - | + On an instance with GitHub Advanced Security, to help users more efficiently review and filter code scanning alerts at scale using the REST API, the `updated_at` field in API responses is improved. The `updated_at` timestamp now represents an alert's most recent state change on the branch that you requested. State changes include an alert being introduced, fixed, dismissed, reopened, or reintroduced. Previously, the `updated_at` timestamp changed frequently, whenever an alert was found in an analysis or the alert state changed. For more information about using the REST API to retrieve code scanning alerts, see "[AUTOTITLE](/rest/code-scanning/code-scanning?apiVersion=2022-11-28)" in the REST API documentation. + + # https://github.com/github/releases/issues/2874 + - | + On an instance with Dependabot enabled, the following improvements apply to the repository view for dependency graph, available from the repository's "Insights" tab. + + - Users can search by package name from a paginated list of all dependencies. + - Dependency licenses are displayed. + - Dependabot alerts appear for dependencies, sorted by severity, and link to the Dependabot alerts and the Dependabot update pull request where applicable. + + For more information about the dependency graph, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph)." + + # https://github.com/github/releases/issues/3253 + - | + After first enabling Dependabot on an instance, GitHub Enterprise Server will no longer send web or email notifications for repositories that are initially populated with Dependabot alerts. This allows you to review the new Dependabot alerts for a repository, organization, or the entire instance without immediately notifying other users of existing alerts. + + # https://github.com/github/releases/issues/2603 + - | + On an instance with GitHub Actions enabled, workflows that use Node.js 12 will log a warning. Node.js 12 has been end-of-life since [April 2022](https://github.com/nodejs/Release/#end-of-life-releases). + + - Workflow authors should update actions to run on Node.js 16 instead of 12. For more information, see "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions)." + - Users with workflows that use Node.js should specify Node.js 16 or later in the workflows using versioned actions. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions)." + + # https://github.com/github/releases/issues/3500 + - | + On an instance with GitHub Actions enabled and runners using GitHub Actions Runner 2.309.0 or later, users can no longer use `GITHUB_ENV` to set the `NODE_OPTIONS` environment variable in workflows. Workflows that set `NODE_OPTIONS` as an environment variable will now log the following error. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable)" and the [v2.309.0 release](https://github.com/actions/runner/releases/tag/v2.309.0) in the actions/runner repository on GitHub.com. + + ``` + Can't store NODE_OPTIONS output parameter using '$GITHUB_ENV' command. + ``` + + # https://github.com/github/releases/issues/3205 + - | + Users can quickly take action on multiple items in a group, or the group itself, using the `•••` button in a table, board, or roadmap. + + # https://github.com/github/releases/issues/3219 + - | + Users can break out items in a project by workstreams, team members, priorities, or other groupings using a swimlane view. For more information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-board-layout#grouping-by-field-values)." + + # https://github.com/github/releases/issues/3262 + - | + Users can view view the template used to create a project from a project's settings. + + # https://github.com/github/releases/issues/3262 + - | + When scrolling through a project, group headers are now sticky. + + # https://github.com/github/releases/issues/3262 + - | + The colors for single-select fields in a project have been updated, so users see the same colors within the field picker and within project views. + + # https://github.com/github/releases/issues/3262 + - | + Users create can create issues in a project view that's grouped by repository in the board layout by clicking "Create new issue", or by starting to type the issue's title. + + known_issues: + - | + Custom firewall rules are removed during the upgrade process. + - | + During the validation phase of a configuration run, a `No such object` error may occur for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. + - | + If the root site administrator is locked out of the Management Console after failed login attempts, the account does not unlock automatically after the defined lockout time. Someone with administrative SSH access to the instance must unlock the account using the administrative shell. For more information, see "[AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/troubleshooting-access-to-the-management-console#unlocking-the-root-site-administrator-account)." + - | + If an instance is configured to forward logs to a target server with TLS enabled, certificate authority (CA) bundles that a site administrator uploads using `ghe-ssl-ca-certificate-install` are not respected, and connections to the server fail. + - | + The `mbind: Operation not permitted` error in the `/var/log/mysql/mysql.err` file can be ignored. MySQL 8 does not gracefully handle when the `CAP_SYS_NICE` capability isn't required, and outputs an error instead of a warning. + - | + On an instance hosted in AWS, system time may lose synchronization with Amazon's servers after an administrator reboots the instance. + - | + On an instance with the HTTP `X-Forwarded-For` header configured for use behind a load balancer, all client IP addresses in the instance's audit log erroneously appear as 127.0.0.1. + - | + {% data reusables.release-notes.large-adoc-files-issue %} + - | + {% data reusables.release-notes.2023-11-cluster-ha-failover-git-push-failure %} + - | + On an instance in a high-availability configuration, passive replica nodes accept Git client requests and forward the requests to the primary node. + - | + On an instance with the HTTP `X-Forwarded-For` header configured for use behind a load balancer, all client IP addresses in the instance's audit log erroneously appear as 127.0.0.1. + - | + {% data reusables.release-notes.2023-10-git-push-made-but-not-registered %} + - | + {% data reusables.release-notes.2023-12-backup-utils-exit-early-redis %} + + deprecations: + # https://github.com/github/releases/issues/3259 + - heading: Enterprise-level security overview is deprecated + notes: + - | + The enterprise-level "Security overview" page is deprecated in favor of the new "Security risk" and "Security coverage" pages. For more information, see "[AUTOTITLE](/code-security/security-overview/assessing-code-security-risk)" and "[AUTOTITLE](/code-security/security-overview/assessing-adoption-code-security)." + + # https://github.com/github/releases/issues/2605 + - heading: Dependabot updates no longer support Python 3.6 or 3.7 + notes: + - | + Dependabot updates no longer support Python 3.6 or 3.7, which have reached end-of-life. If a user's code uses these versions, Dependabot will no longer be able to open pull requests in your repository and will log errors. Update to Python 3.8 or later to ensure your code is secure and Dependabot can still run. + + Users will continue to receive Dependabot alerts for dependencies with known vulnerabilities. To resolve these alerts, users can manually upgrade the affected package. + + For more information about Python releases, see [Status of Python versions](https://devguide.python.org/versions) on the Python website. For more information about supported package managers for Dependabot, see "[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems)." diff --git a/data/reusables/rest-api/github-cli-install-and-auth.md b/data/reusables/rest-api/github-cli-install-and-auth.md new file mode 100644 index 000000000000..b41e5a727a1d --- /dev/null +++ b/data/reusables/rest-api/github-cli-install-and-auth.md @@ -0,0 +1,20 @@ +1. Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository. +1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %} + + {%- ifversion fpt or ghec %} + + ```shell + gh auth login + ``` + + {%- else %} + + ```shell + gh auth login --hostname HOSTNAME + ``` + + {%- endif %} + +1. Follow the on-screen prompts. + + {% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use Git commands like `git push` and `git pull` without needing to set up a separate credential manager or use SSH. diff --git a/data/reusables/rest-api/quickstart-location-javascript-admonition.md b/data/reusables/rest-api/quickstart-location-javascript-admonition.md deleted file mode 100644 index e94cb5946c7b..000000000000 --- a/data/reusables/rest-api/quickstart-location-javascript-admonition.md +++ /dev/null @@ -1,7 +0,0 @@ -{% ifversion ghes or ghae %} -{% note %} - -**Note:** The following example is intended for {% data variables.product.prodname_dotcom_the_website %}. If you'd prefer to try the example using {% data variables.product.product_name %}, you must replace `octocat/Spoon-Knife` with a repository on {% ifversion ghes %}your instance{% elsif ghae %}{% data variables.product.product_name %}{% endif %}. Alternatively, you can create a new `Octokit` instance without specifying `baseURL`. - -{% endnote %} -{% endif %} diff --git a/data/variables/rest.yml b/data/variables/rest.yml new file mode 100644 index 000000000000..6ce315f536d8 --- /dev/null +++ b/data/variables/rest.yml @@ -0,0 +1 @@ +example_request_url: '/repos{% ifversion ghes or ghae %}/REPO-OWNER/REPO-NAME{% else %}/octocat/Spoon-Knife{% endif %}/issues' diff --git a/src/fixtures/fixtures/data/variables/release_candidate.yml b/src/fixtures/fixtures/data/variables/release_candidate.yml deleted file mode 100644 index 953c8dcebae2..000000000000 --- a/src/fixtures/fixtures/data/variables/release_candidate.yml +++ /dev/null @@ -1 +0,0 @@ -version: enterprise-server@3.11 diff --git a/src/versions/lib/enterprise-server-releases.js b/src/versions/lib/enterprise-server-releases.js index 491d6903a75f..2f7eda283ec6 100644 --- a/src/versions/lib/enterprise-server-releases.js +++ b/src/versions/lib/enterprise-server-releases.js @@ -15,7 +15,7 @@ export const nextNext = '3.13' export const supported = ['3.11', '3.10', '3.9', '3.8', '3.7'] // Edit this to `null` when it's no longer the release candidate -export const releaseCandidate = '3.11' +export const releaseCandidate = null // Ensure that: // "next" is ahead of "latest" by one minor or major release.