+```geojson
+{
+ "type": "Polygon",
+ "coordinates": [
+ [
+ [-90,30],
+ [-90,35],
+ [-90,35],
+ [-85,35],
+ [-85,30]
+ ]
+ ]
+}
+```
+
+
+
+
+### Using topoJSON
+
+For example, you can create a simple topoJSON map:
+
+
+```topojson
+{
+ "type": "Topology",
+ "transform": {
+ "scale": [0.0005000500050005, 0.00010001000100010001],
+ "translate": [100, 0]
+ },
+ "objects": {
+ "example": {
+ "type": "GeometryCollection",
+ "geometries": [
+ {
+ "type": "Point",
+ "properties": {"prop0": "value0"},
+ "coordinates": [4000, 5000]
+ },
+ {
+ "type": "LineString",
+ "properties": {"prop0": "value0", "prop1": 0},
+ "arcs": [0]
+ },
+ {
+ "type": "Polygon",
+ "properties": {"prop0": "value0",
+ "prop1": {"this": "that"}
+ },
+ "arcs": [[1]]
+ }
+ ]
+ }
+ },
+ "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
+}
+```
+
+
+
+
+For more information on working with `.geojson` and `.topojson` files, see "[Working with non-code files](/repositories/working-with-files/using-files/working-with-non-code-files#mapping-geojson-files-on-github)."
+
+
+## Creating STL 3D models
+
+You can use ASCII STL syntax directly in markdown to create interactive 3D models. To display a model, add ASCII STL syntax inside a fenced code block with the `stl` syntax identifier. For more information, see "[Creating and highlighting code blocks](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)."
+
+For example, you can create a simple 3D model:
+
++```stl +solid cube_corner + facet normal 0.0 -1.0 0.0 + outer loop + vertex 0.0 0.0 0.0 + vertex 1.0 0.0 0.0 + vertex 0.0 0.0 1.0 + endloop + endfacet + facet normal 0.0 0.0 -1.0 + outer loop + vertex 0.0 0.0 0.0 + vertex 0.0 1.0 0.0 + vertex 1.0 0.0 0.0 + endloop + endfacet + facet normal -1.0 0.0 0.0 + outer loop + vertex 0.0 0.0 0.0 + vertex 0.0 0.0 1.0 + vertex 0.0 1.0 0.0 + endloop + endfacet + facet normal 0.577 0.577 0.577 + outer loop + vertex 1.0 0.0 0.0 + vertex 0.0 1.0 0.0 + vertex 0.0 0.0 1.0 + endloop + endfacet +endsolid +``` ++ + + +For more information on working with `.stl` files, see "[Working with non-code files](/repositories/working-with-files/using-files/working-with-non-code-files#3d-file-viewer)." + diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md index 535f165c2533..67055d249caf 100644 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md +++ b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md @@ -123,7 +123,7 @@ You can enable or disable features for all repositories. By default, {% data variables.product.prodname_dependabot %} can't update dependencies that are located in private repositories or private package registries. However, if a dependency is in a private {% data variables.product.prodname_dotcom %} repository within the same organization as the project that uses that dependency, you can allow {% data variables.product.prodname_dependabot %} to update the version successfully by giving it access to the host repository. -If your code depends on packages in a private registry, you can allow {% data variables.product.prodname_dependabot %} to update the versions of these dependencies by configuring this at the repository level. You do this by adding authentication details to the _dependabot.yml_ file for the repository. For more information, see "[Configuration options for dependency updates](/github/administering-a-repository/configuration-options-for-dependency-updates#configuration-options-for-private-registries)." +If your code depends on packages in a private registry, you can allow {% data variables.product.prodname_dependabot %} to update the versions of these dependencies by configuring this at the repository level. You do this by adding authentication details to the _dependabot.yml_ file for the repository. For more information, see "[Configuration options for the dependabot.yml file](/github/administering-a-repository/configuration-options-for-dependency-updates#configuration-options-for-private-registries)." To allow {% data variables.product.prodname_dependabot %} to access a private {% data variables.product.prodname_dotcom %} repository: @@ -163,6 +163,5 @@ You can manage access to {% data variables.product.prodname_GH_advanced_security - "[Securing your repository](/code-security/getting-started/securing-your-repository)"{% ifversion not fpt %} - "[About secret scanning](/github/administering-a-repository/about-secret-scanning)"{% endif %}{% ifversion not ghae %} -- "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)" -- "[Managing vulnerabilities in your project's dependencies](/github/managing-security-vulnerabilities/managing-vulnerabilities-in-your-projects-dependencies)"{% endif %}{% ifversion fpt or ghec or ghes > 3.2 %} -- "[Keeping your dependencies updated automatically](/github/administering-a-repository/keeping-your-dependencies-updated-automatically)"{% endif %} +- "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)"{% endif %}{% ifversion fpt or ghec or ghes > 3.2 %} +- "[Keeping your dependencies updated automatically](/github/administering-a-repository/keeping-your-dependencies-updated-automatically)"{% endif %} \ No newline at end of file diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md index a79bd3321e0a..f6d67a50f8f8 100644 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md +++ b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md @@ -42,7 +42,7 @@ To search for specific events, use the `action` qualifier in your query. Actions | [`billing`](#billing-category-actions) | Contains all activities related to your organization's billing. | [`business`](#business-category-actions) | Contains activities related to business settings for an enterprise. | | [`codespaces`](#codespaces-category-actions) | Contains all activities related to your organization's codespaces. |{% endif %}{% ifversion fpt or ghec or ghes > 3.2 %} -| [`dependabot_alerts`](#dependabot_alerts-category-actions) | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_alerts %} in existing repositories. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." +| [`dependabot_alerts`](#dependabot_alerts-category-actions) | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_alerts %} in existing repositories. For more information, see "[About {% data variables.product.prodname_dependabot_alerts %}](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." | [`dependabot_alerts_new_repos`](#dependabot_alerts_new_repos-category-actions) | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_alerts %} in new repositories created in the organization. | [`dependabot_security_updates`](#dependabot_security_updates-category-actions) | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_security_updates %} in existing repositories. For more information, see "[Configuring {% data variables.product.prodname_dependabot_security_updates %}](/github/managing-security-vulnerabilities/configuring-dependabot-security-updates)." | [`dependabot_security_updates_new_repos`](#dependabot_security_updates_new_repos-category-actions) | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_security_updates %} for new repositories created in the organization.{% endif %}{% ifversion fpt or ghec %} @@ -680,7 +680,7 @@ For more information, see "[Managing the publication of {% data variables.produc | Action | Description |------------------|------------------- -| `create` | Triggered when {% data variables.product.product_name %} creates a {% data variables.product.prodname_dependabot %} alert for a repository that uses a vulnerable dependency. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." +| `create` | Triggered when {% data variables.product.product_name %} creates a {% data variables.product.prodname_dependabot %} alert for a repository that uses a vulnerable dependency. For more information, see "[About {% data variables.product.prodname_dependabot_alerts %}](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." | `dismiss` | Triggered when an organization owner or person with admin access to the repository dismisses a {% data variables.product.prodname_dependabot %} alert about a vulnerable dependency. | `resolve` | Triggered when someone with write access to a repository pushes changes to update and resolve a vulnerability in a project dependency. diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md b/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md index 29e586ab412a..890f1e122aa8 100644 --- a/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md +++ b/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md @@ -75,5 +75,5 @@ Almost all software relies on code developed and maintained by other developers, The dependency graph provides a great way to visualize and explore the dependencies for a repository. For more information, see "[About the dependency graph](/code-security/supply-chain-security/about-the-dependency-graph)" and "[Exploring the dependencies of a repository](/code-security/supply-chain-security/exploring-the-dependencies-of-a-repository)." -You can also set up your repository so that {% data variables.product.company_short %} alerts you automatically whenever a security vulnerability is found in one of your dependencies. For more information, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." +You can also set up your repository so that {% data variables.product.company_short %} alerts you automatically whenever a security vulnerability is found in one of your dependencies. For more information, see "[About {% data variables.product.prodname_dependabot_alerts %}](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." {% endif %} diff --git a/content/repositories/working-with-files/using-files/working-with-non-code-files.md b/content/repositories/working-with-files/using-files/working-with-non-code-files.md index 2623fdbd3608..9924bdee5a7a 100644 --- a/content/repositories/working-with-files/using-files/working-with-non-code-files.md +++ b/content/repositories/working-with-files/using-files/working-with-non-code-files.md @@ -130,6 +130,12 @@ By default, the embedded renderer is 420 pixels wide by 620 pixels high, but you {% endtip %} +{% if mermaid %} +### Rendering in Markdown + +You can embed ASCII STL syntax directly in Markdown. For more information, see "[Creating diagrams](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-stl-3d-models)." +{% endif %} + ## Rendering CSV and TSV data GitHub supports rendering tabular data in the form of *.csv* (comma-separated) and .*tsv* (tab-separated) files. @@ -240,7 +246,7 @@ When you click the paper icon on the right, you'll also see the changes made to  -### Geometry Types +### Geometry types Maps on {% data variables.product.product_name %} use [Leaflet.js](http://leafletjs.com) and support all the geometry types outlined in [the geoJSON spec](http://www.geojson.org/geojson-spec.html) (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection). TopoJSON files should be type "Topology" and adhere to the [topoJSON spec](https://github.com/mbostock/topojson/wiki/Specification). @@ -281,6 +287,12 @@ By default, the embedded map 420px x 620px, but you can customize the output by {% endtip %} +{% if mermaid %} +### Mapping in Markdown + +You can embed geoJSON and topoJSON directly in Markdown. For more information, see "[Creating diagrams](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-geojson-and-topojson-maps)." +{% endif %} + ### Clustering If your map contains a large number of markers (roughly over 750), GitHub will automatically cluster nearby markers at higher zoom levels. Simply click the cluster or zoom in to see individual markers. @@ -299,7 +311,7 @@ Additionally, if your `.geojson` file is especially large (over 10 MB), it is no It may still be possible to render the data by converting the `.geojson` file to [TopoJSON](https://github.com/mbostock/topojson), a compression format that, in some cases, can reduce filesize by up to 80%. Of course, you can always break the file into smaller chunks (such as by state or by year), and store the data as multiple files within the repository. -### Additional Resources +### Further reading * [Leaflet.js geojson documentation](http://leafletjs.com/examples/geojson.html) * [MapBox marker-styling documentation](http://www.mapbox.com/developers/simplestyle/) @@ -327,3 +339,45 @@ $ jupyter nbconvert --to html NOTEBOOK-NAME.ipynb - [Jupyter Notebook's GitHub repository](https://github.com/jupyter/jupyter_notebook) - [Gallery of Jupyter Notebooks](https://github.com/jupyter/jupyter/wiki/A-gallery-of-interesting-Jupyter-Notebooks) + +{% if mermaid %} +## Displaying mermaid files on {% data variables.product.prodname_dotcom %} + +{% data variables.product.product_name %} supports rendering Mermaid files within repositories. Commit the file as you would normally using a `.mermaid` or `.mmd` extension. Then, navigate to the path of the Mermaid file on {% data variables.product.prodname_dotcom %}. + +For example, if you add a `.mmd` file with the following content to your repository: + +``` +graph TD + A[Friend's Birthday] -->|Get money| B(Go shopping) + B --> C{Let me think} + C -->|One| D["Cool
The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -37575,14 +37530,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -37590,132 +37545,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -37723,29 +37588,19 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "create-a-deployment", - "category": "deployments", + "slug": "create-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], - "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "422", @@ -37756,115 +37611,42 @@ "bodyParameters": [ { "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", + "description": "A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", + "rawDescription": "The contents of the key.", "childParamsGroups": [] }, { "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", + "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] - }, + } + ] + }, + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", + "parameters": [ { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", - "in": "body", - "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "get-a-deployment", - "category": "deployments", + "slug": "get-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "descriptionHTML": "", "bodyParameters": [], @@ -37915,19 +37698,18 @@ "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -37948,61 +37730,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "environments": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -38021,42 +37795,107 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Results per page (max 100)
" + }, + { + "name": "page", + "description": "Page number of the results to fetch.", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "descriptionHTML": "Page number of the results to fetch.
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Get all environments", + "summary": "List deployments", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "get-all-environments", + "slug": "list-deployments", "category": "deployments", - "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", + "verb": "post", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -38075,418 +37914,364 @@ "type": "string" }, "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Get an environment", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "environments" - }, - "slug": "get-an-environment", - "category": "deployments", - "subcategory": "environments", - "notes": [], - "bodyParameters": [], - "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" - } - ] - }, - { - "verb": "put", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" - } - ], - "summary": "Create or update an environment", + "summary": "Create a deployment", "requestBody": { - "required": false, + "required": true, "content": { "application/json": { "schema": { "type": "object", - "nullable": true, "properties": { - "wait_timer": { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", "childParamsGroups": [] }, - "reviewers": { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } + "type": "string" }, - "name": "reviewers", + "name": "required_contexts", "in": "body", "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] + "rawDescription": "The [status](https://docs.github.com/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] }, - "deployment_branch_policy": { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + "transient_environment": { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "bodyParameters": [ + { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "create-or-update-an-environment", + "slug": "get-a-deployment", "category": "deployments", - "subcategory": "environments", "notes": [], - "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "", + "bodyParameters": [], "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
Resource not found
" } ], - "bodyParameters": [ - { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", - "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", - "childParamsGroups": [] - }, - { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } - }, - "name": "reviewers", - "in": "body", - "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] - }, - { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Delete a deployment", + "x-github": { + "enabledForGitHubApps": true, + "category": "repos", + "subcategory": "deployments" + }, + "slug": "delete-a-deployment", + "category": "deployments", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "responses": [ + { + "httpStatusCode": "204", + "httpStatusMessage": "No Content", + "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "subcategory": "deployments" + } + ], + "environments": [ + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/environments", + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "" + }, + { + "name": "repo", "in": "path", "required": true, - "description": "The name of the environment", "schema": { "type": "string" }, - "descriptionHTML": "The name of the environment
" + "descriptionHTML": "" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Delete an environment", + "summary": "Get all environments", "x-github": { "enabledForGitHubApps": true, "category": "repos", "subcategory": "environments" }, - "slug": "delete-an-environment", + "slug": "get-all-environments", "category": "deployments", "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Default response
" + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Response
", + "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" } ] - } - ], - "keys": [ + }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -38572,60 +38421,50 @@ "descriptionHTML": "" }, { - "name": "per_page", - "description": "Results per page (max 100)", - "in": "query", - "schema": { - "type": "integer", - "default": 30 - }, - "descriptionHTML": "Results per page (max 100)
" - }, - { - "name": "page", - "description": "Page number of the results to fetch.", - "in": "query", + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", "schema": { - "type": "integer", - "default": 1 + "type": "string" }, - "descriptionHTML": "Page number of the results to fetch.
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "List deploy keys", + "summary": "Get an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "list-deploy-keys", + "slug": "get-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], - "descriptionHTML": "", "bodyParameters": [], + "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" } ] }, { - "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "verb": "put", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -38644,62 +38483,180 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", + "schema": { + "type": "string" + }, + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" } ], - "summary": "Create a deploy key", + "summary": "Create or update an environment", "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", + "nullable": true, "properties": { - "title": { - "type": "string", - "description": "A name for the key.
", - "name": "title", + "wait_timer": { + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] }, - "key": { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "reviewers": { + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } + }, + "name": "reviewers", "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, - "read_only": { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "deployment_branch_policy": { + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
You can create a read-only deploy key.
", + "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { - "httpStatusCode": "201", - "httpStatusMessage": "Created", + "httpStatusCode": "200", + "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" }, { "httpStatusCode": "422", "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" + "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
A name for the key.
", - "name": "title", - "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", - "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] - } - ] - }, - { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" }, { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } }, - "descriptionHTML": "" + "name": "reviewers", + "in": "body", + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, { - "name": "key_id", - "description": "key_id parameter", - "in": "path", - "required": true, - "schema": { - "type": "integer" + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys/42" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" - } - ], - "summary": "Get a deploy key", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "keys" - }, - "slug": "get-a-deploy-key", - "category": "deployments", - "subcategory": "keys", - "notes": [], - "descriptionHTML": "", - "bodyParameters": [], - "responses": [ - { - "httpStatusCode": "200", - "httpStatusMessage": "OK", - "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" + "nullable": true, + "required": [ + "protected_branches", + "custom_branch_policies" + ], + "name": "deployment_branch_policy", + "in": "body", + "rawType": "object", + "rawDescription": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to `null`.", + "childParamsGroups": [ + { + "parentName": "deployment_branch_policy", + "parentType": "object", + "id": "deployment_branch_policy-object", + "params": [ + { + "type": "boolean", + "description": "Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://api.github.com/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", - "description": "Response
" + "description": "Default response
" } ] } diff --git a/lib/rest/static/decorated/ghes-3.1.json b/lib/rest/static/decorated/ghes-3.1.json index ca25f92fcd79..13802afa6438 100644 --- a/lib/rest/static/decorated/ghes-3.1.json +++ b/lib/rest/static/decorated/ghes-3.1.json @@ -29302,11 +29302,11 @@ } ] }, - "deployments": { - "deployments": [ + "deploy_keys": { + "deploy_keys": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -29326,51 +29326,6 @@ }, "descriptionHTML": "" }, - { - "name": "sha", - "description": "The SHA recorded at creation time.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonSimple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -29455,14 +29404,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -29470,132 +29419,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.1/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise. \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.1/rest/overview/api-previews#enhanced-deployments) custom media type.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -29603,148 +29462,59 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments", - "previews": [ - { - "name": "ant-man", - "html": "The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonDeployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" - } - ], - "bodyParameters": [ - { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.1/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", - "childParamsGroups": [] + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "bodyParameters": [ { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Name for the target deployment environment (e.g., `production`, `staging`, `qa`).", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { - "type": "string or null", - "description": "Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "type": "string", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise. \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.1/rest/overview/api-previews#enhanced-deployments) custom media type.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } - ], - "subcategory": "deployments" + ] }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -29765,44 +29535,35 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments", - "previews": [ - { - "name": "flash", - "html": "New features in the Deployments API on GitHub are currently available during a public beta. Please see the blog post for full details.
\nTo access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:
application/vnd.github.flash-preview+jsonThe inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonResponse
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -29844,61 +29604,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "keys": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -29918,6 +29670,51 @@ }, "descriptionHTML": "" }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonSimple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -29996,14 +29799,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Create a deploy key", + "summary": "Create a deployment", "requestBody": { "required": true, "content": { @@ -30011,42 +29814,132 @@ "schema": { "type": "object", "properties": { - "title": { + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.1/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + "payload": { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { "type": "string", - "description": "A name for the key.
", - "name": "title", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Required. The contents of the key.
", - "name": "key", + "description": { + "type": "string or null", + "description": "Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", "in": "body", "rawType": "string", - "rawDescription": "The contents of the key.", + "rawDescription": "Short description of the deployment.", "childParamsGroups": [] }, - "read_only": { + "transient_environment": { "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonYou can create a read-only deploy key.
", + "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "description": "Simple example", + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + }, + { + "httpStatusCode": "202", + "httpStatusMessage": "Accepted", + "description": "Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" }, { "httpStatusCode": "422", @@ -30077,36 +29986,109 @@ "bodyParameters": [ { "type": "string", - "description": "A name for the key.
", - "name": "title", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", "in": "body", "rawType": "string", - "rawDescription": "A name for the key.", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", "childParamsGroups": [] }, { "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", "in": "body", "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.1/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
key_id parameter
" + "descriptionHTML": "deployment_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" } ], - "summary": "Get a deploy key", + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "deployments", + "previews": [ + { + "name": "flash", + "html": "New features in the Deployments API on GitHub are currently available during a public beta. Please see the blog post for full details.
\nTo access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:
application/vnd.github.flash-preview+jsonThe inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonResponse
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ] + ], + "subcategory": "deployments" }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", + "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", "parameters": [ { "name": "owner", @@ -30196,45 +30188,55 @@ "descriptionHTML": "" }, { - "name": "key_id", - "description": "key_id parameter", + "name": "deployment_id", + "description": "deployment_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "key_id parameter
" + "descriptionHTML": "deployment_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "deployments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-a-deployment", "category": "deployments", - "subcategory": "keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" } - ] + ], + "subcategory": "deployments" } ], "statuses": [ diff --git a/lib/rest/static/decorated/ghes-3.2.json b/lib/rest/static/decorated/ghes-3.2.json index 72c8d41bf598..d1beb36532d9 100644 --- a/lib/rest/static/decorated/ghes-3.2.json +++ b/lib/rest/static/decorated/ghes-3.2.json @@ -30176,11 +30176,11 @@ } ] }, - "deployments": { - "deployments": [ + "deploy_keys": { + "deploy_keys": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -30200,51 +30200,6 @@ }, "descriptionHTML": "" }, - { - "name": "sha", - "description": "The SHA recorded at creation time.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonSimple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -30329,14 +30278,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -30344,132 +30293,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.2/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise. \n**Note:** This parameter requires you to use the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/enterprise-server@3.2/rest/overview/api-previews#enhanced-deployments) custom media type.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -30477,35 +30336,19 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments", - "previews": [ - { - "name": "ant-man", - "html": "The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonDeployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "422", @@ -30516,109 +30359,36 @@ "bodyParameters": [ { "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", + "description": "A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", + "rawDescription": "The contents of the key.", "childParamsGroups": [] }, { "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", + "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.2/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", - "in": "body", - "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments", - "previews": [ - { - "name": "flash", - "html": "New features in the Deployments API on GitHub are currently available during a public beta. Please see the blog post for full details.
\nTo access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:
application/vnd.github.flash-preview+jsonThe inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonResponse
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -30718,61 +30478,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "environments": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -30791,42 +30543,113 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Results per page (max 100)
" + }, + { + "name": "page", + "description": "Page number of the results to fetch.", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "descriptionHTML": "Page number of the results to fetch.
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Get all environments", + "summary": "List deployments", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments", + "previews": [ + { + "name": "ant-man", + "html": "The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonGet all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", + "verb": "post", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -30845,52 +30668,301 @@ "type": "string" }, "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Get an environment", - "x-github": { - "enabledForGitHubApps": true, + "summary": "Create a deployment", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.2/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + "payload": { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + "transient_environment": { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
The inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" + "httpStatusCode": "201", + "httpStatusMessage": "Created", + "description": "Simple example", + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + }, + { + "httpStatusCode": "202", + "httpStatusMessage": "Accepted", + "description": "Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" } - ] + ], + "bodyParameters": [ + { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.2/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
\nNote: This parameter requires you to use the application/vnd.github.ant-man-preview+json custom media type.
The name of the environment
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" - } - ], - "summary": "Create or update an environment", - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "type": "object", - "nullable": true, - "properties": { - "wait_timer": { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", - "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", - "childParamsGroups": [] - }, - "reviewers": { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } - }, - "name": "reviewers", - "in": "body", - "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] - }, - "deployment_branch_policy": { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
deployment_id parameter
" } - }, + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments", + "previews": [ + { + "name": "flash", + "html": "New features in the Deployments API on GitHub are currently available during a public beta. Please see the blog post for full details.
\nTo access the new environment parameter, the two new values for the state parameter (in_progress and queued), and use auto_inactive on production deployments during the public beta period, you must provide the following custom media type in the Accept header:
application/vnd.github.flash-preview+jsonThe inactive state and the log_url, environment_url, and auto_inactive parameters are currently available for developers to preview. Please see the blog post for full details.
To access the API during the preview period, you must provide a custom media type in the Accept header:
application/vnd.github.ant-man-preview+jsonCreate or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "", + "bodyParameters": [], "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
Resource not found
" } ], - "bodyParameters": [ - { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", - "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", - "childParamsGroups": [] - }, - { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } - }, - "name": "reviewers", - "in": "body", - "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] - }, - { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Delete a deployment", + "x-github": { + "enabledForGitHubApps": true, + "category": "repos", + "subcategory": "deployments" + }, + "slug": "delete-a-deployment", + "category": "deployments", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "responses": [ + { + "httpStatusCode": "204", + "httpStatusMessage": "No Content", + "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "subcategory": "deployments" + } + ], + "environments": [ + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/environments", + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "" + }, + { + "name": "repo", "in": "path", "required": true, - "description": "The name of the environment", "schema": { "type": "string" }, - "descriptionHTML": "The name of the environment
" + "descriptionHTML": "" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Delete an environment", + "summary": "Get all environments", "x-github": { "enabledForGitHubApps": true, "category": "repos", "subcategory": "environments" }, - "slug": "delete-an-environment", + "slug": "get-all-environments", "category": "deployments", "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Default response
" + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Response
", + "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" } ] - } - ], - "keys": [ + }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -31342,60 +31191,50 @@ "descriptionHTML": "" }, { - "name": "per_page", - "description": "Results per page (max 100)", - "in": "query", - "schema": { - "type": "integer", - "default": 30 - }, - "descriptionHTML": "Results per page (max 100)
" - }, - { - "name": "page", - "description": "Page number of the results to fetch.", - "in": "query", + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", "schema": { - "type": "integer", - "default": 1 + "type": "string" }, - "descriptionHTML": "Page number of the results to fetch.
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "List deploy keys", + "summary": "Get an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "list-deploy-keys", + "slug": "get-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], - "descriptionHTML": "", "bodyParameters": [], + "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" } ] }, { - "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "verb": "put", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -31414,62 +31253,180 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", + "schema": { + "type": "string" + }, + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" } ], - "summary": "Create a deploy key", + "summary": "Create or update an environment", "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", + "nullable": true, "properties": { - "title": { - "type": "string", - "description": "A name for the key.
", - "name": "title", + "wait_timer": { + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] }, - "key": { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "reviewers": { + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } + }, + "name": "reviewers", "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, - "read_only": { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "deployment_branch_policy": { + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
You can create a read-only deploy key.
", + "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { - "httpStatusCode": "201", - "httpStatusMessage": "Created", + "httpStatusCode": "200", + "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" }, { "httpStatusCode": "422", "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" + "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
A name for the key.
", - "name": "title", - "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", - "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] - } - ] - }, - { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" }, { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } }, - "descriptionHTML": "" + "name": "reviewers", + "in": "body", + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, { - "name": "key_id", - "description": "key_id parameter", - "in": "path", - "required": true, - "schema": { - "type": "integer" + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" - } - ], - "summary": "Get a deploy key", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "keys" - }, - "slug": "get-a-deploy-key", - "category": "deployments", - "subcategory": "keys", - "notes": [], - "descriptionHTML": "", - "bodyParameters": [], - "responses": [ - { - "httpStatusCode": "200", - "httpStatusMessage": "OK", - "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" + "nullable": true, + "required": [ + "protected_branches", + "custom_branch_policies" + ], + "name": "deployment_branch_policy", + "in": "body", + "rawType": "object", + "rawDescription": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to `null`.", + "childParamsGroups": [ + { + "parentName": "deployment_branch_policy", + "parentType": "object", + "id": "deployment_branch_policy-object", + "params": [ + { + "type": "boolean", + "description": "Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", - "description": "Response
" + "description": "Default response
" } ] } diff --git a/lib/rest/static/decorated/ghes-3.3.json b/lib/rest/static/decorated/ghes-3.3.json index 550f77563a56..cabcc4ad29d9 100644 --- a/lib/rest/static/decorated/ghes-3.3.json +++ b/lib/rest/static/decorated/ghes-3.3.json @@ -30277,11 +30277,11 @@ } ] }, - "deployments": { - "deployments": [ + "deploy_keys": { + "deploy_keys": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -30301,51 +30301,6 @@ }, "descriptionHTML": "" }, - { - "name": "sha", - "description": "The SHA recorded at creation time.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -30424,14 +30379,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -30439,132 +30394,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.3/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -30572,29 +30437,19 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "create-a-deployment", - "category": "deployments", + "slug": "create-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], - "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "422", @@ -30605,115 +30460,42 @@ "bodyParameters": [ { "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", + "description": "A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", + "rawDescription": "The contents of the key.", "childParamsGroups": [] }, { "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", + "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] - }, + } + ] + }, + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", + "parameters": [ { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.3/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", - "in": "body", - "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "get-a-deployment", - "category": "deployments", + "slug": "get-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "descriptionHTML": "", "bodyParameters": [], @@ -30764,19 +30547,18 @@ "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -30797,61 +30579,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "environments": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -30870,42 +30644,107 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Results per page (max 100)
" + }, + { + "name": "page", + "description": "Page number of the results to fetch.", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "descriptionHTML": "Page number of the results to fetch.
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Get all environments", + "summary": "List deployments", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "get-all-environments", + "slug": "list-deployments", "category": "deployments", - "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", + "verb": "post", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -30924,418 +30763,364 @@ "type": "string" }, "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Get an environment", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "environments" - }, - "slug": "get-an-environment", - "category": "deployments", - "subcategory": "environments", - "notes": [], - "bodyParameters": [], - "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" - } - ] - }, - { - "verb": "put", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" - } - ], - "summary": "Create or update an environment", + "summary": "Create a deployment", "requestBody": { - "required": false, + "required": true, "content": { "application/json": { "schema": { "type": "object", - "nullable": true, "properties": { - "wait_timer": { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", "childParamsGroups": [] }, - "reviewers": { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } + "type": "string" }, - "name": "reviewers", + "name": "required_contexts", "in": "body", "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.3/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] }, - "deployment_branch_policy": { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + "transient_environment": { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "bodyParameters": [ + { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.3/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "create-or-update-an-environment", + "slug": "get-a-deployment", "category": "deployments", - "subcategory": "environments", "notes": [], - "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "", + "bodyParameters": [], "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
Resource not found
" } ], - "bodyParameters": [ - { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", - "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", - "childParamsGroups": [] - }, - { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } - }, - "name": "reviewers", - "in": "body", - "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] - }, - { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Delete a deployment", + "x-github": { + "enabledForGitHubApps": true, + "category": "repos", + "subcategory": "deployments" + }, + "slug": "delete-a-deployment", + "category": "deployments", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "responses": [ + { + "httpStatusCode": "204", + "httpStatusMessage": "No Content", + "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "subcategory": "deployments" + } + ], + "environments": [ + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/environments", + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "" + }, + { + "name": "repo", "in": "path", "required": true, - "description": "The name of the environment", "schema": { "type": "string" }, - "descriptionHTML": "The name of the environment
" + "descriptionHTML": "" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Delete an environment", + "summary": "Get all environments", "x-github": { "enabledForGitHubApps": true, "category": "repos", "subcategory": "environments" }, - "slug": "delete-an-environment", + "slug": "get-all-environments", "category": "deployments", "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Default response
" + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Response
", + "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" } ] - } - ], - "keys": [ + }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -31421,60 +31270,50 @@ "descriptionHTML": "" }, { - "name": "per_page", - "description": "Results per page (max 100)", - "in": "query", - "schema": { - "type": "integer", - "default": 30 - }, - "descriptionHTML": "Results per page (max 100)
" - }, - { - "name": "page", - "description": "Page number of the results to fetch.", - "in": "query", + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", "schema": { - "type": "integer", - "default": 1 + "type": "string" }, - "descriptionHTML": "Page number of the results to fetch.
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "List deploy keys", + "summary": "Get an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "list-deploy-keys", + "slug": "get-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], - "descriptionHTML": "", "bodyParameters": [], + "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" } ] }, { - "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "verb": "put", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -31493,62 +31332,180 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", + "schema": { + "type": "string" + }, + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" } ], - "summary": "Create a deploy key", + "summary": "Create or update an environment", "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", + "nullable": true, "properties": { - "title": { - "type": "string", - "description": "A name for the key.
", - "name": "title", + "wait_timer": { + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] }, - "key": { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "reviewers": { + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } + }, + "name": "reviewers", "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, - "read_only": { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "deployment_branch_policy": { + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
You can create a read-only deploy key.
", + "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { - "httpStatusCode": "201", - "httpStatusMessage": "Created", + "httpStatusCode": "200", + "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" }, { "httpStatusCode": "422", "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" + "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
A name for the key.
", - "name": "title", - "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", - "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] - } - ] - }, - { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" }, { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } }, - "descriptionHTML": "" + "name": "reviewers", + "in": "body", + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, { - "name": "key_id", - "description": "key_id parameter", - "in": "path", - "required": true, - "schema": { - "type": "integer" + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" - } - ], - "summary": "Get a deploy key", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "keys" - }, - "slug": "get-a-deploy-key", - "category": "deployments", - "subcategory": "keys", - "notes": [], - "descriptionHTML": "", - "bodyParameters": [], - "responses": [ - { - "httpStatusCode": "200", - "httpStatusMessage": "OK", - "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" + "nullable": true, + "required": [ + "protected_branches", + "custom_branch_policies" + ], + "name": "deployment_branch_policy", + "in": "body", + "rawType": "object", + "rawDescription": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to `null`.", + "childParamsGroups": [ + { + "parentName": "deployment_branch_policy", + "parentType": "object", + "id": "deployment_branch_policy-object", + "params": [ + { + "type": "boolean", + "description": "Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", - "description": "Response
" + "description": "Default response
" } ] } diff --git a/lib/rest/static/decorated/ghes-3.4.json b/lib/rest/static/decorated/ghes-3.4.json index a4ddddd69bde..80959f32c393 100644 --- a/lib/rest/static/decorated/ghes-3.4.json +++ b/lib/rest/static/decorated/ghes-3.4.json @@ -32841,11 +32841,11 @@ } ] }, - "deployments": { - "deployments": [ + "deploy_keys": { + "deploy_keys": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -32865,51 +32865,6 @@ }, "descriptionHTML": "" }, - { - "name": "sha", - "description": "The SHA recorded at creation time.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -32988,14 +32943,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -33003,132 +32958,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.4/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -33136,29 +33001,19 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "create-a-deployment", - "category": "deployments", + "slug": "create-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], - "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "422", @@ -33169,115 +33024,42 @@ "bodyParameters": [ { "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", + "description": "A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", + "rawDescription": "The contents of the key.", "childParamsGroups": [] }, { "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", + "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] - }, + } + ] + }, + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", + "parameters": [ { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.4/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", - "in": "body", - "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "get-a-deployment", - "category": "deployments", + "slug": "get-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "descriptionHTML": "", "bodyParameters": [], @@ -33328,19 +33111,18 @@ "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -33361,61 +33143,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "environments": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -33434,42 +33208,107 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Results per page (max 100)
" + }, + { + "name": "page", + "description": "Page number of the results to fetch.", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "descriptionHTML": "Page number of the results to fetch.
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Get all environments", + "summary": "List deployments", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "get-all-environments", + "slug": "list-deployments", "category": "deployments", - "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", + "verb": "post", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -33488,418 +33327,364 @@ "type": "string" }, "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Get an environment", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "environments" - }, - "slug": "get-an-environment", - "category": "deployments", - "subcategory": "environments", - "notes": [], - "bodyParameters": [], - "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" - } - ] - }, - { - "verb": "put", - "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" - }, - { - "name": "environment_name", - "in": "path", - "required": true, - "description": "The name of the environment", - "schema": { - "type": "string" - }, - "descriptionHTML": "The name of the environment
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" - } - ], - "summary": "Create or update an environment", + "summary": "Create a deployment", "requestBody": { - "required": false, + "required": true, "content": { "application/json": { "schema": { "type": "object", - "nullable": true, "properties": { - "wait_timer": { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", "childParamsGroups": [] }, - "reviewers": { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } + "type": "string" }, - "name": "reviewers", + "name": "required_contexts", "in": "body", "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.4/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] }, - "deployment_branch_policy": { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + "transient_environment": { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub Enterprise Server we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "bodyParameters": [ + { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/enterprise-server@3.4/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "environments" + "subcategory": "deployments" }, - "slug": "create-or-update-an-environment", + "slug": "get-a-deployment", "category": "deployments", - "subcategory": "environments", "notes": [], - "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "", + "bodyParameters": [], "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
Resource not found
" } ], - "bodyParameters": [ - { - "type": "integer", - "example": 30, - "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", - "name": "wait_timer", - "in": "body", - "rawType": "integer", - "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", - "childParamsGroups": [] - }, - { - "type": "array of objects or null", - "nullable": true, - "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - } - }, - "name": "reviewers", - "in": "body", - "rawType": "array", - "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", - "childParamsGroups": [ - { - "parentName": "reviewers", - "parentType": "items", - "id": "reviewers-items", - "params": [ - { - "type": "string", - "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", - "example": 4532992, - "name": "id", - "in": "body", - "rawType": "integer", - "rawDescription": "The id of the user or team who can review the deployment", - "childParamsGroups": [] - } - ] - } - ] - }, - { - "type": "object or null", - "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
deployment_id parameter
" + } + ], + "x-codeSamples": [ + { + "lang": "Shell", + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + }, + { + "lang": "JavaScript", + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + } + ], + "summary": "Delete a deployment", + "x-github": { + "enabledForGitHubApps": true, + "category": "repos", + "subcategory": "deployments" + }, + "slug": "delete-a-deployment", + "category": "deployments", + "notes": [], + "bodyParameters": [], + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "responses": [ + { + "httpStatusCode": "204", + "httpStatusMessage": "No Content", + "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" + } + ], + "subcategory": "deployments" + } + ], + "environments": [ + { + "verb": "get", + "requestPath": "/repos/{owner}/{repo}/environments", + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "descriptionHTML": "" + }, + { + "name": "repo", "in": "path", "required": true, - "description": "The name of the environment", "schema": { "type": "string" }, - "descriptionHTML": "The name of the environment
" + "descriptionHTML": "" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments', {\n owner: 'octocat',\n repo: 'hello-world'\n})" } ], - "summary": "Delete an environment", + "summary": "Get all environments", "x-github": { "enabledForGitHubApps": true, "category": "repos", "subcategory": "environments" }, - "slug": "delete-an-environment", + "slug": "get-all-environments", "category": "deployments", "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", + "descriptionHTML": "Get all environments for a repository.
\nAnyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Default response
" + "httpStatusCode": "200", + "httpStatusMessage": "OK", + "description": "Response
", + "payload": "{\n \"total_count\": 1,\n \"environments\": [\n {\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n }\n ]\n}" } ] - } - ], - "keys": [ + }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -33985,60 +33834,50 @@ "descriptionHTML": "" }, { - "name": "per_page", - "description": "Results per page (max 100)", - "in": "query", - "schema": { - "type": "integer", - "default": 30 - }, - "descriptionHTML": "Results per page (max 100)
" - }, - { - "name": "page", - "description": "Page number of the results to fetch.", - "in": "query", + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", "schema": { - "type": "integer", - "default": 1 + "type": "string" }, - "descriptionHTML": "Page number of the results to fetch.
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world'\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "List deploy keys", + "summary": "Get an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "list-deploy-keys", + "slug": "get-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], - "descriptionHTML": "", "bodyParameters": [], + "descriptionHTML": "Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" } ] }, { - "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "verb": "put", + "requestPath": "/repos/{owner}/{repo}/environments/{environment_name}", "parameters": [ { "name": "owner", @@ -34057,62 +33896,180 @@ "type": "string" }, "descriptionHTML": "" + }, + { + "name": "environment_name", + "in": "path", + "required": true, + "description": "The name of the environment", + "schema": { + "type": "string" + }, + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X PUT \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME \\\n -d '{\"wait_timer\":42}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('PUT /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name',\n wait_timer: 42\n})" } ], - "summary": "Create a deploy key", + "summary": "Create or update an environment", "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", + "nullable": true, "properties": { - "title": { - "type": "string", - "description": "A name for the key.
", - "name": "title", + "wait_timer": { + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] }, - "key": { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "reviewers": { + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } + }, + "name": "reviewers", "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, - "read_only": { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "deployment_branch_policy": { + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
You can create a read-only deploy key.
", + "descriptionHTML": "Create or update an environment with protection rules, such as required reviewers. For more information about environment protection rules, see \"Environments.\"
\nNote: Although you can use this operation to specify that only branches that match specified name patterns can deploy to this environment, you must use the UI to set the name patterns. For more information, see \"Environments.\"
\nNote: To create or update secrets for an environment, see \"Secrets.\"
\nYou must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { - "httpStatusCode": "201", - "httpStatusMessage": "Created", + "httpStatusCode": "200", + "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"id\": 161088068,\n \"node_id\": \"MDExOkVudmlyb25tZW50MTYxMDg4MDY4\",\n \"name\": \"staging\",\n \"url\": \"https://api.github.com/repos/github/hello-world/environments/staging\",\n \"html_url\": \"https://github.com/github/hello-world/deployments/activity_log?environments_filter=staging\",\n \"created_at\": \"2020-11-23T22:00:40Z\",\n \"updated_at\": \"2020-11-23T22:00:40Z\",\n \"protection_rules\": [\n {\n \"id\": 3736,\n \"node_id\": \"MDQ6R2F0ZTM3MzY=\",\n \"type\": \"wait_timer\",\n \"wait_timer\": 30\n },\n {\n \"id\": 3755,\n \"node_id\": \"MDQ6R2F0ZTM3NTU=\",\n \"type\": \"required_reviewers\",\n \"reviewers\": [\n {\n \"type\": \"User\",\n \"reviewer\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n }\n },\n {\n \"type\": \"Team\",\n \"reviewer\": {\n \"id\": 1,\n \"node_id\": \"MDQ6VGVhbTE=\",\n \"url\": \"https://api.github.com/teams/1\",\n \"html_url\": \"https://github.com/orgs/github/teams/justice-league\",\n \"name\": \"Justice League\",\n \"slug\": \"justice-league\",\n \"description\": \"A great team.\",\n \"privacy\": \"closed\",\n \"permission\": \"admin\",\n \"members_url\": \"https://api.github.com/teams/1/members{/member}\",\n \"repositories_url\": \"https://api.github.com/teams/1/repos\",\n \"parent\": null\n }\n }\n ]\n },\n {\n \"id\": 3756,\n \"node_id\": \"MDQ6R2F0ZTM3NTY=\",\n \"type\": \"branch_policy\"\n }\n ],\n \"deployment_branch_policy\": {\n \"protected_branches\": false,\n \"custom_branch_policies\": true\n }\n}" }, { "httpStatusCode": "422", "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" + "description": "Validation error when the environment name is invalid or when protected_branches and custom_branch_policies in deployment_branch_policy are set to the same value
A name for the key.
", - "name": "title", - "in": "body", - "rawType": "string", - "rawDescription": "A name for the key.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", - "in": "body", - "rawType": "string", - "rawDescription": "The contents of the key.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "type": "integer", + "example": 30, + "description": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).
", + "name": "wait_timer", "in": "body", - "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawType": "integer", + "rawDescription": "The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).", "childParamsGroups": [] - } - ] - }, - { - "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", - "parameters": [ - { - "name": "owner", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "descriptionHTML": "" }, { - "name": "repo", - "in": "path", - "required": true, - "schema": { - "type": "string" + "type": "array of objects or null", + "nullable": true, + "description": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.
", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + } }, - "descriptionHTML": "" + "name": "reviewers", + "in": "body", + "rawType": "array", + "rawDescription": "The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.", + "childParamsGroups": [ + { + "parentName": "reviewers", + "parentType": "items", + "id": "reviewers-items", + "params": [ + { + "type": "string", + "description": "The type of reviewer. Must be one of: User or Team
The id of the user or team who can review the deployment
", + "example": 4532992, + "name": "id", + "in": "body", + "rawType": "integer", + "rawDescription": "The id of the user or team who can review the deployment", + "childParamsGroups": [] + } + ] + } + ] }, { - "name": "key_id", - "description": "key_id parameter", - "in": "path", - "required": true, - "schema": { - "type": "integer" + "type": "object or null", + "description": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.
Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" - } - ], - "x-codeSamples": [ - { - "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" - }, - { - "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" - } - ], - "summary": "Get a deploy key", - "x-github": { - "enabledForGitHubApps": true, - "category": "repos", - "subcategory": "keys" - }, - "slug": "get-a-deploy-key", - "category": "deployments", - "subcategory": "keys", - "notes": [], - "descriptionHTML": "", - "bodyParameters": [], - "responses": [ - { - "httpStatusCode": "200", - "httpStatusMessage": "OK", - "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" + "nullable": true, + "required": [ + "protected_branches", + "custom_branch_policies" + ], + "name": "deployment_branch_policy", + "in": "body", + "rawType": "object", + "rawDescription": "The type of deployment branch policy for this environment. To allow all branches to deploy, set to `null`.", + "childParamsGroups": [ + { + "parentName": "deployment_branch_policy", + "parentType": "object", + "id": "deployment_branch_policy-object", + "params": [ + { + "type": "boolean", + "description": "Required. Whether only branches with branch protection rules can deploy to this environment. If protected_branches is true, custom_branch_policies must be false; if protected_branches is false, custom_branch_policies must be true.
Required. Whether only branches that match the specified name patterns can deploy to this environment. If custom_branch_policies is true, protected_branches must be false; if custom_branch_policies is false, protected_branches must be true.
key_id parameter
" + "descriptionHTML": "The name of the environment
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n http(s)://{hostname}/api/v3/repos/octocat/hello-world/environments/ENVIRONMENT_NAME" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/environments/{environment_name}', {\n owner: 'octocat',\n repo: 'hello-world',\n environment_name: 'environment_name'\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete an environment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "environments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-an-environment", "category": "deployments", - "subcategory": "keys", + "subcategory": "environments", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "You must authenticate using an access token with the repo scope to use this endpoint.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", - "description": "Response
" + "description": "Default response
" } ] } diff --git a/lib/rest/static/decorated/github.ae.json b/lib/rest/static/decorated/github.ae.json index e57069b546e6..f8cb4c449ea5 100644 --- a/lib/rest/static/decorated/github.ae.json +++ b/lib/rest/static/decorated/github.ae.json @@ -26912,11 +26912,11 @@ } ] }, - "deployments": { - "deployments": [ + "deploy_keys": { + "deploy_keys": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -26936,51 +26936,6 @@ }, "descriptionHTML": "" }, - { - "name": "sha", - "description": "The SHA recorded at creation time.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The SHA recorded at creation time.
" - }, - { - "name": "ref", - "description": "The name of the ref. This can be a branch, tag, or SHA.", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" - }, - { - "name": "task", - "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "none" - }, - "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" + "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" } - ], - "subcategory": "deployments" + ] }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/deployments", + "requestPath": "/repos/{owner}/{repo}/keys", "parameters": [ { "name": "owner", @@ -27059,14 +27014,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" } ], - "summary": "Create a deployment", + "summary": "Create a deploy key", "requestBody": { "required": true, "content": { @@ -27074,132 +27029,42 @@ "schema": { "type": "object", "properties": { - "ref": { - "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - "task": { + "title": { "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - "auto_merge": { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - "required_contexts": { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/github-ae@latest/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - "payload": { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, - "environment": { + "key": { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - "transient_environment": { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } }, "required": [ - "ref" + "key" ] }, - "examples": { - "simple-example": { - "summary": "Simple example", - "value": { - "ref": "topic-branch", - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot" - } - }, - "advanced-example": { - "summary": "Advanced example", - "value": { - "ref": "topic-branch", - "auto_merge": false, - "payload": "{ \"deploy\": \"migrate\" }", - "description": "Deploy request from hubot", - "required_contexts": [ - "ci/janky", - "security/brakeman" - ] - } - } + "example": { + "title": "octocat@octomac", + "key": "ssh-rsa AAA...", + "read_only": true } } } @@ -27207,29 +27072,19 @@ "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "create-a-deployment", - "category": "deployments", + "slug": "create-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], - "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub AE we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
You can create a read-only deploy key.
", "responses": [ { "httpStatusCode": "201", "httpStatusMessage": "Created", - "description": "Simple example", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" - }, - { - "httpStatusCode": "202", - "httpStatusMessage": "Accepted", - "description": "Merged branch response
", - "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" - }, - { - "httpStatusCode": "409", - "httpStatusMessage": "Conflict", - "description": "Conflict when there is a merge conflict or the commit's status checks failed
" + "description": "Response
", + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "422", @@ -27240,109 +27095,36 @@ "bodyParameters": [ { "type": "string", - "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", - "name": "ref", - "in": "body", - "rawType": "string", - "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", - "childParamsGroups": [] - }, - { - "type": "string", - "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
A name for the key.
", + "name": "title", "in": "body", "rawType": "string", - "rawDescription": "Specifies a task to execute (e.g., `deploy` or `deploy:migrations`).", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", - "default": true, - "name": "auto_merge", - "in": "body", - "rawType": "boolean", - "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", - "childParamsGroups": [] - }, - { - "type": "array of strings", - "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", - "items": { - "type": "string" - }, - "name": "required_contexts", - "in": "body", - "rawType": "array", - "rawDescription": "The [status](https://docs.github.com/github-ae@latest/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", - "childParamsGroups": [] - }, - { - "oneOf": [ - { - "type": "object", - "additionalProperties": true - }, - { - "type": "string", - "description": "JSON payload with extra information about the deployment.", - "default": "" - } - ], - "name": "payload", - "in": "body", - "type": "object or string or ", - "description": "JSON payload with extra information about the deployment.
", + "rawDescription": "A name for the key.", "childParamsGroups": [] }, { "type": "string", - "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", - "default": "", - "nullable": true, - "name": "description", + "description": "Required. The contents of the key.
", + "name": "key", "in": "body", "rawType": "string", - "rawDescription": "Short description of the deployment.", - "childParamsGroups": [] - }, - { - "type": "boolean", - "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", + "name": "read_only", "in": "body", "rawType": "boolean", - "rawDescription": "Specifies if the given environment is one that end-users directly interact with. Default: `true` when `environment` is `production` and `false` otherwise.", + "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", "childParamsGroups": [] } - ], - "subcategory": "deployments" + ] }, { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -27363,34 +27145,35 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Get a deployment", + "summary": "Get a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "get-a-deployment", - "category": "deployments", + "slug": "get-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "descriptionHTML": "", "bodyParameters": [], @@ -27399,19 +27182,18 @@ "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ], - "subcategory": "deployments" + ] }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", + "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", "parameters": [ { "name": "owner", @@ -27432,61 +27214,53 @@ "descriptionHTML": "" }, { - "name": "deployment_id", - "description": "deployment_id parameter", + "name": "key_id", + "description": "key_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "deployment_id parameter
" + "descriptionHTML": "key_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" } ], - "summary": "Delete a deployment", + "summary": "Delete a deploy key", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "deployments" + "subcategory": "keys" }, - "slug": "delete-a-deployment", - "category": "deployments", + "slug": "delete-a-deploy-key", + "category": "deploy_keys", + "subcategory": "deploy_keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", + "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" - }, - { - "httpStatusCode": "404", - "httpStatusMessage": "Not Found", - "description": "Resource not found
" - }, - { - "httpStatusCode": "422", - "httpStatusMessage": "Unprocessable Entity", - "description": "Validation failed
" } - ], - "subcategory": "deployments" + ] } - ], - "keys": [ + ] + }, + "deployments": { + "deployments": [ { "verb": "get", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -27506,6 +27280,51 @@ }, "descriptionHTML": "" }, + { + "name": "sha", + "description": "The SHA recorded at creation time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The SHA recorded at creation time.
" + }, + { + "name": "ref", + "description": "The name of the ref. This can be a branch, tag, or SHA.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the ref. This can be a branch, tag, or SHA.
" + }, + { + "name": "task", + "description": "The name of the task for the deployment (e.g., `deploy` or `deploy:migrations`).", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "none" + }, + "descriptionHTML": "The name of the task for the deployment (e.g., deploy or deploy:migrations).
The name of the environment that was deployed to (e.g., staging or production).
Simple filtering of deployments is available via query parameters:
", "responses": [ { "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "[\n {\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n }\n]" + "payload": "[\n {\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n }\n]" } - ] + ], + "subcategory": "deployments" }, { "verb": "post", - "requestPath": "/repos/{owner}/{repo}/keys", + "requestPath": "/repos/{owner}/{repo}/deployments", "parameters": [ { "name": "owner", @@ -27584,14 +27403,14 @@ "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys \\\n -d '{\"key\":\"key\"}'" + "source": "curl \\\n -X POST \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments \\\n -d '{\"ref\":\"ref\"}'" }, { "lang": "JavaScript", - "source": "await octokit.request('POST /repos/{owner}/{repo}/keys', {\n owner: 'octocat',\n repo: 'hello-world',\n key: 'key'\n})" + "source": "await octokit.request('POST /repos/{owner}/{repo}/deployments', {\n owner: 'octocat',\n repo: 'hello-world',\n ref: 'ref'\n})" } ], - "summary": "Create a deploy key", + "summary": "Create a deployment", "requestBody": { "required": true, "content": { @@ -27599,42 +27418,132 @@ "schema": { "type": "object", "properties": { - "title": { + "ref": { + "type": "string", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", + "in": "body", + "rawType": "string", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", + "childParamsGroups": [] + }, + "task": { + "type": "string", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", + "in": "body", + "rawType": "boolean", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + "required_contexts": { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/github-ae@latest/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + "payload": { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + "environment": { "type": "string", - "description": "A name for the key.
", - "name": "title", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Required. The contents of the key.
", - "name": "key", + "description": { + "type": "string or null", + "description": "Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", "in": "body", "rawType": "string", - "rawDescription": "The contents of the key.", + "rawDescription": "Short description of the deployment.", "childParamsGroups": [] }, - "read_only": { + "transient_environment": { "type": "boolean", - "description": "If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
You can create a read-only deploy key.
", + "descriptionHTML": "Deployments offer a few configurable parameters with certain defaults.
\nThe ref parameter can be any named branch, tag, or SHA. At GitHub AE we often deploy branches and verify them\nbefore we merge a pull request.
The environment parameter allows deployments to be issued to different runtime environments. Teams often have\nmultiple environments for verifying their applications, such as production, staging, and qa. This parameter\nmakes it easier to track which environments have requested deployments. The default environment is production.
The auto_merge parameter is used to ensure that the requested ref is not behind the repository's default branch. If\nthe ref is behind the default branch for the repository, we will attempt to merge it for you. If the merge succeeds,\nthe API will return a successful merge commit. If merge conflicts prevent the merge from succeeding, the API will\nreturn a failure response.
By default, commit statuses for every submitted context must be in a success\nstate. The required_contexts parameter allows you to specify a subset of contexts that must be success, or to\nspecify contexts that have not yet been submitted. You are not required to use commit statuses to deploy. If you do\nnot require any contexts or create any commit statuses, the deployment will always succeed.
The payload parameter is available for any extra information that a deployment system might need. It is a JSON text\nfield that will be passed on when a deployment event is dispatched.
The task parameter is used by the deployment system to allow different execution paths. In the web world this might\nbe deploy:migrations to run schema changes on the system. In the compiled world this could be a flag to compile an\napplication with debugging enabled.
Users with repo or repo_deployment scopes can create a deployment for a given ref.
You will see this response when GitHub automatically merges the base branch into the topic branch instead of creating\na deployment. This auto-merge happens when:
\nmaster in the response exampleIf there are no new commits in the base branch, a new request to create a deployment should give a successful\nresponse.
\nThis error happens when the auto_merge option is enabled and when the default branch (in this case master), can't\nbe merged into the branch that's being deployed (in this case topic-branch), due to merge conflicts.
This error happens when the required_contexts parameter indicates that one or more contexts need to have a success\nstatus for the commit to be deployed, but one or more of the required contexts do not have a state of success.
Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "description": "Simple example", + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" + }, + { + "httpStatusCode": "202", + "httpStatusMessage": "Accepted", + "description": "Merged branch response
", + "payload": "{\n \"message\": \"Auto-merged master into topic-branch on deployment.\"\n}" + }, + { + "httpStatusCode": "409", + "httpStatusMessage": "Conflict", + "description": "Conflict when there is a merge conflict or the commit's status checks failed
" }, { "httpStatusCode": "422", @@ -27665,36 +27584,109 @@ "bodyParameters": [ { "type": "string", - "description": "A name for the key.
", - "name": "title", + "description": "Required. The ref to deploy. This can be a branch, tag, or SHA.
", + "name": "ref", "in": "body", "rawType": "string", - "rawDescription": "A name for the key.", + "rawDescription": "The ref to deploy. This can be a branch, tag, or SHA.", "childParamsGroups": [] }, { "type": "string", - "description": "Required. The contents of the key.
", - "name": "key", + "description": "Specifies a task to execute (e.g., deploy or deploy:migrations).
If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"Repository permission levels for an organization\" and \"Permission levels for a user account repository.\"
", - "name": "read_only", + "description": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.
", + "default": true, + "name": "auto_merge", "in": "body", "rawType": "boolean", - "rawDescription": "If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. \n \nDeploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see \"[Repository permission levels for an organization](https://docs.github.com/articles/repository-permission-levels-for-an-organization/)\" and \"[Permission levels for a user account repository](https://docs.github.com/articles/permission-levels-for-a-user-account-repository/).\"", + "rawDescription": "Attempts to automatically merge the default branch into the requested ref, if it's behind the default branch.", + "childParamsGroups": [] + }, + { + "type": "array of strings", + "description": "The status contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.
", + "items": { + "type": "string" + }, + "name": "required_contexts", + "in": "body", + "rawType": "array", + "rawDescription": "The [status](https://docs.github.com/github-ae@latest/rest/reference/commits#commit-statuses) contexts to verify against commit status checks. If you omit this parameter, GitHub verifies all unique contexts before creating a deployment. To bypass checking entirely, pass an empty array. Defaults to all unique contexts.", + "childParamsGroups": [] + }, + { + "oneOf": [ + { + "type": "object", + "additionalProperties": true + }, + { + "type": "string", + "description": "JSON payload with extra information about the deployment.", + "default": "" + } + ], + "name": "payload", + "in": "body", + "type": "object or string or ", + "description": "JSON payload with extra information about the deployment.
", + "childParamsGroups": [] + }, + { + "type": "string", + "description": "Name for the target deployment environment (e.g., production, staging, qa).
Short description of the deployment.
", + "default": "", + "nullable": true, + "name": "description", + "in": "body", + "rawType": "string", + "rawDescription": "Short description of the deployment.", + "childParamsGroups": [] + }, + { + "type": "boolean", + "description": "Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false
Specifies if the given environment is one that end-users directly interact with. Default: true when environment is production and false otherwise.
key_id parameter
" + "descriptionHTML": "deployment_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" }, { "lang": "JavaScript", - "source": "await octokit.request('GET /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('GET /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" } ], - "summary": "Get a deploy key", + "summary": "Get a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "deployments" }, - "slug": "get-a-deploy-key", + "slug": "get-a-deployment", "category": "deployments", - "subcategory": "keys", "notes": [], "descriptionHTML": "", "bodyParameters": [], @@ -27752,18 +27743,19 @@ "httpStatusCode": "200", "httpStatusMessage": "OK", "description": "Response
", - "payload": "{\n \"id\": 1,\n \"key\": \"ssh-rsa AAA...\",\n \"url\": \"https://api.github.com/repos/octocat/Hello-World/keys/1\",\n \"title\": \"octocat@octomac\",\n \"verified\": true,\n \"created_at\": \"2014-12-10T15:53:42Z\",\n \"read_only\": true\n}" + "payload": "{\n \"url\": \"https://api.github.com/repos/octocat/example/deployments/1\",\n \"id\": 1,\n \"node_id\": \"MDEwOkRlcGxveW1lbnQx\",\n \"sha\": \"a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d\",\n \"ref\": \"topic-branch\",\n \"task\": \"deploy\",\n \"payload\": {},\n \"original_environment\": \"staging\",\n \"environment\": \"production\",\n \"description\": \"Deploy request from hubot\",\n \"creator\": {\n \"login\": \"octocat\",\n \"id\": 1,\n \"node_id\": \"MDQ6VXNlcjE=\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"gravatar_id\": \"\",\n \"url\": \"https://api.github.com/users/octocat\",\n \"html_url\": \"https://github.com/octocat\",\n \"followers_url\": \"https://api.github.com/users/octocat/followers\",\n \"following_url\": \"https://api.github.com/users/octocat/following{/other_user}\",\n \"gists_url\": \"https://api.github.com/users/octocat/gists{/gist_id}\",\n \"starred_url\": \"https://api.github.com/users/octocat/starred{/owner}{/repo}\",\n \"subscriptions_url\": \"https://api.github.com/users/octocat/subscriptions\",\n \"organizations_url\": \"https://api.github.com/users/octocat/orgs\",\n \"repos_url\": \"https://api.github.com/users/octocat/repos\",\n \"events_url\": \"https://api.github.com/users/octocat/events{/privacy}\",\n \"received_events_url\": \"https://api.github.com/users/octocat/received_events\",\n \"type\": \"User\",\n \"site_admin\": false\n },\n \"created_at\": \"2012-07-20T01:19:13Z\",\n \"updated_at\": \"2012-07-20T01:19:13Z\",\n \"statuses_url\": \"https://api.github.com/repos/octocat/example/deployments/1/statuses\",\n \"repository_url\": \"https://api.github.com/repos/octocat/example\",\n \"transient_environment\": false,\n \"production_environment\": true\n}" }, { "httpStatusCode": "404", "httpStatusMessage": "Not Found", "description": "Resource not found
" } - ] + ], + "subcategory": "deployments" }, { "verb": "delete", - "requestPath": "/repos/{owner}/{repo}/keys/{key_id}", + "requestPath": "/repos/{owner}/{repo}/deployments/{deployment_id}", "parameters": [ { "name": "owner", @@ -27784,45 +27776,55 @@ "descriptionHTML": "" }, { - "name": "key_id", - "description": "key_id parameter", + "name": "deployment_id", + "description": "deployment_id parameter", "in": "path", "required": true, "schema": { "type": "integer" }, - "descriptionHTML": "key_id parameter
" + "descriptionHTML": "deployment_id parameter
" } ], "x-codeSamples": [ { "lang": "Shell", - "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/keys/42" + "source": "curl \\\n -X DELETE \\\n -H \"Accept: application/vnd.github.v3+json\" \\\n https://{hostname}/api/v3/repos/octocat/hello-world/deployments/42" }, { "lang": "JavaScript", - "source": "await octokit.request('DELETE /repos/{owner}/{repo}/keys/{key_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n key_id: 42\n})" + "source": "await octokit.request('DELETE /repos/{owner}/{repo}/deployments/{deployment_id}', {\n owner: 'octocat',\n repo: 'hello-world',\n deployment_id: 42\n})" } ], - "summary": "Delete a deploy key", + "summary": "Delete a deployment", "x-github": { "enabledForGitHubApps": true, "category": "repos", - "subcategory": "keys" + "subcategory": "deployments" }, - "slug": "delete-a-deploy-key", + "slug": "delete-a-deployment", "category": "deployments", - "subcategory": "keys", "notes": [], "bodyParameters": [], - "descriptionHTML": "Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
", + "descriptionHTML": "If the repository only has one deployment, you can delete the deployment regardless of its status. If the repository has more than one deployment, you can only delete inactive deployments. This ensures that repositories with multiple deployments will always have an active deployment. Anyone with repo or repo_deployment scopes can delete a deployment.
To set a deployment as inactive, you must:
\nFor more information, see \"Create a deployment\" and \"Create a deployment status.\"
", "responses": [ { "httpStatusCode": "204", "httpStatusMessage": "No Content", "description": "Response
" + }, + { + "httpStatusCode": "404", + "httpStatusMessage": "Not Found", + "description": "Resource not found
" + }, + { + "httpStatusCode": "422", + "httpStatusMessage": "Unprocessable Entity", + "description": "Validation failed
" } - ] + ], + "subcategory": "deployments" } ], "statuses": [ diff --git a/script/rest/update-files.js b/script/rest/update-files.js index 2833791bbe3a..1a819e46b5d9 100755 --- a/script/rest/update-files.js +++ b/script/rest/update-files.js @@ -140,10 +140,15 @@ async function updateRedirectOverrides() { const redirects = {} console.log('\n➡️ Updating REST API redirect exception list.\n') - for (const value of Object.values(overrides)) { + for (const [key, value] of Object.entries(overrides)) { const oldUrl = value.originalUrl const anchor = oldUrl.replace('/rest/reference', '').split('#')[1] - redirects[oldUrl] = `/rest/reference/${value.category}#${anchor}` + if (key.includes('#')) { + // We are updating a subcategory into a category + redirects[oldUrl] = `/rest/reference/${value.category}` + } else { + redirects[oldUrl] = `/rest/reference/${value.category}#${anchor}` + } } await writeFile( 'lib/redirects/static/client-side-rest-api-redirects.json', diff --git a/script/rest/utils/rest-api-overrides.json b/script/rest/utils/rest-api-overrides.json index b94d33c10837..13e312dcebcd 100644 --- a/script/rest/utils/rest-api-overrides.json +++ b/script/rest/utils/rest-api-overrides.json @@ -130,25 +130,55 @@ "originalUrl": "/rest/reference/repos#delete-a-repository-invitation" }, "repos/list-deploy-keys": { - "category": "deployments", - "subcategory": "keys", + "category": "deploy_keys", + "subcategory": "deploy_keys", "originalUrl": "/rest/reference/repos#list-deploy-keys" }, "repos/create-deploy-key": { - "category": "deployments", - "subcategory": "keys", + "category": "deploy_keys", + "subcategory": "deploy_keys", "originalUrl": "/rest/reference/repos#create-a-deploy-key" }, "repos/get-deploy-key": { - "category": "deployments", - "subcategory": "keys", + "category": "deploy_keys", + "subcategory": "deploy_keys", "originalUrl": "/rest/reference/repos#get-a-deploy-key" }, "repos/delete-deploy-key": { - "category": "deployments", - "subcategory": "keys", + "category": "deploy_keys", + "subcategory": "deploy_keys", "originalUrl": "/rest/reference/repos#delete-a-deploy-key" }, + "repos#deploy-keys": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/repos#deploy-keys" + }, + "deployments/list-deploy-keys": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/deployments#list-deploy-keys" + }, + "deployments/create-deploy-key": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/deployments#create-a-deploy-key" + }, + "deployments/get-deploy-key": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/deployments#get-a-deploy-key" + }, + "deployments/delete-deploy-key": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/deployments#delete-a-deploy-key" + }, + "deployments#deploy-keys": { + "category": "deploy_keys", + "subcategory": "deploy_keys", + "originalUrl": "/rest/reference/deployments#deploy-keys" + }, "repos/get-pages": { "category": "pages", "subcategory": null,