feat: add new GET /repos/{owner}/{repo}/codespaces/new operation (a…

…nd update some other operation descriptions, parameter descriptions and response examples) (#206)
octokit · Jul 15, 2022 · 8da5974 · 8da5974
1 parent 91e1aaa
commit 8da5974
Show file tree

Hide file tree

Showing 16 changed files with 276 additions and 72 deletions.
diff --git a/cache/api.github.com.json b/cache/api.github.com.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.6.3",
+ "version": "6.7.0",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },
@@ -3414,7 +3414,7 @@
  "/enterprises/{enterprise}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an enterprise",
- "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of active_users for each repository.",
+ "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of active_users for each repository.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-ghe",
  "externalDocs": {
@@ -8057,7 +8057,7 @@
  "/orgs/{org}/code-scanning/alerts": {
  "get": {
  "summary": "List code scanning alerts for an organization",
- "description": "Lists all code scanning alerts for the default branch (usually `main`\nor `master`) for all eligible repositories in an organization.\nTo use this endpoint, you must be an administrator or security manager for the organization, and you must use an access token with the `repo` scope or `security_events` scope.\n\nGitHub Apps must have the `security_events` read permission to use this endpoint.",
+ "description": "Lists code scanning alerts for the default branch for all eligible repositories in an organization. Eligible repositories are repositories that are owned by organizations that you own or for which you are a security manager. For more information, see \"[Managing security managers in your organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization).\"\n\nTo use this endpoint, you must be an owner or security manager for the organization, and you must use an access token with the `repo` scope or `security_events` scope.\n\nGitHub Apps must have the `security_events` read permission to use this endpoint.",
  "tags": ["code-scanning"],
  "operationId": "code-scanning/list-alerts-for-org",
  "externalDocs": {
@@ -8075,7 +8075,7 @@
  { "$ref": "#/components/parameters/direction" },
  {
  "name": "state",
- "description": "Set to `open`, `closed`, `fixed`, or `dismissed` to list code scanning alerts in a specific state.",
+ "description": "If specified, only code scanning alerts with this state will be returned.",
  "in": "query",
  "required": false,
  "schema": {
@@ -11618,7 +11618,7 @@
  "/orgs/{org}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an organization",
- "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of advanced_security_committers for each repository.\nIf this organization defers to an enterprise for billing, the total_advanced_security_committers returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.",
+ "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of advanced_security_committers for each repository.\n\nIf this organization defers to an enterprise for billing, the `total_advanced_security_committers` returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-org",
  "externalDocs": {
@@ -21947,6 +21947,77 @@
  "x-octokit": {}
  }
  },
+ "/repos/{owner}/{repo}/codespaces/new": {
+ "get": {
+ "summary": "Get default attributes for a codespace",
+ "description": "Gets the default attributes for codespaces created by the user with the repository.\n\nYou must authenticate using an access token with the `codespace` scope to use this endpoint.\n\nGitHub Apps must have write access to the `codespaces` repository permission to use this endpoint.",
+ "tags": ["codespaces"],
+ "operationId": "codespaces/pre-flight-with-repo-for-authenticated-user",
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/codespaces#preview-attributes-for-a-new-codespace"
+ },
+ "parameters": [
+ { "$ref": "#/components/parameters/owner" },
+ { "$ref": "#/components/parameters/repo" },
+ {
+ "name": "ref",
+ "description": "The branch or commit to check for a default devcontainer path. If not specified, the default branch will be checked.",
+ "in": "query",
+ "schema": { "type": "string", "example": "main" }
+ },
+ {
+ "name": "client_ip",
+ "description": "An alternative IP for default location auto-detection, such as when proxying a request.",
+ "in": "query",
+ "schema": { "type": "string", "example": "1.2.3.4" }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Response when a user is able to create codespaces from the repository.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "billable_owner": {
+ "$ref": "#/components/schemas/simple-user"
+ },
+ "defaults": {
+ "type": "object",
+ "required": ["location", "devcontainer_path"],
+ "properties": {
+ "location": { "type": "string" },
+ "devcontainer_path": {
+ "type": "string",
+ "nullable": true
+ }
+ }
+ }
+ }
+ },
+ "examples": {
+ "default": {
+ "$ref": "#/components/examples/codespaces-list-devcontainers-for-repository"
+ }
+ }
+ }
+ }
+ },
+ "401": { "$ref": "#/components/responses/requires_authentication" },
+ "403": { "$ref": "#/components/responses/forbidden" },
+ "404": { "$ref": "#/components/responses/not_found" }
+ },
+ "x-github": {
+ "githubCloudOnly": false,
+ "enabledForGitHubApps": true,
+ "category": "codespaces",
+ "subcategory": null
+ },
+ "x-octokit": {}
+ }
+ },
  "/repos/{owner}/{repo}/codespaces/secrets": {
  "get": {
  "summary": "List repository secrets",
@@ -23964,11 +24035,8 @@
  "description": "Response when creating a secret",
  "content": {
  "application/json": {
- "schema": {
- "type": "object",
- "properties": {},
- "additionalProperties": false
- }
+ "schema": { "$ref": "#/components/schemas/empty-object" },
+ "examples": { "default": { "value": null } }
  }
  }
  },

diff --git a/cache/ghes-3.2.json b/cache/ghes-3.2.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.6.3",
+ "version": "6.7.0",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },

diff --git a/cache/ghes-3.3.json b/cache/ghes-3.3.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.6.3",
+ "version": "6.7.0",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },

diff --git a/cache/ghes-3.4.json b/cache/ghes-3.4.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.6.3",
+ "version": "6.7.0",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },
@@ -5304,7 +5304,7 @@
  "/enterprises/{enterprise}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an enterprise",
- "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of active_users for each repository.",
+ "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of active_users for each repository.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-ghe",
  "externalDocs": {
@@ -11708,7 +11708,7 @@
  "/orgs/{org}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an organization",
- "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of advanced_security_committers for each repository.\nIf this organization defers to an enterprise for billing, the total_advanced_security_committers returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.",
+ "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of advanced_security_committers for each repository.\n\nIf this organization defers to an enterprise for billing, the `total_advanced_security_committers` returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-org",
  "externalDocs": {
@@ -22281,11 +22281,8 @@
  "description": "Response when creating a secret",
  "content": {
  "application/json": {
- "schema": {
- "type": "object",
- "properties": {},
- "additionalProperties": false
- }
+ "schema": { "$ref": "#/components/schemas/empty-object" },
+ "examples": { "default": { "value": null } }
  }
  }
  },

diff --git a/cache/ghes-3.5.json b/cache/ghes-3.5.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
- "version": "6.6.3",
+ "version": "6.7.0",
  "title": "GitHub's official OpenAPI spec + Octokit extension",
  "description": "OpenAPI specs from https://github.com/github/rest-api-description with the 'x-octokit' extension required by the Octokit SDKs",
  "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" },
@@ -5442,7 +5442,7 @@
  "/enterprises/{enterprise}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an enterprise",
- "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of active_users for each repository.",
+ "description": "Gets the GitHub Advanced Security active committers for an enterprise per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of active_users for each repository.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-ghe",
  "externalDocs": {
@@ -9518,7 +9518,7 @@
  "/orgs/{org}/code-scanning/alerts": {
  "get": {
  "summary": "List code scanning alerts for an organization",
- "description": "Lists all code scanning alerts for the default branch (usually `main`\nor `master`) for all eligible repositories in an organization.\nTo use this endpoint, you must be an administrator or security manager for the organization, and you must use an access token with the `repo` scope or `security_events` scope.\n\nGitHub Apps must have the `security_events` read permission to use this endpoint.",
+ "description": "Lists code scanning alerts for the default branch for all eligible repositories in an organization. Eligible repositories are repositories that are owned by organizations that you own or for which you are a security manager. For more information, see \"[Managing security managers in your organization](https://docs.github.com/enterprise-server@3.5/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization).\"\n\nTo use this endpoint, you must be an owner or security manager for the organization, and you must use an access token with the `repo` scope or `security_events` scope.\n\nGitHub Apps must have the `security_events` read permission to use this endpoint.",
  "tags": ["code-scanning"],
  "operationId": "code-scanning/list-alerts-for-org",
  "externalDocs": {
@@ -9536,7 +9536,7 @@
  { "$ref": "#/components/parameters/direction" },
  {
  "name": "state",
- "description": "Set to `open`, `closed`, `fixed`, or `dismissed` to list code scanning alerts in a specific state.",
+ "description": "If specified, only code scanning alerts with this state will be returned.",
  "in": "query",
  "required": false,
  "schema": {
@@ -12115,7 +12115,7 @@
  "/orgs/{org}/settings/billing/advanced-security": {
  "get": {
  "summary": "Get GitHub Advanced Security active committers for an organization",
- "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of advanced_security_committers for each repository.\nIf this organization defers to an enterprise for billing, the total_advanced_security_committers returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.",
+ "description": "Gets the GitHub Advanced Security active committers for an organization per repository.\n\nEach distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of advanced_security_committers for each repository.\n\nIf this organization defers to an enterprise for billing, the `total_advanced_security_committers` returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.\n\nThe total number of repositories with committer information is tracked by the `total_count` field.",
  "tags": ["billing"],
  "operationId": "billing/get-github-advanced-security-billing-org",
  "externalDocs": {
@@ -23118,11 +23118,8 @@
  "description": "Response when creating a secret",
  "content": {
  "application/json": {
- "schema": {
- "type": "object",
- "properties": {},
- "additionalProperties": false
- }
+ "schema": { "$ref": "#/components/schemas/empty-object" },
+ "examples": { "default": { "value": null } }
  }
  }
  },
@@ -40819,6 +40816,20 @@
  "responses": { "501": { "description": "Not Implemented" } }
  }
  },
+ "/repos/{owner}/{repo}/codespaces/new": {
+ "get": {
+ "summary": "Get default attributes for a codespace",
+ "description": "This endpoint does not exist in GitHub Enterprise Server 3.5. It was added in api.github.com",
+ "tags": ["codespaces"],
+ "operationId": "codespaces/pre-flight-with-repo-for-authenticated-user",
+ "externalDocs": {
+ "description": "API method documentation",
+ "url": "https://docs.github.com/rest/reference/codespaces#preview-attributes-for-a-new-codespace"
+ },
+ "x-octokit": { "api.github.com": "removed" },
+ "responses": { "501": { "description": "Not Implemented" } }
+ }
+ },
  "/repos/{owner}/{repo}/codespaces/secrets": {
  "get": {
  "summary": "List repository secrets",