Skip to content

Commit b1c2b43

Browse files
jschneiderjschneider
authored
Add missing token scopes to all scope enums (#1313)
1 parent da12d98 commit b1c2b43

5 files changed

Lines changed: 243 additions & 3 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,6 @@ gitlab4j-mock-config-*.properties
5959

6060
# git-changelog plugin #
6161
.okhttpcache
62+
63+
# IntelliJ HTTP Client private environment (contains tokens)
64+
http-client.private.env.json

‎gitlab4j-models/src/main/java/org/gitlab4j/api/models/ImpersonationToken.java‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,49 @@ public class ImpersonationToken implements Serializable {
1616

1717
/** Enum to specify the scope of an ImpersonationToken. */
1818
public enum Scope {
19+
/** Grants complete read/write access to the API. */
1920
API,
21+
22+
/** Grants read access to the API. */
2023
READ_API,
24+
25+
/** Grants read-only access to the user's profile. */
2126
READ_USER,
27+
28+
/** Grants read-only access to repositories on private projects using Git-over-HTTP. */
2229
READ_REPOSITORY,
30+
31+
/** Grants read-write access to repositories on private projects using Git-over-HTTP. */
2332
WRITE_REPOSITORY,
33+
34+
/** Grants read (pull) access to a Container Registry. */
2435
READ_REGISTRY,
36+
37+
/** Grants write (push) access to a Container Registry. */
2538
WRITE_REGISTRY,
39+
40+
/** Grants pull access through the dependency proxy. */
41+
READ_VIRTUAL_REGISTRY,
42+
43+
/** Grants push, pull and delete access through the dependency proxy. */
44+
WRITE_VIRTUAL_REGISTRY,
45+
46+
/** Grants create access to the runners. */
47+
CREATE_RUNNER,
48+
49+
/** Grants access to manage the runners. */
50+
MANAGE_RUNNER,
51+
52+
/** Grants access to GitLab Duo related API endpoints. */
53+
AI_FEATURES,
54+
55+
/** Grants permission to perform Kubernetes API calls using the agent for Kubernetes. */
2656
K8S_PROXY,
57+
58+
/** Grants permission to rotate this token using the personal access token API. */
59+
SELF_ROTATE,
60+
61+
/** Grants permission to perform API actions as any user in the system, when authenticated as an admin user. */
2762
SUDO;
2863

2964
private static JacksonJsonEnumHelper<Scope> enumHelper = new JacksonJsonEnumHelper<>(Scope.class);

‎gitlab4j-models/src/main/java/org/gitlab4j/models/Constants.java‎

Lines changed: 61 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -882,7 +882,22 @@ public enum ApplicationScope {
882882
PROFILE,
883883

884884
/** Grants read-only access to the user's primary email address using OpenID Connect. */
885-
EMAIL;
885+
EMAIL,
886+
887+
/** Grants read (pull) access to a Container Registry. */
888+
READ_REGISTRY,
889+
890+
/** Grants write (push) access to a Container Registry. */
891+
WRITE_REGISTRY,
892+
893+
/** Grants pull access through the dependency proxy. */
894+
READ_VIRTUAL_REGISTRY,
895+
896+
/** Grants push, pull and delete access through the dependency proxy. */
897+
WRITE_VIRTUAL_REGISTRY,
898+
899+
/** Grants permission to rotate this token using the personal access token API. */
900+
SELF_ROTATE;
886901

887902
private static JacksonJsonEnumHelper<ApplicationScope> enumHelper =
888903
new JacksonJsonEnumHelper<>(ApplicationScope.class);
@@ -1185,8 +1200,26 @@ public String toString() {
11851200

11861201
/** Enum to use for specifying the deploy token scope. */
11871202
public enum DeployTokenScope {
1203+
/** Grants read-only access to repositories on private projects using Git-over-HTTP. */
11881204
READ_REPOSITORY,
1189-
READ_REGISTRY;
1205+
1206+
/** Grants read (pull) access to a Container Registry. */
1207+
READ_REGISTRY,
1208+
1209+
/** Grants write (push) access to a Container Registry. */
1210+
WRITE_REGISTRY,
1211+
1212+
/** Grants pull access through the dependency proxy. */
1213+
READ_VIRTUAL_REGISTRY,
1214+
1215+
/** Grants push, pull and delete access through the dependency proxy. */
1216+
WRITE_VIRTUAL_REGISTRY,
1217+
1218+
/** Grants read access to the package registry. */
1219+
READ_PACKAGE_REGISTRY,
1220+
1221+
/** Grants write access to the package registry. */
1222+
WRITE_PACKAGE_REGISTRY;
11901223

11911224
private static JacksonJsonEnumHelper<DeployTokenScope> enumHelper =
11921225
new JacksonJsonEnumHelper<>(DeployTokenScope.class);
@@ -1209,13 +1242,38 @@ public String toString() {
12091242

12101243
/** Enum to use for specifying the project token scope. */
12111244
public enum ProjectAccessTokenScope {
1245+
/** Grants complete read/write access to the scoped project API. */
12121246
API,
1247+
1248+
/** Grants read access to the scoped project API. */
12131249
READ_API,
1250+
1251+
/** Grants read (pull) access to a Container Registry. */
12141252
READ_REGISTRY,
1253+
1254+
/** Grants write (push) access to a Container Registry. */
12151255
WRITE_REGISTRY,
1256+
1257+
/** Grants read-only access to repositories on private projects using Git-over-HTTP. */
12161258
READ_REPOSITORY,
1259+
1260+
/** Grants read-write access to repositories on private projects using Git-over-HTTP. */
12171261
WRITE_REPOSITORY,
1218-
CREATE_RUNNER;
1262+
1263+
/** Grants create access to the runners. */
1264+
CREATE_RUNNER,
1265+
1266+
/** Grants access to manage the runners. */
1267+
MANAGE_RUNNER,
1268+
1269+
/** Grants access to GitLab Duo related API endpoints. */
1270+
AI_FEATURES,
1271+
1272+
/** Grants permission to perform Kubernetes API calls using the agent for Kubernetes. */
1273+
K8S_PROXY,
1274+
1275+
/** Grants permission to rotate this token using the personal access token API. */
1276+
SELF_ROTATE;
12191277

12201278
private static JacksonJsonEnumHelper<ProjectAccessTokenScope> enumHelper =
12211279
new JacksonJsonEnumHelper<>(ProjectAccessTokenScope.class);

‎http-client.private.env.json.example‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"dev": {
3+
"token": "glpat-xxxxxxxxxxxxxxxxxxxx",
4+
"project_id": "12345",
5+
"group_id": "6789"
6+
}
7+
}

‎verify-scopes.http‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
### Verify that the added scopes exist in GitLab
2+
###
3+
### Prerequisites:
4+
### Copy http-client.private.env.json.example to http-client.private.env.json
5+
### and fill in your gitlab.com token, project_id, and group_id.
6+
### Then select the "dev" environment in IntelliJ before running.
7+
###
8+
### How the proof works:
9+
### GitLab validates scopes AFTER authentication. If a scope is valid,
10+
### the request succeeds (or fails for permission reasons: 403/404).
11+
### If a scope is INVALID, GitLab returns 400 with
12+
### "scopes does not have a valid value".
13+
###
14+
### Each section includes a negative test with a deliberately invalid
15+
### scope to demonstrate that GitLab does reject unknown scopes.
16+
17+
18+
### --- ApplicationScope: self_rotate ---
19+
###
20+
### The self-service PAT endpoint (POST /api/v4/user/personal_access_tokens)
21+
### only accepts k8s_proxy and self_rotate scopes (by design, GitLab 16.5+).
22+
### The other ApplicationScope scopes (read_registry, write_registry, etc.)
23+
### are valid PAT scopes but can only be set via the admin endpoint or the UI.
24+
###
25+
### Reference: https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes
26+
27+
### Positive: self_rotate scope (should return 201)
28+
POST https://gitlab.com/api/v4/user/personal_access_tokens
29+
PRIVATE-TOKEN: {{token}}
30+
Content-Type: application/json
31+
32+
{
33+
"name": "verify-self-rotate",
34+
"scopes": ["self_rotate"],
35+
"expires_at": "2026-12-31"
36+
}
37+
38+
### Negative: invalid scope (should return 400)
39+
POST https://gitlab.com/api/v4/user/personal_access_tokens
40+
PRIVATE-TOKEN: {{token}}
41+
Content-Type: application/json
42+
43+
{
44+
"name": "verify-invalid-scope",
45+
"scopes": ["THIS_SCOPE_DOES_NOT_EXIST"],
46+
"expires_at": "2026-12-31"
47+
}
48+
49+
### --- ProjectAccessTokenScope scopes ---
50+
###
51+
### Requires Maintainer access on the project.
52+
### Reference: https://docs.gitlab.com/user/project/settings/project_access_tokens/#scopes-for-a-project-access-token
53+
54+
### Positive: newly added scopes (should return 201, NOT 400)
55+
POST https://gitlab.com/api/v4/projects/{{project_id}}/access_tokens
56+
PRIVATE-TOKEN: {{token}}
57+
Content-Type: application/json
58+
59+
{
60+
"name": "verify-project-scopes-valid",
61+
"scopes": ["manage_runner", "ai_features", "k8s_proxy", "self_rotate"],
62+
"expires_at": "2026-12-31",
63+
"access_level": 30
64+
}
65+
66+
### Negative: invalid scope (should return 400)
67+
POST https://gitlab.com/api/v4/projects/{{project_id}}/access_tokens
68+
PRIVATE-TOKEN: {{token}}
69+
Content-Type: application/json
70+
71+
{
72+
"name": "verify-project-scopes-invalid",
73+
"scopes": ["manage_runner", "THIS_SCOPE_DOES_NOT_EXIST"],
74+
"expires_at": "2026-12-31",
75+
"access_level": 30
76+
}
77+
78+
### --- ImpersonationToken.Scope (Group Access Token) scopes ---
79+
###
80+
### Requires Owner access on the group.
81+
### Reference: https://docs.gitlab.com/user/group/settings/group_access_tokens/#scopes-for-a-group-access-token
82+
83+
### Positive: newly added scopes (should return 400 Bad request - User does not have permission to create group access token)
84+
POST https://gitlab.com/api/v4/groups/{{group_id}}/access_tokens
85+
PRIVATE-TOKEN: {{token}}
86+
Content-Type: application/json
87+
88+
{
89+
"name": "verify-group-scopes-valid",
90+
"scopes": ["create_runner", "manage_runner", "ai_features", "self_rotate", "read_virtual_registry", "write_virtual_registry"],
91+
"expires_at": "2026-12-31",
92+
"access_level": 30
93+
}
94+
95+
### Negative: invalid scope (should return 400 scopes does not have a valid value)
96+
POST https://gitlab.com/api/v4/groups/{{group_id}}/access_tokens
97+
PRIVATE-TOKEN: {{token}}
98+
Content-Type: application/json
99+
100+
{
101+
"name": "verify-group-scopes-invalid",
102+
"scopes": ["create_runner", "THIS_SCOPE_DOES_NOT_EXIST"],
103+
"expires_at": "2026-12-31",
104+
"access_level": 30
105+
}
106+
107+
### --- DeployTokenScope scopes ---
108+
###
109+
### Requires Maintainer access on the project.
110+
### Reference: https://docs.gitlab.com/user/project/deploy_tokens/#scope
111+
112+
### Positive: newly added scopes (should return 201, NOT 400)
113+
POST https://gitlab.com/api/v4/projects/{{project_id}}/deploy_tokens
114+
PRIVATE-TOKEN: {{token}}
115+
Content-Type: application/json
116+
117+
{
118+
"name": "verify-deploy-scopes-valid",
119+
"scopes": ["write_registry", "read_virtual_registry", "write_virtual_registry", "read_package_registry", "write_package_registry"],
120+
"expires_at": "2026-12-31"
121+
}
122+
123+
### Negative: invalid scope (should return 400 scopes does not have a valid value)
124+
POST https://gitlab.com/api/v4/projects/{{project_id}}/deploy_tokens
125+
PRIVATE-TOKEN: {{token}}
126+
Content-Type: application/json
127+
128+
{
129+
"name": "verify-deploy-scopes-invalid",
130+
"scopes": ["read_repository", "THIS_SCOPE_DOES_NOT_EXIST"],
131+
"expires_at": "2026-12-31"
132+
}
133+
134+
### --- Cleanup ---
135+
### If any tokens were created above, revoke them:
136+
### GET https://gitlab.com/api/v4/personal_access_tokens
137+
### then DELETE https://gitlab.com/api/v4/personal_access_tokens/:id

0 commit comments

Comments
 (0)