Skip to content

Update matrix-auth-plugin docs for v3.2+ syntax #2718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Oct 19, 2025
Merged

Update matrix-auth-plugin docs for v3.2+ syntax #2718

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
effd572
Update matrix-auth-plugin docs for v3.2+ syntax
Oct 5, 2025
67c53c2
Merge branch 'master' into update-matrix-auth-docs
Junaid-Ashraf-56 Oct 7, 2025
a3af5b5
Updated according to the given points
Oct 13, 2025
12614a5
Merge branch 'update-matrix-auth-docs' of github.com:Junaid-Ashraf-56…
Oct 13, 2025
d46dbe3
Merge branch 'master' into update-matrix-auth-docs
Junaid-Ashraf-56 Oct 13, 2025
f2d49fd
Test
Oct 14, 2025
ef300ac
Update
Oct 14, 2025
1833658
Update
Oct 14, 2025
9a94154
Delete integrations/src/test/java/io/jenkins/plugins/casc/ProjectMatr…
Junaid-Ashraf-56 Oct 14, 2025
94a0259
Merge branch 'master' into update-matrix-auth-docs
Junaid-Ashraf-56 Oct 17, 2025
ecdce5d
Revert "Delete integrations/src/test/java/io/jenkins/plugins/casc/Pro…
timja Oct 19, 2025
6447cd8
Fixup
timja Oct 19, 2025
627244f
Re-add most of a sentence
timja Oct 19, 2025
39fddd7
Fmt
timja Oct 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 61 additions & 2 deletions demos/global-matrix-auth/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# matrix-auth-plugin

Requires `matrix-auth` >= 3.0
Requires `matrix-auth` >= 3.2
> Starting from version 3.2 of the `matrix-auth` plugin, the JCasC syntax for configuring permissions has changed. The previous `permissions:` format is deprecated and replaced with a structured `entries:` format. While older configurations may still work with `deprecated: warn`, it is recommended to migrate to the new format.

There are a couple of built-in authorizations to consider.

Expand All @@ -9,6 +10,30 @@ There are a couple of built-in authorizations to consider.

## sample-configuration (global matrix)

Updated Configuration:
```yaml
jenkins:
authorizationStrategy:
globalMatrix:
entries:
- user:
name: "admin"
permissions:
- "Overall/Administer"
- user:
name: "anonymous"
permissions:
- "Overall/Read"
- group:
name: "authenticated"
permissions:
- "Overall/Administer"
```
Permissions must be defined **per line**, meaning each line must grant permission to only a single role, and only a single user or group of users.



## Deprecated Configuration (Pre-3.2)
```yaml
jenkins:
authorizationStrategy:
Expand All @@ -18,10 +43,44 @@ jenkins:
- "GROUP:Overall/Administer:authenticated"
- "USER:Overall/Administer:admin"
```
Permissions must be defined **per line**, meaning each line must grant permission to only a single role, and only a single user or group of users.



## sample-configuration (project based matrix)

```yaml
jenkins:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you update the integration test to use this to prove it works please (and continues to work):

https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/integrations/src/test/java/io/jenkins/plugins/casc/ProjectMatrixAuthorizationTest.java

It will need to change to use the JenkinsConfiguredWithReadmeRule

You can then append #<heading-number> to the ConfiguredWithReadme so that it uses the right example, like in:

configuration-as-code-plugin/integrations/src/test/java/io/jenkins/plugins/casc/GitHostKeyVerificationTest.java

Line 22 in 4cb0061

@ConfiguredWithReadme("git-client/README.md#2")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a pleasure for me to work on the repo.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you haven't done this

authorizationStrategy:
projectMatrix:
entries:
- group:
name: "authenticated"
permissions:
- "View/Delete"
- "View/Read"
- "View/Configure"
- "View/Create"
- "Job/Read"
- "Job/Build"
- "Job/Configure"
- "Job/Create"
- "Job/Delete"
- "Job/Discover"
- "Job/Move"
- "Job/Workspace"
- "Job/Cancel"
- "Run/Delete"
- "Run/Replay"
- "Run/Update"
- "SCM/Tag"
- "Overall/Administer"
- user:
name: "anonymous"
permissions:
- "Overall/Read"
```

## Deprecated Configuration for Project Matrix (Pre-3.2)
```yaml
jenkins:
authorizationStrategy:
Expand Down