Skip to content

Commit 38360ca

Browse files
docs-botdocs-bot
authored
Merge pull request #44058 from github/repo-sync
Repo sync
2 parents 70aa62e + 2a91c94 commit 38360ca

14 files changed

Lines changed: 988 additions & 13 deletions

File tree

‎content/rest/about-the-rest-api/api-versions.md‎

Lines changed: 38 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ curl {% data reusables.rest-api.version-header %} https://github.com/__api/zen
3636

3737
Requests without the `X-GitHub-Api-Version` header will default to use the `{{ defaultRestApiVersion }}` version.
3838

39-
If you specify an API version that is no longer supported, you will receive a `400` error.
39+
If you specify an API version that is no longer supported, you will receive a `410 Gone` response.
4040

4141
## Upgrading to a new API version
4242

@@ -46,12 +46,45 @@ When you update your integration to specify the new API version in the `X-GitHub
4646

4747
Once your integration is updated, test your integration to verify that it works with the new API version.
4848

49+
## API version {% data variables.release-phases.closing_down %}
50+
51+
API versions are supported for 24 months after a newer API version is released.
52+
53+
While a version is within its support window but approaching {% data variables.release-phases.closing_down %}, {% data variables.product.github %} includes the following headers in API responses to help you prepare for migration:
54+
55+
* `Deprecation` — The date when the API version will be {% data variables.release-phases.closing_down %}, formatted as an HTTP date per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1). For example: `Wed, 27 Nov 2019 14:34:29 GMT`. <!-- markdownlint-disable-line GHD046 -->
56+
* `Sunset` — The date when the API version will be completely removed ({% data variables.release-phases.retired %}), after which requests will return a `410 Gone` response. Follows [RFC 8594](https://tools.ietf.org/html/rfc8594). For example: `Fri, 27 Nov 2020 14:34:29 GMT`. <!-- markdownlint-disable-line GHD046 -->
57+
58+
After the support window ends:
59+
60+
* Requests that specify a {% data variables.release-phases.closing_down %} API version receive a `410 Gone` response.
61+
* Requests that do not specify an API version default to the next oldest supported version, not the {% data variables.release-phases.closing_down %} version. If you rely on unversioned requests, you may observe behavioral changes as older versions are removed from support.
62+
63+
For more information on migrating to a newer API version, see [AUTOTITLE](/rest/about-the-rest-api/breaking-changes).
64+
65+
## Exceptions to standard versioning
66+
67+
In rare cases, {% data variables.product.github %} may make changes outside the normal API versioning cadence. These are exceptional interventions that do not alter the standard versioning guarantees for most integrators.
68+
69+
### Security, availability, and reliability issues
70+
71+
Critical security vulnerabilities, data exposure risks, or severe reliability issues may require changes outside the normal release schedule. {% data variables.product.github %} may release an unscheduled API version, backport fixes to supported versions, or in rare cases, introduce a breaking change to an existing version to protect users and platform integrity.
72+
73+
{% data variables.product.github %} will communicate such changes through release notes, changelogs, and direct communication explaining what changed and why. Where feasible, advance notice will be provided. Immediate action may be taken without advance notice when required.
74+
75+
### Low-usage services
76+
77+
For certain services with very low usage, {% data variables.product.github %} may deprecate functionality outside the standard versioning process. In these cases, {% data variables.product.github %} will communicate the intent and reach out to affected integrators directly.
78+
4979
## Supported API versions
5080

51-
The following REST API versions are currently supported:
81+
The following REST API versions are currently supported.
5282

53-
{% for apiVersion in allVersions[currentVersion].apiVersions %}
54-
{{ apiVersion }}
55-
{% endfor %}
83+
| API version | End of support date |
84+
| --- | --- |
85+
{%- for apiVersion in allVersions[currentVersion].apiVersions %}
86+
{%- assign versionData = tables.rest-api-versions.versions[apiVersion] %}
87+
| `{{ apiVersion }}` | {{ versionData.end_of_support | default: "Not yet scheduled" }} |
88+
{%- endfor %}
5689

5790
You can also make an API request to get all of the supported API versions. For more information, see [AUTOTITLE](/rest/meta/meta#get-all-api-versions).

‎data/reusables/rest-api/about-api-versions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The {% data variables.product.github %} REST API is versioned. The API version name is based on the date when the API version was released. For example, the API version `{{ initialRestVersioningReleaseDate }}` was released on {{ initialRestVersioningReleaseDateLong }}.
22

3-
Breaking changes are changes that can potentially break an integration. We will provide advance notice before releasing breaking changes. Breaking changes include:
3+
Breaking changes are changes that can potentially break an integration. Breaking changes will be released in a new API version. We will provide advance notice before releasing breaking changes. Breaking changes include:
44

55
* Removing an entire operation
66
* Removing or renaming a parameter

‎data/tables/rest-api-versions.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# REST API calendar date versions and their end of support dates.
2+
# Rendering code lives in content/rest/about-the-rest-api/api-versions.md
3+
4+
versions:
5+
'2022-11-28':
6+
end_of_support: 'March 10, 2028'
7+
'2026-03-10':
8+
end_of_support: ~

‎src/data-directory/lib/data-schemas/tables/rest-api-versions.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// This schema enforces the structure in data/tables/rest-api-versions.yml
2+
3+
export default {
4+
type: 'object',
5+
additionalProperties: false,
6+
required: ['versions'],
7+
properties: {
8+
versions: {
9+
type: 'object',
10+
additionalProperties: {
11+
type: 'object',
12+
additionalProperties: false,
13+
required: ['end_of_support'],
14+
properties: {
15+
end_of_support: {
16+
type: ['string', 'null'],
17+
},
18+
},
19+
},
20+
},
21+
},
22+
}

‎src/github-apps/data/fpt-2022-11-28/fine-grained-pat-permissions.json‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1076,6 +1076,102 @@
10761076
}
10771077
]
10781078
},
1079+
"organization_copilot_spaces": {
1080+
"title": "Copilot Spaces",
1081+
"displayTitle": "Organization permissions for \"Copilot Spaces\"",
1082+
"permissions": [
1083+
{
1084+
"category": "copilot-spaces",
1085+
"slug": "list-organization-copilot-spaces",
1086+
"subcategory": "copilot-spaces",
1087+
"verb": "get",
1088+
"requestPath": "/orgs/{org}/copilot-spaces",
1089+
"additional-permissions": false,
1090+
"access": "read"
1091+
},
1092+
{
1093+
"category": "copilot-spaces",
1094+
"slug": "create-an-organization-copilot-space",
1095+
"subcategory": "copilot-spaces",
1096+
"verb": "post",
1097+
"requestPath": "/orgs/{org}/copilot-spaces",
1098+
"additional-permissions": false,
1099+
"access": "write"
1100+
},
1101+
{
1102+
"category": "copilot-spaces",
1103+
"slug": "get-an-organization-copilot-space",
1104+
"subcategory": "copilot-spaces",
1105+
"verb": "get",
1106+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1107+
"additional-permissions": false,
1108+
"access": "read"
1109+
},
1110+
{
1111+
"category": "copilot-spaces",
1112+
"slug": "set-an-organization-copilot-space",
1113+
"subcategory": "copilot-spaces",
1114+
"verb": "put",
1115+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1116+
"additional-permissions": false,
1117+
"access": "write"
1118+
},
1119+
{
1120+
"category": "copilot-spaces",
1121+
"slug": "delete-an-organization-copilot-space",
1122+
"subcategory": "copilot-spaces",
1123+
"verb": "delete",
1124+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1125+
"additional-permissions": false,
1126+
"access": "write"
1127+
},
1128+
{
1129+
"category": "copilot-spaces",
1130+
"slug": "list-resources-for-an-organization-copilot-space",
1131+
"subcategory": "resources",
1132+
"verb": "get",
1133+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources",
1134+
"additional-permissions": false,
1135+
"access": "read"
1136+
},
1137+
{
1138+
"category": "copilot-spaces",
1139+
"slug": "create-a-resource-for-an-organization-copilot-space",
1140+
"subcategory": "resources",
1141+
"verb": "post",
1142+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources",
1143+
"additional-permissions": false,
1144+
"access": "write"
1145+
},
1146+
{
1147+
"category": "copilot-spaces",
1148+
"slug": "get-a-resource-for-an-organization-copilot-space",
1149+
"subcategory": "resources",
1150+
"verb": "get",
1151+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1152+
"additional-permissions": false,
1153+
"access": "read"
1154+
},
1155+
{
1156+
"category": "copilot-spaces",
1157+
"slug": "set-a-resource-for-an-organization-copilot-space",
1158+
"subcategory": "resources",
1159+
"verb": "put",
1160+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1161+
"additional-permissions": false,
1162+
"access": "write"
1163+
},
1164+
{
1165+
"category": "copilot-spaces",
1166+
"slug": "delete-a-resource-from-an-organization-copilot-space",
1167+
"subcategory": "resources",
1168+
"verb": "delete",
1169+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1170+
"additional-permissions": false,
1171+
"access": "write"
1172+
}
1173+
]
1174+
},
10791175
"organization_copilot_agent_settings": {
10801176
"title": "Copilot agent settings",
10811177
"displayTitle": "Organization permissions for \"Copilot agent settings\"",

‎src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1553,6 +1553,122 @@
15531553
}
15541554
]
15551555
},
1556+
"organization_copilot_spaces": {
1557+
"title": "Copilot Spaces",
1558+
"displayTitle": "Organization permissions for \"Copilot Spaces\"",
1559+
"permissions": [
1560+
{
1561+
"category": "copilot-spaces",
1562+
"slug": "list-organization-copilot-spaces",
1563+
"subcategory": "copilot-spaces",
1564+
"verb": "get",
1565+
"requestPath": "/orgs/{org}/copilot-spaces",
1566+
"access": "read",
1567+
"user-to-server": true,
1568+
"server-to-server": true,
1569+
"additional-permissions": false
1570+
},
1571+
{
1572+
"category": "copilot-spaces",
1573+
"slug": "create-an-organization-copilot-space",
1574+
"subcategory": "copilot-spaces",
1575+
"verb": "post",
1576+
"requestPath": "/orgs/{org}/copilot-spaces",
1577+
"access": "write",
1578+
"user-to-server": true,
1579+
"server-to-server": true,
1580+
"additional-permissions": false
1581+
},
1582+
{
1583+
"category": "copilot-spaces",
1584+
"slug": "get-an-organization-copilot-space",
1585+
"subcategory": "copilot-spaces",
1586+
"verb": "get",
1587+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1588+
"access": "read",
1589+
"user-to-server": true,
1590+
"server-to-server": true,
1591+
"additional-permissions": false
1592+
},
1593+
{
1594+
"category": "copilot-spaces",
1595+
"slug": "set-an-organization-copilot-space",
1596+
"subcategory": "copilot-spaces",
1597+
"verb": "put",
1598+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1599+
"access": "write",
1600+
"user-to-server": true,
1601+
"server-to-server": true,
1602+
"additional-permissions": false
1603+
},
1604+
{
1605+
"category": "copilot-spaces",
1606+
"slug": "delete-an-organization-copilot-space",
1607+
"subcategory": "copilot-spaces",
1608+
"verb": "delete",
1609+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}",
1610+
"access": "write",
1611+
"user-to-server": true,
1612+
"server-to-server": true,
1613+
"additional-permissions": false
1614+
},
1615+
{
1616+
"category": "copilot-spaces",
1617+
"slug": "list-resources-for-an-organization-copilot-space",
1618+
"subcategory": "resources",
1619+
"verb": "get",
1620+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources",
1621+
"access": "read",
1622+
"user-to-server": true,
1623+
"server-to-server": true,
1624+
"additional-permissions": false
1625+
},
1626+
{
1627+
"category": "copilot-spaces",
1628+
"slug": "create-a-resource-for-an-organization-copilot-space",
1629+
"subcategory": "resources",
1630+
"verb": "post",
1631+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources",
1632+
"access": "write",
1633+
"user-to-server": true,
1634+
"server-to-server": true,
1635+
"additional-permissions": false
1636+
},
1637+
{
1638+
"category": "copilot-spaces",
1639+
"slug": "get-a-resource-for-an-organization-copilot-space",
1640+
"subcategory": "resources",
1641+
"verb": "get",
1642+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1643+
"access": "read",
1644+
"user-to-server": true,
1645+
"server-to-server": true,
1646+
"additional-permissions": false
1647+
},
1648+
{
1649+
"category": "copilot-spaces",
1650+
"slug": "set-a-resource-for-an-organization-copilot-space",
1651+
"subcategory": "resources",
1652+
"verb": "put",
1653+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1654+
"access": "write",
1655+
"user-to-server": true,
1656+
"server-to-server": true,
1657+
"additional-permissions": false
1658+
},
1659+
{
1660+
"category": "copilot-spaces",
1661+
"slug": "delete-a-resource-from-an-organization-copilot-space",
1662+
"subcategory": "resources",
1663+
"verb": "delete",
1664+
"requestPath": "/orgs/{org}/copilot-spaces/{space_number}/resources/{space_resource_id}",
1665+
"access": "write",
1666+
"user-to-server": true,
1667+
"server-to-server": true,
1668+
"additional-permissions": false
1669+
}
1670+
]
1671+
},
15561672
"organization_copilot_agent_settings": {
15571673
"title": "Copilot agent settings",
15581674
"displayTitle": "Organization permissions for \"Copilot agent settings\"",

0 commit comments

Comments
 (0)