├── LICENSE.md ├── README.md └── assets ├── oauth-code-redirect.png └── oauth-request-access.png /LICENSE.md: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | Section 1 -- Definitions. 69 | 70 | a. Adapted Material means material subject to Copyright and Similar 71 | Rights that is derived from or based upon the Licensed Material 72 | and in which the Licensed Material is translated, altered, 73 | arranged, transformed, or otherwise modified in a manner requiring 74 | permission under the Copyright and Similar Rights held by the 75 | Licensor. For purposes of this Public License, where the Licensed 76 | Material is a musical work, performance, or sound recording, 77 | Adapted Material is always produced where the Licensed Material is 78 | synched in timed relation with a moving image. 79 | 80 | b. Adapter's License means the license You apply to Your Copyright 81 | and Similar Rights in Your contributions to Adapted Material in 82 | accordance with the terms and conditions of this Public License. 83 | 84 | c. Copyright and Similar Rights means copyright and/or similar rights 85 | closely related to copyright including, without limitation, 86 | performance, broadcast, sound recording, and Sui Generis Database 87 | Rights, without regard to how the rights are labeled or 88 | categorized. For purposes of this Public License, the rights 89 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 90 | Rights. 91 | 92 | d. Effective Technological Measures means those measures that, in the 93 | absence of proper authority, may not be circumvented under laws 94 | fulfilling obligations under Article 11 of the WIPO Copyright 95 | Treaty adopted on December 20, 1996, and/or similar international 96 | agreements. 97 | 98 | e. Exceptions and Limitations means fair use, fair dealing, and/or 99 | any other exception or limitation to Copyright and Similar Rights 100 | that applies to Your use of the Licensed Material. 101 | 102 | f. Licensed Material means the artistic or literary work, database, 103 | or other material to which the Licensor applied this Public 104 | License. 105 | 106 | g. Licensed Rights means the rights granted to You subject to the 107 | terms and conditions of this Public License, which are limited to 108 | all Copyright and Similar Rights that apply to Your use of the 109 | Licensed Material and that the Licensor has authority to license. 110 | 111 | h. Licensor means the individual(s) or entity(ies) granting rights 112 | under this Public License. 113 | 114 | i. Share means to provide material to the public by any means or 115 | process that requires permission under the Licensed Rights, such 116 | as reproduction, public display, public performance, distribution, 117 | dissemination, communication, or importation, and to make material 118 | available to the public including in ways that members of the 119 | public may access the material from a place and at a time 120 | individually chosen by them. 121 | 122 | j. Sui Generis Database Rights means rights other than copyright 123 | resulting from Directive 96/9/EC of the European Parliament and of 124 | the Council of 11 March 1996 on the legal protection of databases, 125 | as amended and/or succeeded, as well as other essentially 126 | equivalent rights anywhere in the world. 127 | 128 | k. You means the individual or entity exercising the Licensed Rights 129 | under this Public License. Your has a corresponding meaning. 130 | 131 | Section 2 -- Scope. 132 | 133 | a. License grant. 134 | 135 | 1. Subject to the terms and conditions of this Public License, 136 | the Licensor hereby grants You a worldwide, royalty-free, 137 | non-sublicensable, non-exclusive, irrevocable license to 138 | exercise the Licensed Rights in the Licensed Material to: 139 | 140 | a. reproduce and Share the Licensed Material, in whole or 141 | in part; and 142 | 143 | b. produce, reproduce, and Share Adapted Material. 144 | 145 | 2. Exceptions and Limitations. For the avoidance of doubt, where 146 | Exceptions and Limitations apply to Your use, this Public 147 | License does not apply, and You do not need to comply with 148 | its terms and conditions. 149 | 150 | 3. Term. The term of this Public License is specified in Section 151 | 6(a). 152 | 153 | 4. Media and formats; technical modifications allowed. The 154 | Licensor authorizes You to exercise the Licensed Rights in 155 | all media and formats whether now known or hereafter created, 156 | and to make technical modifications necessary to do so. The 157 | Licensor waives and/or agrees not to assert any right or 158 | authority to forbid You from making technical modifications 159 | necessary to exercise the Licensed Rights, including 160 | technical modifications necessary to circumvent Effective 161 | Technological Measures. For purposes of this Public License, 162 | simply making modifications authorized by this Section 2(a) 163 | (4) never produces Adapted Material. 164 | 165 | 5. Downstream recipients. 166 | 167 | a. Offer from the Licensor -- Licensed Material. Every 168 | recipient of the Licensed Material automatically 169 | receives an offer from the Licensor to exercise the 170 | Licensed Rights under the terms and conditions of this 171 | Public License. 172 | 173 | b. No downstream restrictions. You may not offer or impose 174 | any additional or different terms or conditions on, or 175 | apply any Effective Technological Measures to, the 176 | Licensed Material if doing so restricts exercise of the 177 | Licensed Rights by any recipient of the Licensed 178 | Material. 179 | 180 | 6. No endorsement. Nothing in this Public License constitutes or 181 | may be construed as permission to assert or imply that You 182 | are, or that Your use of the Licensed Material is, connected 183 | with, or sponsored, endorsed, or granted official status by, 184 | the Licensor or others designated to receive attribution as 185 | provided in Section 3(a)(1)(A)(i). 186 | 187 | b. Other rights. 188 | 189 | 1. Moral rights, such as the right of integrity, are not 190 | licensed under this Public License, nor are publicity, 191 | privacy, and/or other similar personality rights; however, to 192 | the extent possible, the Licensor waives and/or agrees not to 193 | assert any such rights held by the Licensor to the limited 194 | extent necessary to allow You to exercise the Licensed 195 | Rights, but not otherwise. 196 | 197 | 2. Patent and trademark rights are not licensed under this 198 | Public License. 199 | 200 | 3. To the extent possible, the Licensor waives any right to 201 | collect royalties from You for the exercise of the Licensed 202 | Rights, whether directly or through a collecting society 203 | under any voluntary or waivable statutory or compulsory 204 | licensing scheme. In all other cases the Licensor expressly 205 | reserves any right to collect such royalties. 206 | 207 | Section 3 -- License Conditions. 208 | 209 | Your exercise of the Licensed Rights is expressly made subject to the 210 | following conditions. 211 | 212 | a. Attribution. 213 | 214 | 1. If You Share the Licensed Material (including in modified 215 | form), You must: 216 | 217 | a. retain the following if it is supplied by the Licensor 218 | with the Licensed Material: 219 | 220 | i. identification of the creator(s) of the Licensed 221 | Material and any others designated to receive 222 | attribution, in any reasonable manner requested by 223 | the Licensor (including by pseudonym if 224 | designated); 225 | 226 | ii. a copyright notice; 227 | 228 | iii. a notice that refers to this Public License; 229 | 230 | iv. a notice that refers to the disclaimer of 231 | warranties; 232 | 233 | v. a URI or hyperlink to the Licensed Material to the 234 | extent reasonably practicable; 235 | 236 | b. indicate if You modified the Licensed Material and 237 | retain an indication of any previous modifications; and 238 | 239 | c. indicate the Licensed Material is licensed under this 240 | Public License, and include the text of, or the URI or 241 | hyperlink to, this Public License. 242 | 243 | 2. You may satisfy the conditions in Section 3(a)(1) in any 244 | reasonable manner based on the medium, means, and context in 245 | which You Share the Licensed Material. For example, it may be 246 | reasonable to satisfy the conditions by providing a URI or 247 | hyperlink to a resource that includes the required 248 | information. 249 | 250 | 3. If requested by the Licensor, You must remove any of the 251 | information required by Section 3(a)(1)(A) to the extent 252 | reasonably practicable. 253 | 254 | 4. If You Share Adapted Material You produce, the Adapter's 255 | License You apply must not prevent recipients of the Adapted 256 | Material from complying with this Public License. 257 | 258 | Section 4 -- Sui Generis Database Rights. 259 | 260 | Where the Licensed Rights include Sui Generis Database Rights that 261 | apply to Your use of the Licensed Material: 262 | 263 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 264 | to extract, reuse, reproduce, and Share all or a substantial 265 | portion of the contents of the database; 266 | 267 | b. if You include all or a substantial portion of the database 268 | contents in a database in which You have Sui Generis Database 269 | Rights, then the database in which You have Sui Generis Database 270 | Rights (but not its individual contents) is Adapted Material; and 271 | 272 | c. You must comply with the conditions in Section 3(a) if You Share 273 | all or a substantial portion of the contents of the database. 274 | 275 | For the avoidance of doubt, this Section 4 supplements and does not 276 | replace Your obligations under this Public License where the Licensed 277 | Rights include other Copyright and Similar Rights. 278 | 279 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 280 | 281 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 282 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 283 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 284 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 285 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 286 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 287 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 288 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 289 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 290 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 291 | 292 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 293 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 294 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 295 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 296 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 297 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 298 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 299 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 300 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 301 | 302 | c. The disclaimer of warranties and limitation of liability provided 303 | above shall be interpreted in a manner that, to the extent 304 | possible, most closely approximates an absolute disclaimer and 305 | waiver of all liability. 306 | 307 | Section 6 -- Term and Termination. 308 | 309 | a. This Public License applies for the term of the Copyright and 310 | Similar Rights licensed here. However, if You fail to comply with 311 | this Public License, then Your rights under this Public License 312 | terminate automatically. 313 | 314 | b. Where Your right to use the Licensed Material has terminated under 315 | Section 6(a), it reinstates: 316 | 317 | 1. automatically as of the date the violation is cured, provided 318 | it is cured within 30 days of Your discovery of the 319 | violation; or 320 | 321 | 2. upon express reinstatement by the Licensor. 322 | 323 | For the avoidance of doubt, this Section 6(b) does not affect any 324 | right the Licensor may have to seek remedies for Your violations 325 | of this Public License. 326 | 327 | c. For the avoidance of doubt, the Licensor may also offer the 328 | Licensed Material under separate terms or conditions or stop 329 | distributing the Licensed Material at any time; however, doing so 330 | will not terminate this Public License. 331 | 332 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 333 | License. 334 | 335 | Section 7 -- Other Terms and Conditions. 336 | 337 | a. The Licensor shall not be bound by any additional or different 338 | terms or conditions communicated by You unless expressly agreed. 339 | 340 | b. Any arrangements, understandings, or agreements regarding the 341 | Licensed Material not stated herein are separate from and 342 | independent of the terms and conditions of this Public License. 343 | 344 | Section 8 -- Interpretation. 345 | 346 | a. For the avoidance of doubt, this Public License does not, and 347 | shall not be interpreted to, reduce, limit, restrict, or impose 348 | conditions on any use of the Licensed Material that could lawfully 349 | be made without permission under this Public License. 350 | 351 | b. To the extent possible, if any provision of this Public License is 352 | deemed unenforceable, it shall be automatically reformed to the 353 | minimum extent necessary to make it enforceable. If the provision 354 | cannot be reformed, it shall be severed from this Public License 355 | without affecting the enforceability of the remaining terms and 356 | conditions. 357 | 358 | c. No term or condition of this Public License will be waived and no 359 | failure to comply consented to unless expressly agreed to by the 360 | Licensor. 361 | 362 | d. Nothing in this Public License constitutes or may be interpreted 363 | as a limitation upon, or waiver of, any privileges and immunities 364 | that apply to the Licensor or You, including from the legal 365 | processes of any jurisdiction or authority. 366 | 367 | ======================================================================= 368 | 369 | Creative Commons is not a party to its public 370 | licenses. Notwithstanding, Creative Commons may elect to apply one of 371 | its public licenses to material it publishes and in those instances 372 | will be considered the “Licensor.” The text of the Creative Commons 373 | public licenses is dedicated to the public domain under the CC0 Public 374 | Domain Dedication. Except for the limited purpose of indicating that 375 | material is shared under a Creative Commons public license or as 376 | otherwise permitted by the Creative Commons policies published at 377 | creativecommons.org/policies, Creative Commons does not authorize the 378 | use of the trademark "Creative Commons" or any other trademark or logo 379 | of Creative Commons without its prior written consent including, 380 | without limitation, in connection with any unauthorized modifications 381 | to any of its public licenses or any other arrangements, 382 | understandings, or agreements concerning use of licensed material. For 383 | the avoidance of doubt, this paragraph does not form part of the 384 | public licenses. 385 | 386 | Creative Commons may be contacted at creativecommons.org. 387 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Octokit Handbook 2 | 3 | Octokit is a set of official GitHub libraries written in different languages in order simplify the usage of the GitHub platform. 4 | 5 | This handbook aims to help maintainers to create and maintain Octokit libraries as well as community-maintained equivalents that are not an official Octokit library (yet). 6 | 7 | 8 | 9 | - [Authentication](#authentication) 10 | - [Personal Access Tokens](#personal-access-tokens) 11 | - [User access tokens (OAuth)](#user-access-tokens-oauth) 12 | - [Installation access tokens (GitHub Apps)](#installation-access-tokens-github-apps) 13 | - [OAuth App authentication (`client_id`/`client_secret`)](#oauth-app-authentication-client_idclient_secret) 14 | - [GitHub App authentication (JSON Web Token)](#github-app-authentication-json-web-token) 15 | - [Rest API](#rest-api) 16 | - [To consider](#to-consider) 17 | - [Octokit Implementations](#octokit-implementations) 18 | - [Gotchas](#gotchas) 19 | - [Inputs without namespace](#inputs-without-namespace) 20 | - [Some “list” endpoint response that paginate have a different response structure](#some-list-endpoint-response-that-paginate-have-a-different-response-structure) 21 | - [Some “list” endpoint respond with `204` or `409` if the repository is empty](#some-list-endpoint-respond-with-204-or-409-if-the-repository-is-empty) 22 | - [Same route, different results](#same-route-different-results) 23 | - [Supporting GitHub Enterprise](#supporting-github-enterprise) 24 | - [Preview headers](#preview-headers) 25 | - [`/repositories/:id` and `/users/:id` are currently not documented / not part of the OpenAPI specification](#repositoriesid-and-usersid-are-currently-not-documented--not-part-of-the-openapi-specification) 26 | - [URL parameters should be encoded](#url-parameters-should-be-encoded) 27 | - [Rate limits](#rate-limits) 28 | - [200 Response to HEAD requests](#200-response-to-head-requests) 29 | - [GraphQL](#graphql) 30 | - [Implementations:](#implementations) 31 | - [Gotchas](#gotchas-1) 32 | - [Pagination](#pagination) 33 | - [Preview headers](#preview-headers-1) 34 | - [Differences between api.github.com and GHE](#differences-between-apigithubcom-and-ghe) 35 | - [OAuth Apps](#oauth-apps) 36 | - [Implementations](#implementations) 37 | - [GitHub’s API endpoints for OAuth App clients](#githubs-api-endpoints-for-oauth-app-clients) 38 | - [Security considerations](#security-considerations) 39 | - [Resources](#resources) 40 | - [Webhooks](#webhooks) 41 | - [Implementations](#implementations-1) 42 | - [Gotchas](#gotchas-2) 43 | - [GitHub Apps](#github-apps) 44 | - [Implementations](#implementations-2) 45 | - [Gotchas](#gotchas-3) 46 | - [Replication lag after creating installation token](#replication-lag-after-creating-installation-token) 47 | - [Scopes are not supported](#scopes-are-not-supported) 48 | - [Permissions & repositories for OAuth tokens cannot be limited](#permissions--repositories-for-oauth-tokens-cannot-be-limited) 49 | - [Differences between api.github.com and GHE](#differences-between-apigithubcom-and-ghe-1) 50 | - [Actions](#actions) 51 | - [Shared resources](#shared-resources) 52 | - [OpenAPI](#openapi) 53 | - [Webhooks](#webhooks-1) 54 | - [Fixtures](#fixtures) 55 | - [GraphQL Schema](#graphql-schema) 56 | - [GitHub App Permissions](#github-app-permissions) 57 | - [License](#license) 58 | 59 | 60 | 61 | # Authentication 62 | 63 | There are different means of authentication. 64 | 65 | See https://github.com/octokit/auth.js for a reference implementation for the most common strategies. 66 | 67 | ## Personal Access Tokens 68 | 69 | Personal access tokens are passed in the `Authorization` header. Example: `Authorization: token `. 70 | 71 | Personal access tokens cannot be created programmatically. They work the same as user access tokens created by OAuth apps. They have a set of scopes and can optionally be set to expire (the current default is 30 days from token creation). 72 | 73 | Personal access tokens are meant for testing. You can create one at https://github.com/settings/tokens/new. 74 | 75 | ## User access tokens (OAuth) 76 | 77 | User access tokens can be created by GitHub Apps (they are called [user-to-server tokens](https://docs.github.com/en/developers/apps/identifying-and-authorizing-users-for-github-apps)) or by OAuth Apps (they are just called [access tokens](https://docs.github.com/en/developers/apps/authorizing-oauth-apps)). There are several differences betweet the user access tokens created by GitHub Apps vs OAuth Apps. 78 | 79 | 1. **Access** 80 | 81 | OAuth Apps: user access tokens have access to all of the user's repositories. Access to organizations [can be restricted](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/restricting-access-to-your-organizations-data). Access to organizations with restrictions enabled can be granted if the user is an owner, or [requested](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/approving-oauth-apps-for-your-organization) if the user is a member. 82 | 83 | GitHub Apps: user access tokens inherit the user permissions of the app (see below) and can only access repositories and organizations that the app is installed on. Uninstalling an app or suspending an installation immediately revokes access to the respective repository/organization resources. 84 | 85 | 1. **Scopes vs Permissions.** 86 | 87 | OAuth Apps have the concept of [scopes](https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes). The app itself does not have a global set of scopes, each new user token can be granted any combination of scopes. 88 | 89 | GitHub Apps have the concept of [permissions](https://docs.github.com/en/rest/reference/permissions-required-for-github-apps). The app registration includes permissions for repositories, organizations, and users. User permissions (e.g. `starring`, `blocking`) are inherited directly from the app's registration settings. The permissions for repositories (e.g. `issues`, `pull_requests`) and organizations (e.g. `administration`, `team_discussions`) are inherited from each installation. Installation permissions are not automatically updated, each time a GitHub App requests additional repository/organization permissions, they have to be approved for each installation. 90 | 91 | 1. **Web flow** 92 | 93 | The OAuth web flow for [OAuth Apps](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-flow) and [GitHub Apps](https://docs.github.com/en/developers/apps/identifying-and-authorizing-users-for-github-apps#web-application-flow) are nearly identical. OAuth apps accept a `?scope` query parameter to request any set of scopes. 94 | 95 | 1. **Device flow** 96 | 97 | The device flow works the same for OAuth Apps and GitHub Apps. 98 | 99 | 1. **Expiring tokens** 100 | 101 | [Expiring user access tokens](https://docs.github.com/en/developers/apps/refreshing-user-to-server-access-tokens) are only supported by GitHub Apps and are opt-in by the app owners. 102 | 103 | ## Installation access tokens (GitHub Apps) 104 | 105 | Installation access tokens can be created by a GitHub App in order to access repository and organization resources for an installation. Installation access tokens expire after 1 hour. Using an installation access token, a GitHub App can interact on repositories or organizations as itself (e.g. create comments). 106 | 107 | **Gotchas** 108 | 109 | - Installation tokens cannot be used for authenticated git operations the same way that OAuth/Personal Access Tokens can be. E.g. this git URL will not work `https://${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git`. As a workaround, this scheme works with installation tokens / GitHub Action tokens: 110 | `https://x-access-token:{GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git` 111 | - The [OAuth device flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#device-flow) does not require the `client_secret` so it can be safely used on clients without the need of maintaining a custom server. However, the flow is not possible for browsers due to CORS restrictions. 112 | 113 | ## OAuth App authentication (`client_id`/`client_secret`) 114 | 115 | OAuth apps can authenticate using its `client_id` and `client_secret` in order to avoid the low rate limiting for unauthenticated requests. `client_id` and `client_secret` have to be passed as Basic authorization in the `Authorization` header. 116 | 117 | **Gotchas** 118 | 119 | - OAuth App authentication does not work for GraphQL queries 120 | - The API endpoint to exchange a `code` for an OAuth access token is [`POST http(s)://[hostname]/login/oauth/access_token`](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github). It does not use the standard `api.github.com` host or `/v3/api` path for GitHub enterprise and is not documented as part of the REST API. The `Accept` & `Content-Type` headers must be set to `application/json`. The server does not respond with an `4xx` error code, even if the request failed. You have to check for the presence of the `"error"` response key instead. 121 | 122 | ## GitHub App authentication (JSON Web Token) 123 | 124 | A JWT is passed in the `Authorization` header. Example: `Authorization: Bearer `. In order to generate a JWT, a GitHub Apps private key is required. [See Authenticating as a GitHub App](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app). 125 | 126 | Only a few REST API endpoints require JWT authentication 127 | 128 | 1. All routes starting with `/app` 129 | 2. `GET /orgs/:org/installation` 130 | 3. `GET /repos/:owner/:repo/installation` 131 | 4. `GET /users/:username/installation` 132 | 133 | For all other routes and for GraphQL queries, an installation access token or user access token needs to be created. 134 | 135 | An installation access token can be retrieved using the [`POST /app/installations/:installation_id/access_tokens`](https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app) endpoint. Usually the `:installation_id` is retrieved from a webhook event payload or from [`GET /app/installations`](https://developer.github.com/v3/apps/#list-installations). Installation tokens can only access repositories that the app was installed on, and expire after 1h. 136 | 137 | GitHub Apps can also create OAuth tokens for users, every GitHub App also has `client_id` and `client_secret` just like OAuth Apps. However, these cannot be used like [OAuth App authentication](#oauth-app-authentication), GitHub Apps can only use JWT in order to authenticate as itself. 138 | 139 | **Gotchas** 140 | 141 | - JWT authentication does not work for GraphQL queries 142 | - When using an Installation Access Token directly after creation, a request might error with `401` or `403`. Not because the token is invalid or the permissions are not sufficient, but because the token or the permissions did not yet propagate across all read-only databases. See https://github.com/octokit/auth-app.js/issues/65 and https://github.com/octokit/auth-app.js/issues/589 for more details 143 | - When receiving one of the following errors 144 | 145 | > 'Expiration time' claim ('exp') must be a numeric value representing the future time at which the assertion expires 146 | 147 | or 148 | 149 | > 'Issued at' claim ('iat') must be an Integer representing the time that the assertion was issued 150 | 151 | The most likely problem is that the system time is out of sync with GitHub’s APIs time. 152 | 153 | In order to mitigate the problem, read out the `date` header from the error response, use it to calculate the approximate difference between the system time and GitHub’s API time, then calculate the JWT again and retry the request. 154 | 155 | # Rest API 156 | 157 | - **complete**: create methods for all endpoints, or at least document all if the Octokit library is using a generic request library. See OpenAPI in [shared resources](#shared-resources) 158 | - **generated**: in order to implement and document the complete set of REST API route endpoints, and to (automatically) keep it up-to-date with new endpoints, the codebase should be generated. See OpenAPI in [shared resources](#shared-resources) 159 | 160 | ## To consider 161 | 162 | - Set media type format per request, but without overriding current accept header, as it might include previews (GHE version 3.2 and lower) 163 | - Implement `Sunset` / `Deprecation` headers (_to be documented_) 164 | 165 | ## Octokit Implementations 166 | 167 | - https://github.com/octokit/octokit.net 168 | - https://github.com/octokit/octokit.rb 169 | - https://github.com/octokit/rest.js 170 | 171 | Community implementations 172 | 173 | - https://github.com/google/go-github 174 | 175 | ## Gotchas 176 | 177 | ### Inputs without namespace 178 | 179 | - https://docs.github.com/en/rest/reference/markdown#render-a-markdown-document-in-raw-mode 180 | - https://docs.github.com/en/rest/reference/repos#upload-a-release-asset 181 | 182 | ### Some “list” endpoint response that paginate have a different response structure 183 | 184 | They have a `total_count` key in the response (search also has `incomplete_results`, `/installation/repositories` also has `repository_selection`), as well as a key with the list of the items which name varies from endpoint to endpoint 185 | 186 | - https://developer.github.com/v3/search/ (all endpoints, key `items`) 187 | - https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref (key: `check_runs`) 188 | - https://developer.github.com/v3/checks/runs/#list-check-runs-in-a-check-suite (key: `check_runs`) 189 | - https://developer.github.com/v3/checks/suites/#list-check-suites-for-a-specific-ref (key: `check_suites`) 190 | - https://developer.github.com/v3/apps/installations/#list-repositories (key: `repositories`) 191 | - https://developer.github.com/v3/apps/installations/#list-repositories-accessible-to-the-user-for-an-installation (key: `repositories`) 192 | - https://developer.github.com/v3/actions/artifacts/#list-workflow-run-artifacts 193 | `GET /repos/:owner/:repo/actions/runs/:run_id/artifacts`, key: `artifacts` 194 | - https://developer.github.com/v3/actions/secrets/#list-secrets-for-a-repository 195 | `GET /repos/:owner/:repo/actions/secrets`, key: `secrets` 196 | - https://developer.github.com/v3/actions/workflows/#list-repository-workflows 197 | `GET /repos/:owner/:repo/actions/workflows`, key: `workflows` 198 | - https://developer.github.com/v3/actions/workflow_jobs/#list-jobs-for-a-workflow-run 199 | `GET /repos/:owner/:repo/actions/runs/:run_id/jobs`, key: `jobs` 200 | - https://developer.github.com/v3/actions/workflow_runs/#list-workflow-runs 201 | `GET /repos/:owner/:repo/actions/workflows/:workflow_id/runs`, key: `workflow_runs` 202 | - https://developer.github.com/v3/actions/workflow_runs/#list-repository-workflow-runs 203 | `GET /repos/:owner/:repo/actions/runs`, key: `workflow_runs` 204 | 205 | An Octokit library should normalize these responses so that paginated results are always returned following the same structure. 206 | 207 | **IMPORTANT**: **If the list response has only one page, no `Link` header is provided**. Checking for the `Link` header alone is not sufficient to check whether a response is paginated or not. For the exceptions with the namespace, a fallback check for the route paths has to be added in order to normalize the response. You can check for the `total_count` property to be present, but must make sure it’s not [Get the combined status for a specific ref](https://docs.github.com/en/rest/reference/repos#get-the-combined-status-for-a-specific-reference) request, because it includes `total_count`, too, while not being a paginating response. 208 | 209 | ### Some “list” endpoint respond with `204` or `409` if the repository is empty 210 | 211 | See [octokit/plugin-paginate-rest.js#158](https://github.com/octokit/plugin-paginate-rest.js/issues/158). 212 | 213 | For example, if a repository is empty: 214 | 215 | - `GET /repos/{owner}/{repo}/contributors` responds without a response body and a `204` status code 216 | - `GET /repos/{owner}/{repo}/commits` responds without a `409` error 217 | 218 | ``` 219 | { 220 | "message": "Git Repository is empty.", 221 | "documentation_url": "https://docs.github.com/rest/reference/repos#list-commits" 222 | } 223 | ``` 224 | 225 | A pagination method should return an empty array in both cases. 226 | 227 | ### Same route, different results 228 | 229 | [Get contents](https://developer.github.com/v3/repos/contents/#get-contents) 230 | 231 | GET /repos/:owner/:repo/contents/:path 232 | 233 | If `:path` points to a folder, the response is an array of files. Otherwise the response is an object. 234 | 235 | ### Supporting GitHub Enterprise 236 | 237 | Octokit should support all GitHub Enterprise versions that are currently supported by GitHub. Besides newly introduced endpoints that are not backported to GitHub Enterprise, there are also some endpoints that are different, e.g. while endpoints on api.github.com just work, on some GHE versions (3.2 and below) they might still need preview headers. 238 | 239 | Note that the base URLs are more complicated. For https://api.github.com, the root URL for all REST APIs is `https://api.github.com`, for GHE the root URL is `http(s)://[hostname]/api/v3`, except the [Management Console endpoints](https://docs.github.com/en/enterprise-server@3.0/rest/reference/enterprise-admin#endpoint-urls), which root URL is just `http(s)://hostname/`. 240 | 241 | While not directly related to the REST API, it’s worth noting that for GraphQL, the endpoint URL for `api.github.com` is `https://api.github.com/graphql`, while for GHE it’s `http(s)://[hostname]/api/graphql`. 242 | 243 | ### Preview headers 244 | 245 | The concept of _preview_ headers has been deprecated from api.github.com but it still exists in GHE version 3.2 and below. Instead of using _preview_ headers going forward, new features are now being tested using beta previews that users have to opt-in. 246 | 247 | When _preview_ headers are set implicitly, a warning should be logged to make the user aware that these APIs are subject to change. 248 | 249 | ### `/repositories/:id` and `/users/:id` are currently not documented / not part of the OpenAPI specification 250 | 251 | Repositories and usernames can change. For integrators, it would be more appropriate to use the repository ID as it does not change, but these endpoints are currently not documented, hence Octokit is currently not implementing them explicitly. It might be mentioned in the Octokit library’s documentation though. 252 | 253 | ### URL parameters should be encoded 254 | 255 | For example: [`GET /repos/{owner}/{repo}/compare/{base}...{head}`](https://docs.github.com/en/rest/reference/repos#compare-two-commits). The `base` and `head` parameters are branch names, which can include `/` and other special characters. 256 | 257 | ### Rate limits 258 | 259 | See https://docs.github.com/en/rest/guides/best-practices-for-integrators#dealing-with-rate-limits and https://docs.github.com/en/rest/guides/best-practices-for-integrators?apiVersion=2022-11-28#dealing-with-secondary-rate-limits 260 | 261 | One important gotcha is that in some circumstances, a `Retry-After` header will not be set in case of a secondary rate limit. In that case the time to wait should default to 60 seconds. 262 | 263 | ### 200 Response to HEAD requests 264 | 265 | Some of GitHub's REST API endpoints respond with a `200` status to `HEAD` requests. See https://github.com/octokit/rest.js/pull/842. Arguably the response should be `204`, and it is in some cases, but not consistently. 266 | 267 | # GraphQL 268 | 269 | ## Implementations: 270 | 271 | - https://github.com/octokit/graphql.js 272 | 273 | ## Gotchas 274 | 275 | - Watch this talk: https://www.youtube.com/watch?v=i5pIszu9MeM 276 | 277 | ### Pagination 278 | 279 | _TBD_, see https://github.com/octokit/graphql.js/issues/61#issuecomment-643392492 for an idea how a generic pagination API could be implemented for GraphQL 280 | 281 | ### Preview headers 282 | 283 | The concept of _preview_ headers is in the process of being deprecated. 284 | 285 | ### Differences between api.github.com and GHE 286 | 287 | _TBD_ 288 | 289 | # OAuth Apps 290 | 291 | If a 3rd party integration (“client”) needs to access protected resources of a GitHub user (“resource owner”), a GitHub OAuth App needs to be registered for the client. Once registered, a client can request a GitHub user to grant authorization to selected protected resources (“scope”) to the client. Once an authorization was granted, GitHub can issue OAuth access tokens to the client in order to send requests on behalf of the user. 292 | 293 |
294 | 295 | 296 | 297 | In order to initiate a grant authorization request, the client redirects a user to GitHub’s [authorization endpoint](https://tools.ietf.org/html/rfc6749#section-3.1) on github.com, see [Request a user’s identity](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#1-request-a-users-github-identity). 298 | 299 | The first time the user opens the page, all scopes requested by the client are displayed for the user to review. If the user grants the authorization request, they get redirected to the OAuth App’s redirect URL, with an additional `?code=` query parameter set to the grant’s [authorization code](https://tools.ietf.org/html/rfc6749#section-1.3.1). GitHub does not support [implicit grants](https://tools.ietf.org/html/rfc6749#section-4.2). 300 | 301 |
302 |
303 | 304 | 305 | 306 | The client then exchanges the authorization code and the OAuth App’s `client_id` and `client_secret` for an OAuth access token using GitHub’s [token endpoint](https://tools.ietf.org/html/rfc6749#section-3.2). Note that GitHub’s OAuth Access tokens do not expire and there are no refresh tokens as described in the [OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-6). 307 | 308 |
309 | 310 | ## Implementations 311 | 312 | - Authentication strategy for OAuth App: https://github.com/octokit/auth-oauth-app.js 313 | - Authentication strategy for OAuth User: https://github.com/octokit/auth-oauth-user.js 314 | - Authentication strategy for device flow: https://github.com/octokit/auth-oauth-device.js 315 | - SDK: https://github.com/octokit/oauth-app.js 316 | - Others: https://github.com/octokit/oauth-authorization-url.js 317 | 318 | ## GitHub’s API endpoints for OAuth App clients 319 | 320 | 1. **Authorization endpoint** ([OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-3.1)): 321 | [https://github.com/login/oauth/authorize](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#1-request-a-users-github-identity) 322 | 2. **Redirect endpoint:** client URL, configured during the OAuth App registration. It can be changed in the OAuth App’s settings page on github.com 323 | 3. **Token endpoint** ([OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-3.2)): 324 | [`POST https://github.com/login/oauth/access_token`](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github) 325 | 326 | Besides the endpoints required by the OAuth 2.0 specification, GitHub provides additional endpoints 327 | 328 | 1. Check if a token is still valid (think: check session) 329 | [`POST /applications/:client_id/token`](https://docs.github.com/en/rest/reference/apps#check-a-token) 330 | 2. Reset a single token(think: I’ve accidentally posted my token on Twitter for everyone to see, and I need to invalidate it and get a new one) 331 | [`PATCH /applications/:client_id/token`](https://docs.github.com/en/rest/reference/apps#reset-a-token) 332 | 3. Invalidate (revoke) a single token (think: sign out) 333 | [`DELETE /applications/:client_id/token`](https://docs.github.com/en/rest/reference/apps#delete-an-app-token) 334 | 4. Invalidate (revoke) all tokens for a single user (think: uninstall the app) 335 | [`DELETE /applications/:client_id/grant`](https://docs.github.com/en/rest/reference/apps#delete-an-app-authorization) 336 | 337 | There are no endpoints for OAuth App clients to: 338 | 339 | 1. Retrieve its access tokens. 340 | 2. Retrieve its authorizations. 341 | 3. Revoke all authorizations at once. 342 | 343 | The client owner(s) can revoke all authorizations at once on the OAuth App’s settings page. If the client requires to retrieve previously created access tokens it needs to persist them. 344 | 345 | ## Security considerations 346 | 347 | - The `client_secret` must not be shared with user-accessible parts of the OAuth client, such as browser-based application clients or native applications, in order to prevent counterfeit clients ([compare Section 10.1 of OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-10.1)). If an attacker would manage to intercept the redirect after authorization was granted, they could use the known `client_id` and `client_secret` to generate a token themselves. GitHub does not support the [PKCE extension](https://tools.ietf.org/html/rfc7636). 348 | - The client should request access tokens with the minimal scope necessary. 349 | - Avoid passing access tokens as part of URLs. Browser history or request logs can expose tokens unknowingly. The client’s configured `redirect_url` must point to one of two things: 350 | 1. The client back-end, which can directly retrieve the OAuth Access token and use it to authenticate as the user. The Authorization server can persist the token if future requests authenticated as the user will be necessary for the OAuth app. 351 | 2. The client front-end, which then needs to send the authorization code to the client back-end in exchange for the OAuth Access token. The client back-end needs to expose a custom API endpoint for that operation. The client front-end can persist the OAuth Access token for future authentication against GitHub’s REST or GraphQL API. 352 | 353 | See also: https://tools.ietf.org/html/rfc6749#section-10 354 | 355 | ## Resources 356 | 357 | - [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) 358 | Applied to GitHub.com, the [OAuth 2.0 roles](https://tools.ietf.org/html/rfc6749#section-1.1) are: 359 | - **resource owner**: GitHub User 360 | - **resource server**: api.github.com 361 | - **authorization server**: github.com 362 | - **client**: the 3rd party integration that needs to send requests on behalf of the user. A server component that has access to both `client_id` and `client_secret` is required, in order to exchange an authorization grant for an access token. 363 | - [Authorizating OAuth Apps on GitHub](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-flow) 364 | 365 | # Webhooks 366 | 367 | ## Implementations 368 | 369 | - https://github.com/octokit/webhooks.js 370 | 371 | ## Gotchas 372 | 373 | **Differences between api.github.com and GHE** 374 | 375 | _TBD_ 376 | 377 | # GitHub Apps 378 | 379 | ## Implementations 380 | 381 | - Authentication strategy: https://github.com/octokit/auth-app.js/ 382 | - SDK: https://github.com/octokit/app.js/ 383 | 384 | ## Gotchas 385 | 386 | ### Replication lag after creating installation token 387 | 388 | It is possible that when sending requests with an installation token that was created just before, the server might respond with a 404 (Not Found for GET/HEAD) or 403 (Bad Credentials), not because the installation token is invalid but because there is a short replication lag on GitHub’s site. 389 | 390 | ### Scopes are not supported 391 | 392 | The `?scope` query parameter is not supported for the OAuth web flow. The OAuth tokens created by GitHub apps are constrained by the permission accepted by each installation. 393 | 394 | ### Permissions & repositories for OAuth tokens cannot be limited 395 | 396 | When [`creating an installation access token`](https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app), two parameters can be passed to limit the access for the token: 397 | 398 | 1. `permissions` - a subset of the installation's permissions 399 | 2. `repositories` or `repository_ids` - a subset of the installation's repositories. 400 | 401 | There are no possibility to reduce permissions/repository access for user-to-server (OAuth) access tokens as of February 2021 402 | 403 | ### Differences between api.github.com and GHE 404 | 405 | _TBD_ 406 | 407 | # Actions 408 | 409 | Actions are run in Docker containers, which have access to the current source code as well as environment variables. The two most relevant are 410 | 411 | 1. `GITHUB_TOKEN`: An authentication token used to make API requests to GitHub 412 | 2. `GITHUB_EVENT_PATH`: Path to a JSON file containing the event payload that triggered the action. 413 | 414 | See [GitHub Actions Environment variables](https://docs.github.com/en/actions/reference/environment-variables) for more. 415 | 416 | The Octokit library reads out the token, instantiates an authenticated API to utilize the REST/GraphQL API and provides the event name and payload as a parameter, similar to the handling of Webhooks. 417 | 418 | **Implementations** 419 | 420 | - SDK: https://github.com/octokit/action.js 421 | - toolkit: https://github.com/actions/toolkit 422 | 423 | **Gotchas** 424 | 425 | - The `GITHUB_TOKEN` cannot be used as expected for an authenticated git remote URL: `https://${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git`, 426 | instead it needs to be [used like an installation access token](https://docs.github.com/en/developers/apps/authenticating-with-github-apps#http-based-git-access-by-an-installation): 427 | `https://x-access-token:{GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git` 428 | 429 | # Shared resources 430 | 431 | ## OpenAPI 432 | 433 | https://github.com/octokit/openapi 434 | 435 | JSON API specs for all REST API endpoints for `api.github.com` as well as all currently supported GitHub Enterprise versions. [https://github.com/octokit/openapi](https://github.com/octokit/openapi) pulls changes from [GitHub's official OpenAPI spec](https://github.com/github/rest-api-description/) and adds a `x-octokit` extension with relevant information for Octokit libraries, such as a list of changes for each endpoint, so that OpenAPI operation ID changes don't need to result in breaking changes, but instead deprecations can be implemented. 436 | 437 | In order to act on new releases, install the [openapi-release-notifier](https://github.com/apps/openapi-release-notifier) GitHub App. See the app’s description for further information and an example on how to trigger a GitHub Action Workflow each time a new OpenAPI spec version is released. 438 | 439 | ## Webhooks 440 | 441 | https://github.com/octokit/webhooks 442 | 443 | Always up-to-date, machine-readable schemas for all GitHub Events 444 | 445 | ## Fixtures 446 | 447 | https://github.com/octokit/fixtures, https://github.com/octokit/fixtures-server 448 | 449 | Always up-to-date fixtures for REST API endpoints that can be used for tests so they don’t depend on api.github.com or GitHub Enterprise Server installations 450 | 451 | A mock-server binary can be downloaded from https://github.com/octokit/fixtures-server/releases/latest. It is also continuously deployed. See https://github.com/octokit/fixtures-server#usage 452 | 453 | Fixtures are updated using a nightly cron job. All requests & responses are [normalized](https://github.com/octokit/fixtures/blob/master/HOW_IT_WORKS.md#normalizations) in order to detect changes. When a change occurs, a pull request is opened for review, see https://github.com/octokit/fixtures/pull/177. When merged, a new release is published automatically based on commit message conventions, see https://github.com/octokit/fixtures/blob/master/CONTRIBUTING.md#releases. 454 | 455 | New fixtures can be added by creating a new scenario, see https://github.com/octokit/fixtures/blob/master/HOW_IT_WORKS.md. 456 | 457 | ## GraphQL Schema 458 | 459 | https://github.com/octokit/graphql-schema 460 | 461 | Always up-to-date GraphQL schema, that can be used to generate types for GraphQL APIs 462 | 463 | ## GitHub App Permissions 464 | 465 | https://github.com/octokit/app-permissions/ 466 | 467 | Machine-readable, always up-to-date GitHub App permissions 468 | 469 | # License 470 | 471 | [CC BY 4.0](LICENSE.md) 472 | -------------------------------------------------------------------------------- /assets/oauth-code-redirect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/octokit/handbook/d715d9bfc54acf500e980db09c994d82fe1fa1f5/assets/oauth-code-redirect.png -------------------------------------------------------------------------------- /assets/oauth-request-access.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/octokit/handbook/d715d9bfc54acf500e980db09c994d82fe1fa1f5/assets/oauth-request-access.png --------------------------------------------------------------------------------