Skip to content

Commit b3ec08a

Browse files
octokitbotoctokitbot
authored
feat: add new public beta APIs for creating, reading, updating and deleting custom repo roles (POST /orgs/{org}/custom_roles, PATCH /orgs/{org}/custom_roles/{role_id}, DELETE /orgs/{org}/custom_roles/{role_id}, GET /orgs/{org}/fine_grained_permissions) (#549)
WIP octokit/openapi updated
1 parent 0a28d54 commit b3ec08a

19 files changed

+699
-66
lines changed

‎docs/actions/listWorkflowRuns.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
name: List workflow runs
2+
name: List workflow runs for a workflow
33
example: octokit.rest.actions.listWorkflowRuns({ owner, repo, workflow_id })
44
route: GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs
55
scope: actions
66
type: API method
77
---
88

9-
# List workflow runs
9+
# List workflow runs for a workflow
1010

1111
List all workflow runs for a workflow. You can replace `workflow_id` with the workflow file name. For example, you could use `main.yaml`. You can use parameters to narrow the list of results. For more information about using parameters, see [Parameters](https://docs.github.com/rest/overview/resources-in-the-rest-api#parameters).
1212

‎docs/orgs/createCustomRole.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
name: Create a custom role
3+
example: octokit.rest.orgs.createCustomRole({ org, name, base_role, permissions })
4+
route: POST /orgs/{org}/custom_roles
5+
scope: orgs
6+
type: API method
7+
---
8+
9+
# Create a custom role
10+
11+
**Note**: This operation is in beta and is subject to change.
12+
13+
Creates a custom repository role that can be used by all repositories owned by the organization.
14+
15+
To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with `admin:org` scope.
16+
GitHub Apps must have the `organization_custom_roles:write` organization permission to use this endpoint.
17+
18+
For more information on custom repository roles, see "[Managing custom repository roles for an organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization)."
19+
20+
```js
21+
octokit.rest.orgs.createCustomRole({
22+
org,
23+
name,
24+
base_role,
25+
permissions,
26+
});
27+
```
28+
29+
## Parameters
30+
31+
<table>
32+
<thead>
33+
<tr>
34+
<th>name</th>
35+
<th>required</th>
36+
<th>description</th>
37+
</tr>
38+
</thead>
39+
<tbody>
40+
<tr><td>org</td><td>yes</td><td>
41+
42+
The organization name. The name is not case sensitive.
43+
44+
</td></tr>
45+
<tr><td>name</td><td>yes</td><td>
46+
47+
The name of the custom role.
48+
49+
</td></tr>
50+
<tr><td>description</td><td>no</td><td>
51+
52+
A short description about the intended usage of this role or what permissions it grants.
53+
54+
</td></tr>
55+
<tr><td>base_role</td><td>yes</td><td>
56+
57+
The system role from which this role inherits permissions.
58+
59+
</td></tr>
60+
<tr><td>permissions</td><td>yes</td><td>
61+
62+
A list of additional permissions included in this role.
63+
64+
</td></tr>
65+
</tbody>
66+
</table>
67+
68+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/orgs#create-a-custom-role).

‎docs/orgs/deleteCustomRole.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: Delete a custom role
3+
example: octokit.rest.orgs.deleteCustomRole({ org, role_id })
4+
route: DELETE /orgs/{org}/custom_roles/{role_id}
5+
scope: orgs
6+
type: API method
7+
---
8+
9+
# Delete a custom role
10+
11+
**Note**: This operation is in beta and is subject to change.
12+
13+
Deletes a custom role from an organization. Once the custom role has been deleted, any
14+
user, team, or invitation with the deleted custom role will be reassigned the inherited role.
15+
16+
To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with `admin:org` scope.
17+
GitHub Apps must have the `organization_custom_roles:write` organization permission to use this endpoint.
18+
19+
For more information about custom repository roles, see "[Managing custom repository roles for an organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization)."
20+
21+
```js
22+
octokit.rest.orgs.deleteCustomRole({
23+
org,
24+
role_id,
25+
});
26+
```
27+
28+
## Parameters
29+
30+
<table>
31+
<thead>
32+
<tr>
33+
<th>name</th>
34+
<th>required</th>
35+
<th>description</th>
36+
</tr>
37+
</thead>
38+
<tbody>
39+
<tr><td>org</td><td>yes</td><td>
40+
41+
The organization name. The name is not case sensitive.
42+
43+
</td></tr>
44+
<tr><td>role_id</td><td>yes</td><td>
45+
46+
The unique identifier of the role.
47+
48+
</td></tr>
49+
</tbody>
50+
</table>
51+
52+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/orgs#delete-a-custom-role).

‎docs/orgs/listFineGrainedPermissions.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: List fine-grained permissions for an organization
3+
example: octokit.rest.orgs.listFineGrainedPermissions({ org })
4+
route: GET /orgs/{org}/fine_grained_permissions
5+
scope: orgs
6+
type: API method
7+
---
8+
9+
# List fine-grained permissions for an organization
10+
11+
**Note**: This operation is in beta and subject to change.
12+
13+
Lists the fine-grained permissions available for an organization.
14+
15+
To use this endpoint the authenticated user must be an administrator for the organization or of an repository of the organizaiton and must use an access token with `admin:org repo` scope.
16+
GitHub Apps must have the `organization_custom_roles:read` organization permission to use this endpoint.
17+
18+
```js
19+
octokit.rest.orgs.listFineGrainedPermissions({
20+
org,
21+
});
22+
```
23+
24+
## Parameters
25+
26+
<table>
27+
<thead>
28+
<tr>
29+
<th>name</th>
30+
<th>required</th>
31+
<th>description</th>
32+
</tr>
33+
</thead>
34+
<tbody>
35+
<tr><td>org</td><td>yes</td><td>
36+
37+
The organization name. The name is not case sensitive.
38+
39+
</td></tr>
40+
</tbody>
41+
</table>
42+
43+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/orgs#list-fine-grained-permissions-for-an-organization).

‎docs/orgs/updateCustomRole.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
name: Update a custom role
3+
example: octokit.rest.orgs.updateCustomRole({ org, role_id })
4+
route: PATCH /orgs/{org}/custom_roles/{role_id}
5+
scope: orgs
6+
type: API method
7+
---
8+
9+
# Update a custom role
10+
11+
**Note**: This operation is in beta and subject to change.
12+
13+
Updates a custom repository role that can be used by all repositories owned by the organization.
14+
15+
To use this endpoint the authenticated user must be an administrator for the organization and must use an access token with `admin:org` scope.
16+
GitHub Apps must have the `organization_custom_roles:write` organization permission to use this endpoint.
17+
18+
For more information about custom repository roles, see "[Managing custom repository roles for an organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization)."
19+
20+
```js
21+
octokit.rest.orgs.updateCustomRole({
22+
org,
23+
role_id,
24+
});
25+
```
26+
27+
## Parameters
28+
29+
<table>
30+
<thead>
31+
<tr>
32+
<th>name</th>
33+
<th>required</th>
34+
<th>description</th>
35+
</tr>
36+
</thead>
37+
<tbody>
38+
<tr><td>org</td><td>yes</td><td>
39+
40+
The organization name. The name is not case sensitive.
41+
42+
</td></tr>
43+
<tr><td>role_id</td><td>yes</td><td>
44+
45+
The unique identifier of the role.
46+
47+
</td></tr>
48+
<tr><td>name</td><td>no</td><td>
49+
50+
The name of the custom role.
51+
52+
</td></tr>
53+
<tr><td>description</td><td>no</td><td>
54+
55+
A short description about who this role is for or what permissions it grants.
56+
57+
</td></tr>
58+
<tr><td>base_role</td><td>no</td><td>
59+
60+
The system role from which this role inherits permissions.
61+
62+
</td></tr>
63+
<tr><td>permissions</td><td>no</td><td>
64+
65+
A list of additional permissions included in this role. If specified, these permissions will replace any currently set on the role.
66+
67+
</td></tr>
68+
</tbody>
69+
</table>
70+
71+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/orgs#update-a-custom-role).

‎docs/packages/getAllPackageVersionsForAPackageOwnedByAnOrg.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
---
2-
name: Get all package versions for a package owned by an organization
2+
name: List package versions for a package owned by an organization
33
example: octokit.rest.packages.getAllPackageVersionsForAPackageOwnedByAnOrg({ package_type, package_name, org })
44
route: GET /orgs/{org}/packages/{package_type}/{package_name}/versions
55
scope: packages
66
type: API method
77
---
88

9-
# Get all package versions for a package owned by an organization
9+
# List package versions for a package owned by an organization
1010

1111
**Deprecated:** This method has been renamed to packages.getAllPackageVersionsForPackageOwnedByOrg
1212

13-
Returns all package versions for a package owned by an organization.
13+
Lists package versions for a package owned by an organization.
1414

1515
To use this endpoint, you must authenticate using an access token with the `packages:read` scope.
1616
If `package_type` is not `container`, your token must also include the `repo` scope.
@@ -67,4 +67,4 @@ The state of the package, either active or deleted.
6767
</tbody>
6868
</table>
6969

70-
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/packages#get-all-package-versions-for-a-package-owned-by-an-organization).
70+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/packages#get-all-package-versions-for-a-package-owned-by-an-organization).

‎docs/packages/getAllPackageVersionsForAPackageOwnedByTheAuthenticatedUser.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
---
2-
name: Get all package versions for a package owned by the authenticated user
2+
name: List package versions for a package owned by the authenticated user
33
example: octokit.rest.packages.getAllPackageVersionsForAPackageOwnedByTheAuthenticatedUser({ package_type, package_name })
44
route: GET /user/packages/{package_type}/{package_name}/versions
55
scope: packages
66
type: API method
77
---
88

9-
# Get all package versions for a package owned by the authenticated user
9+
# List package versions for a package owned by the authenticated user
1010

1111
**Deprecated:** This method has been renamed to packages.getAllPackageVersionsForPackageOwnedByAuthenticatedUser
1212

13-
Returns all package versions for a package owned by the authenticated user.
13+
Lists package versions for a package owned by the authenticated user.
1414

1515
To use this endpoint, you must authenticate using an access token with the `packages:read` scope.
1616
If `package_type` is not `container`, your token must also include the `repo` scope.
@@ -63,4 +63,4 @@ The state of the package, either active or deleted.
6363
</tbody>
6464
</table>
6565

66-
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/packages#get-all-package-versions-for-a-package-owned-by-the-authenticated-user).
66+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/packages#get-all-package-versions-for-a-package-owned-by-the-authenticated-user).

‎docs/packages/getAllPackageVersionsForPackageOwnedByAuthenticatedUser.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
2-
name: Get all package versions for a package owned by the authenticated user
2+
name: List package versions for a package owned by the authenticated user
33
example: octokit.rest.packages.getAllPackageVersionsForPackageOwnedByAuthenticatedUser({ package_type, package_name })
44
route: GET /user/packages/{package_type}/{package_name}/versions
55
scope: packages
66
type: API method
77
---
88

9-
# Get all package versions for a package owned by the authenticated user
9+
# List package versions for a package owned by the authenticated user
1010

11-
Returns all package versions for a package owned by the authenticated user.
11+
Lists package versions for a package owned by the authenticated user.
1212

1313
To use this endpoint, you must authenticate using an access token with the `packages:read` scope.
1414
If `package_type` is not `container`, your token must also include the `repo` scope.
@@ -59,4 +59,4 @@ The state of the package, either active or deleted.
5959
</tbody>
6060
</table>
6161

62-
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/packages#get-all-package-versions-for-a-package-owned-by-the-authenticated-user).
62+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/packages#get-all-package-versions-for-a-package-owned-by-the-authenticated-user).

‎docs/packages/getAllPackageVersionsForPackageOwnedByOrg.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
2-
name: Get all package versions for a package owned by an organization
2+
name: List package versions for a package owned by an organization
33
example: octokit.rest.packages.getAllPackageVersionsForPackageOwnedByOrg({ package_type, package_name, org })
44
route: GET /orgs/{org}/packages/{package_type}/{package_name}/versions
55
scope: packages
66
type: API method
77
---
88

9-
# Get all package versions for a package owned by an organization
9+
# List package versions for a package owned by an organization
1010

11-
Returns all package versions for a package owned by an organization.
11+
Lists package versions for a package owned by an organization.
1212

1313
To use this endpoint, you must authenticate using an access token with the `packages:read` scope.
1414
If `package_type` is not `container`, your token must also include the `repo` scope.
@@ -65,4 +65,4 @@ The state of the package, either active or deleted.
6565
</tbody>
6666
</table>
6767

68-
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/packages#get-all-package-versions-for-a-package-owned-by-an-organization).
68+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/packages#get-all-package-versions-for-a-package-owned-by-an-organization).

‎docs/packages/getAllPackageVersionsForPackageOwnedByUser.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
2-
name: Get all package versions for a package owned by a user
2+
name: List package versions for a package owned by a user
33
example: octokit.rest.packages.getAllPackageVersionsForPackageOwnedByUser({ package_type, package_name, username })
44
route: GET /users/{username}/packages/{package_type}/{package_name}/versions
55
scope: packages
66
type: API method
77
---
88

9-
# Get all package versions for a package owned by a user
9+
# List package versions for a package owned by a user
1010

11-
Returns all package versions for a public package owned by a specified user.
11+
Lists package versions for a public package owned by a specified user.
1212

1313
To use this endpoint, you must authenticate using an access token with the `packages:read` scope.
1414
If `package_type` is not `container`, your token must also include the `repo` scope.
@@ -50,4 +50,4 @@ The handle for the GitHub user account.
5050
</tbody>
5151
</table>
5252

53-
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/reference/packages#get-all-package-versions-for-a-package-owned-by-a-user).
53+
See also: [GitHub Developer Guide documentation](https://docs.github.com/rest/packages#get-all-package-versions-for-a-package-owned-by-a-user).

0 commit comments

Comments
 (0)