Skip to content

Commit 6573647

Browse files
authored
Merge pull request #16323 from github/repo-sync
repo sync
2 parents 26c2b97 + 273d79d commit 6573647

File tree

10 files changed

+612
-7
lines changed

10 files changed

+612
-7
lines changed
Loading

content/developers/apps/building-github-apps/creating-a-github-app.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,9 @@ topics:
5252
1. By default, to improve your app's security, your app will use expiring user authorization tokens. To opt-out of using expiring user tokens, you must deselect "Expire user authorization tokens". To learn more about setting up a refresh token flow and the benefits of expiring user tokens, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)."
5353
![Option to opt-in to expiring user tokens during GitHub Apps setup](/assets/images/github-apps/expire-user-tokens-selection.png)
5454
1. If your app authorizes users using the OAuth flow, you can select **Request user authorization (OAuth) during installation** to allow people to authorize the app when they install it, saving a step. If you select this option, the "Setup URL" becomes unavailable and users will be redirected to your "User authorization callback URL" after installing the app. See "[Authorizing users during installation](/apps/installing-github-apps/#authorizing-users-during-installation)" for more information.
55-
![Request user authorization during installation](/assets/images/github-apps/github_apps_request_auth_upon_install.png)
55+
![Request user authorization during installation](/assets/images/github-apps/github_apps_request_auth_upon_install.png){% if device-flow-is-opt-in %}
56+
1. If your GitHub App will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
57+
![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
5658
1. If additional setup is required after installation, add a "Setup URL" to redirect users to after they install your app.
5759
![Field for the setup URL of your GitHub App ](/assets/images/github-apps/github_apps_setup_url.png)
5860

content/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,9 +124,9 @@ curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre
124124

125125
{% endnote %}
126126

127-
The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.
127+
The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.
128128

129-
For more information about authorizing users using the device flow, see "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps#device-flow)".
129+
{% if device-flow-is-opt-in %}Before you can use the device flow to identify and authorize users, you must first enable it in your app's settings. For more information on enabling device flow, see "[Modifying a GitHub App](/developers/apps/managing-github-apps/modifying-a-github-app)." {% endif %}For more information about authorizing users using the device flow, see "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps#device-flow)."
130130

131131
## Check which installation's resources a user can access
132132

content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,12 @@ curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre
125125

126126
The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.
127127

128+
{% if device-flow-is-opt-in %}
129+
130+
Before you can use the device flow to authorize and identify users, you must first enable it in your app's settings. For more information about enabling the device flow in your app, see "[Modifying an OAuth App](/developers/apps/managing-oauth-apps/modifying-an-oauth-app)" for OAuth Apps and "[Modifying a GitHub App](/developers/apps/managing-github-apps/modifying-a-github-app)" for GitHub Apps.
131+
132+
{% endif %}
133+
128134
### Overview of the device flow
129135

130136
1. Your app requests device and user verification codes and gets the authorization URL where the user will enter the user verification code.
@@ -254,10 +260,12 @@ If you make more than one access token request (`POST {% data variables.product.
254260
| `unsupported_grant_type` | The grant type must be `urn:ietf:params:oauth:grant-type:device_code` and included as an input parameter when you poll the OAuth token request `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`.
255261
| `incorrect_client_credentials` | For the device flow, you must pass your app's client ID, which you can find on your app settings page. The `client_secret` is not needed for the device flow.
256262
| `incorrect_device_code` | The device_code provided is not valid.
257-
| `access_denied` | When a user clicks cancel during the authorization process, you'll receive a `access_denied` error and the user won't be able to use the verification code again.
263+
| `access_denied` | When a user clicks cancel during the authorization process, you'll receive a `access_denied` error and the user won't be able to use the verification code again.{% if device-flow-is-opt-in %}
264+
| `device_flow_disabled` | Device flow has not been enabled in the app's settings. For more information, see "[Device flow](#device-flow)."{% endif %}
258265

259266
For more information, see the "[OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628#section-3.5)."
260267

268+
261269
## Non-Web application flow
262270

263271
Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.

content/developers/apps/building-oauth-apps/creating-an-oauth-app.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ topics:
5353
**Note:** OAuth Apps cannot have multiple callback URLs, unlike {% data variables.product.prodname_github_apps %}.
5454

5555
{% endnote %}
56-
{% endif %}
57-
10. Click **Register application**.
56+
{% endif %}{% if device-flow-is-opt-in %}
57+
1. If your OAuth App will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
58+
![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
59+
2. Click **Register application**.
5860
![Button to register an application](/assets/images/oauth-apps/oauth_apps_register_application.png)

content/developers/apps/managing-github-apps/modifying-a-github-app.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ topics:
1818
{% data reusables.user-settings.github_apps %}
1919
{% data reusables.user-settings.modify_github_app %}
2020
5. In "Basic information", modify the GitHub App information that you'd like to change.
21-
![Basic information section for your GitHub App](/assets/images/github-apps/github_apps_basic_information.png)
21+
![Basic information section for your GitHub App](/assets/images/github-apps/github_apps_basic_information.png){% if device-flow-is-opt-in %}
22+
1. If your GitHub App will use the device flow to identify and authorize users, click **Enable device flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
23+
![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
2224
6. Click **Save changes**.
2325
![Button to save changes for your GitHub App](/assets/images/github-apps/github_apps_save_changes.png)
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# docs-content 6307. OAuth device auth flow is opt in.
2+
versions:
3+
fpt: '*'
4+
ghec: '*'
5+
ghae: 'issue-6307'

lib/rest/static/apps/enabled-for-apps.json

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
{
22
"api.github.com": {
33
"actions": [
4+
{
5+
"slug": "get-github-actions-cache-usage-for-an-enterprise",
6+
"verb": "get",
7+
"requestPath": "/enterprises/{enterprise}/actions/cache/usage"
8+
},
9+
{
10+
"slug": "get-github-actions-cache-usage-for-an-organization",
11+
"verb": "get",
12+
"requestPath": "/orgs/{org}/actions/cache/usage"
13+
},
14+
{
15+
"slug": "list-repositories-with-github-actions-cache-usage-for-an-organization",
16+
"verb": "get",
17+
"requestPath": "/orgs/{org}/actions/cache/usage-by-repository"
18+
},
419
{
520
"slug": "get-github-actions-permissions-for-an-organization",
621
"verb": "get",
@@ -236,6 +251,11 @@
236251
"verb": "get",
237252
"requestPath": "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format}"
238253
},
254+
{
255+
"slug": "get-github-actions-cache-usage-for-a-repository",
256+
"verb": "get",
257+
"requestPath": "/repos/{owner}/{repo}/actions/cache/usage"
258+
},
239259
{
240260
"slug": "get-a-job-for-a-workflow-run",
241261
"verb": "get",

lib/rest/static/decorated/api.github.com.json

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,218 @@
359359
]
360360
}
361361
],
362+
"cache": [
363+
{
364+
"verb": "get",
365+
"requestPath": "/enterprises/{enterprise}/actions/cache/usage",
366+
"parameters": [
367+
{
368+
"name": "enterprise",
369+
"description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.",
370+
"in": "path",
371+
"required": true,
372+
"schema": {
373+
"type": "string"
374+
},
375+
"descriptionHTML": "<p>The slug version of the enterprise name. You can also substitute this value with the enterprise id.</p>"
376+
}
377+
],
378+
"x-codeSamples": [
379+
{
380+
"lang": "Shell",
381+
"source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/enterprises/ENTERPRISE/actions/cache/usage"
382+
},
383+
{
384+
"lang": "JavaScript",
385+
"source": "await octokit.request('GET /enterprises/{enterprise}/actions/cache/usage', {\n enterprise: 'enterprise'\n})"
386+
}
387+
],
388+
"summary": "Get GitHub Actions cache usage for an enterprise",
389+
"x-github": {
390+
"enabledForGitHubApps": true,
391+
"category": "actions",
392+
"subcategory": "cache"
393+
},
394+
"slug": "get-github-actions-cache-usage-for-an-enterprise",
395+
"category": "actions",
396+
"subcategory": "cache",
397+
"notes": [],
398+
"bodyParameters": [],
399+
"descriptionHTML": "<p>Gets the total GitHub Actions cache usage for an enterprise.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.\nYou must authenticate using an access token with the <code>admin:enterprise</code> scope to use this endpoint.</p>",
400+
"responses": [
401+
{
402+
"httpStatusCode": "200",
403+
"httpStatusMessage": "OK",
404+
"description": "<p>Response</p>",
405+
"payload": "{\n \"total_active_caches_size_in_bytes\": 3344284,\n \"total_active_caches_count\": 5\n}"
406+
}
407+
]
408+
},
409+
{
410+
"verb": "get",
411+
"requestPath": "/orgs/{org}/actions/cache/usage",
412+
"parameters": [
413+
{
414+
"name": "org",
415+
"in": "path",
416+
"required": true,
417+
"schema": {
418+
"type": "string"
419+
},
420+
"descriptionHTML": ""
421+
}
422+
],
423+
"x-codeSamples": [
424+
{
425+
"lang": "Shell",
426+
"source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/actions/cache/usage"
427+
},
428+
{
429+
"lang": "JavaScript",
430+
"source": "await octokit.request('GET /orgs/{org}/actions/cache/usage', {\n org: 'org'\n})"
431+
}
432+
],
433+
"summary": "Get GitHub Actions cache usage for an organization",
434+
"x-github": {
435+
"enabledForGitHubApps": true,
436+
"category": "actions",
437+
"subcategory": "cache"
438+
},
439+
"slug": "get-github-actions-cache-usage-for-an-organization",
440+
"category": "actions",
441+
"subcategory": "cache",
442+
"notes": [],
443+
"bodyParameters": [],
444+
"descriptionHTML": "<p>Gets the total GitHub Actions cache usage for an organization.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.\nYou must authenticate using an access token with the <code>read:org</code> scope to use this endpoint. GitHub Apps must have the <code>organization_admistration:read</code> permission to use this endpoint.</p>",
445+
"responses": [
446+
{
447+
"httpStatusCode": "200",
448+
"httpStatusMessage": "OK",
449+
"description": "<p>Response</p>",
450+
"payload": "{\n \"total_active_caches_size_in_bytes\": 3344284,\n \"total_active_caches_count\": 5\n}"
451+
}
452+
]
453+
},
454+
{
455+
"verb": "get",
456+
"requestPath": "/orgs/{org}/actions/cache/usage-by-repository",
457+
"parameters": [
458+
{
459+
"name": "org",
460+
"in": "path",
461+
"required": true,
462+
"schema": {
463+
"type": "string"
464+
},
465+
"descriptionHTML": ""
466+
},
467+
{
468+
"name": "per_page",
469+
"description": "Results per page (max 100)",
470+
"in": "query",
471+
"schema": {
472+
"type": "integer",
473+
"default": 30
474+
},
475+
"descriptionHTML": "<p>Results per page (max 100)</p>"
476+
},
477+
{
478+
"name": "page",
479+
"description": "Page number of the results to fetch.",
480+
"in": "query",
481+
"schema": {
482+
"type": "integer",
483+
"default": 1
484+
},
485+
"descriptionHTML": "<p>Page number of the results to fetch.</p>"
486+
}
487+
],
488+
"x-codeSamples": [
489+
{
490+
"lang": "Shell",
491+
"source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/orgs/ORG/actions/cache/usage-by-repository"
492+
},
493+
{
494+
"lang": "JavaScript",
495+
"source": "await octokit.request('GET /orgs/{org}/actions/cache/usage-by-repository', {\n org: 'org'\n})"
496+
}
497+
],
498+
"summary": "List repositories with GitHub Actions cache usage for an organization",
499+
"x-github": {
500+
"enabledForGitHubApps": true,
501+
"category": "actions",
502+
"subcategory": "cache"
503+
},
504+
"slug": "list-repositories-with-github-actions-cache-usage-for-an-organization",
505+
"category": "actions",
506+
"subcategory": "cache",
507+
"notes": [],
508+
"bodyParameters": [],
509+
"descriptionHTML": "<p>Lists repositories and their GitHub Actions cache usage for an organization.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.\nYou must authenticate using an access token with the <code>read:org</code> scope to use this endpoint. GitHub Apps must have the <code>organization_admistration:read</code> permission to use this endpoint.</p>",
510+
"responses": [
511+
{
512+
"httpStatusCode": "200",
513+
"httpStatusMessage": "OK",
514+
"description": "<p>Response</p>",
515+
"payload": "{\n \"total_count\": 2,\n \"repository_cache_usages\": [\n {\n \"full_name\": \"octo-org/Hello-World\",\n \"active_caches_size_in_bytes\": 2322142,\n \"active_caches_count\": 3\n },\n {\n \"full_name\": \"octo-org/server\",\n \"active_caches_size_in_bytes\": 1022142,\n \"active_caches_count\": 2\n }\n ]\n}"
516+
}
517+
]
518+
},
519+
{
520+
"verb": "get",
521+
"requestPath": "/repos/{owner}/{repo}/actions/cache/usage",
522+
"parameters": [
523+
{
524+
"name": "owner",
525+
"in": "path",
526+
"required": true,
527+
"schema": {
528+
"type": "string"
529+
},
530+
"descriptionHTML": ""
531+
},
532+
{
533+
"name": "repo",
534+
"in": "path",
535+
"required": true,
536+
"schema": {
537+
"type": "string"
538+
},
539+
"descriptionHTML": ""
540+
}
541+
],
542+
"x-codeSamples": [
543+
{
544+
"lang": "Shell",
545+
"source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/actions/cache/usage"
546+
},
547+
{
548+
"lang": "JavaScript",
549+
"source": "await octokit.request('GET /repos/{owner}/{repo}/actions/cache/usage', {\n owner: 'octocat',\n repo: 'hello-world'\n})"
550+
}
551+
],
552+
"summary": "Get GitHub Actions cache usage for a repository",
553+
"x-github": {
554+
"enabledForGitHubApps": true,
555+
"category": "actions",
556+
"subcategory": "cache"
557+
},
558+
"slug": "get-github-actions-cache-usage-for-a-repository",
559+
"category": "actions",
560+
"subcategory": "cache",
561+
"notes": [],
562+
"bodyParameters": [],
563+
"descriptionHTML": "<p>Gets GitHub Actions cache usage for a repository.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the <code>repo</code> scope. GitHub Apps must have the <code>actions:read</code> permission to use this endpoint.</p>",
564+
"responses": [
565+
{
566+
"httpStatusCode": "200",
567+
"httpStatusMessage": "OK",
568+
"description": "<p>Response</p>",
569+
"payload": "{\n \"full_name\": \"octo-org/Hello-World\",\n \"active_caches_size_in_bytes\": 2322142,\n \"active_caches_count\": 3\n}"
570+
}
571+
]
572+
}
573+
],
362574
"permissions": [
363575
{
364576
"verb": "get",

0 commit comments

Comments
 (0)