From 00e2ec32d73b883f0c3df8c36a9b4191752eaa8c Mon Sep 17 00:00:00 2001 From: Sirine Jnayeh Date: Tue, 20 Aug 2024 20:32:50 +0000 Subject: [PATCH 1/9] Update documentation for setting NOTIFY_COMMIT_ACCESS_CONTROL system property --- README.adoc | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.adoc b/README.adoc index 548b5924fa..c4a59cedf0 100644 --- a/README.adoc +++ b/README.adoc @@ -470,6 +470,38 @@ If hooks are allowed and a git repository includes a `pre-auto-gc` hook, the hoo + See link:https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks["Customizing Git - Git Hooks"] for more details about git repository hooks. +[[global-security-notify-commit-access-control]] +Notify Commit Access Control:: + +The NOTIFY_COMMIT_ACCESS_CONTROL setting allows you to control access to the notifyCommit URL. +This URL is used to trigger builds when changes are pushed to the repository. +By default, access to this URL is unrestricted, which means anyone who knows the URL can trigger a build. ++ +To enhance security, it is recommended to restrict access to the notifyCommit URL. +You can configure this setting to allow only authenticated users or specific IP addresses to trigger builds. ++ +To configure NOTIFY_COMMIT_ACCESS_CONTROL, navigate to the Configure Global Security page and locate the Git Plugin section. +From there, you can specify the access control rules that best fit your security requirements. ++ +You can set the NOTIFY_COMMIT_ACCESS_CONTROL value using the following methods: ++ + +.... +java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled -jar jenkins.war +.... + ++ +[#using-a-groovy-script-security-configuration] +==== Using a Groovy Script ++ +Alternatively, the property can be set using a Groovy script placed in the `init.groovy.d` directory. This method is useful for environments where you manage Jenkins settings through scripts: ++ + +[source,groovy] +---- +hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL = 'disabled' +---- + [#repository-browser] === Repository Browser From cff0e474d9d178db60f6cfb92fe3041e126ded8b Mon Sep 17 00:00:00 2001 From: Sirine Jnayeh Date: Tue, 20 Aug 2024 20:35:32 +0000 Subject: [PATCH 2/9] fixed spacing --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index c4a59cedf0..6bdd6a3484 100644 --- a/README.adoc +++ b/README.adoc @@ -492,7 +492,7 @@ java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled -jar j + [#using-a-groovy-script-security-configuration] -==== Using a Groovy Script + Using a Groovy Script:: + Alternatively, the property can be set using a Groovy script placed in the `init.groovy.d` directory. This method is useful for environments where you manage Jenkins settings through scripts: + From 9c5f63682f2d1d1ef251f6e44aeb106ce6b1ade8 Mon Sep 17 00:00:00 2001 From: Sirine Jnayeh Date: Tue, 20 Aug 2024 22:09:58 +0000 Subject: [PATCH 3/9] Updated README file --- .gitpod.yml | 10 ++++++++++ README.adoc | 51 +++++++++++++++++++-------------------------------- 2 files changed, 29 insertions(+), 32 deletions(-) create mode 100644 .gitpod.yml diff --git a/.gitpod.yml b/.gitpod.yml new file mode 100644 index 0000000000..4efa528141 --- /dev/null +++ b/.gitpod.yml @@ -0,0 +1,10 @@ +# This configuration file was automatically generated by Gitpod. +# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) +# and commit this file to your remote git repository to share the goodness with others. + +# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart + +tasks: + - init: mvn install -DskipTests=false + + diff --git a/README.adoc b/README.adoc index 80938b3f30..9d4e9a7bac 100644 --- a/README.adoc +++ b/README.adoc @@ -330,6 +330,25 @@ The `token` parameter is required by default as a security measure, but can be d hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL .... +You can set the NOTIFY_COMMIT_ACCESS_CONTROL value using the following methods: + +[[using-Java-System-Property-push-notification-from-repository]] +Using Java System Property:: + +.... +java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled -jar jenkins.war +.... + +[#using-a-groovy-script-push-notification-from-repository] + Using a Groovy Script:: + +The property can be set using a Groovy script placed in the `init.groovy.d` directory. This method is useful for environments where you manage Jenkins settings through scripts: + +[source,groovy] +---- +hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL = 'disabled' +---- + It has two modes: * `disabled-for-polling` - Allows unauthenticated requests as long as they only request polling of the repository supplied in the `url` query parameter. Prohibits unauthenticated requests that attempt to schedule a build immediately by providing a @@ -470,38 +489,6 @@ If hooks are allowed and a git repository includes a `pre-auto-gc` hook, the hoo + See link:https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks["Customizing Git - Git Hooks"] for more details about git repository hooks. -[[global-security-notify-commit-access-control]] -Notify Commit Access Control:: - -The NOTIFY_COMMIT_ACCESS_CONTROL setting allows you to control access to the notifyCommit URL. -This URL is used to trigger builds when changes are pushed to the repository. -By default, access to this URL is unrestricted, which means anyone who knows the URL can trigger a build. -+ -To enhance security, it is recommended to restrict access to the notifyCommit URL. -You can configure this setting to allow only authenticated users or specific IP addresses to trigger builds. -+ -To configure NOTIFY_COMMIT_ACCESS_CONTROL, navigate to the Configure Global Security page and locate the Git Plugin section. -From there, you can specify the access control rules that best fit your security requirements. -+ -You can set the NOTIFY_COMMIT_ACCESS_CONTROL value using the following methods: -+ - -.... -java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled -jar jenkins.war -.... - -+ -[#using-a-groovy-script-security-configuration] - Using a Groovy Script:: -+ -Alternatively, the property can be set using a Groovy script placed in the `init.groovy.d` directory. This method is useful for environments where you manage Jenkins settings through scripts: -+ - -[source,groovy] ----- -hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL = 'disabled' ----- - [#repository-browser] === Repository Browser From 633c7d3082248fb1850b07c9ab986695eded384d Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 18:50:07 -0600 Subject: [PATCH 4/9] Remove GitPod configuration --- .gitpod.yml | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 .gitpod.yml diff --git a/.gitpod.yml b/.gitpod.yml deleted file mode 100644 index 4efa528141..0000000000 --- a/.gitpod.yml +++ /dev/null @@ -1,10 +0,0 @@ -# This configuration file was automatically generated by Gitpod. -# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) -# and commit this file to your remote git repository to share the goodness with others. - -# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart - -tasks: - - init: mvn install -DskipTests=false - - From 878f1b198d20f222df06c7848d99926dd848318d Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 19:01:27 -0600 Subject: [PATCH 5/9] Use disabled-for-polling in examples Since `disabled` is not recommneded, let's use a little more favorable example to allow anonymous notifyCommit so long as the request only invokes polling. Include links that provide more information to describe system properties and Groovy post inititalization scripts. --- README.adoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.adoc b/README.adoc index 9d4e9a7bac..73147ac2b6 100644 --- a/README.adoc +++ b/README.adoc @@ -330,23 +330,24 @@ The `token` parameter is required by default as a security measure, but can be d hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL .... -You can set the NOTIFY_COMMIT_ACCESS_CONTROL value using the following methods: +You can set the NOTIFY_COMMIT_ACCESS_CONTROL value with either a link:https://www.jenkins.io/doc/book/managing/system-properties/[Java system property] or a link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/[Groovy hook script]. -[[using-Java-System-Property-push-notification-from-repository]] -Using Java System Property:: +[[using-a-java-system-property-push-notification]] +Using a Java system property:: .... -java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled -jar jenkins.war +java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-polling -jar jenkins.war .... -[#using-a-groovy-script-push-notification-from-repository] - Using a Groovy Script:: +[[using-a-groovy-script-push-notification]] + Using a Groovy script:: -The property can be set using a Groovy script placed in the `init.groovy.d` directory. This method is useful for environments where you manage Jenkins settings through scripts: +The property can be set using a Groovy script placed in the `init.groovy.d` directory. +This method is useful for environments where you manage Jenkins settings with link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/#post-initialization-script-init-hook[Groovy post-initialization scripts]. [source,groovy] ---- -hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL = 'disabled' +hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL='disabled-for-polling' ---- It has two modes: From c65a066555345ae3212647890d1f3c50b8924122 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 19:18:04 -0600 Subject: [PATCH 6/9] Add prefix text for system property Move mode descriptions before method description --- README.adoc | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.adoc b/README.adoc index 73147ac2b6..e245934e72 100644 --- a/README.adoc +++ b/README.adoc @@ -330,10 +330,20 @@ The `token` parameter is required by default as a security measure, but can be d hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL .... -You can set the NOTIFY_COMMIT_ACCESS_CONTROL value with either a link:https://www.jenkins.io/doc/book/managing/system-properties/[Java system property] or a link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/[Groovy hook script]. +It has two modes: + +* `disabled-for-polling` - Allows unauthenticated requests as long as they only request polling of the repository supplied in the `url` query parameter. Prohibits unauthenticated requests that attempt to schedule a build immediately by providing a +`sha1` query parameter. +* `disabled` - Fully disables the access token mechanism and allows all requests to `notifyCommit` +to be unauthenticated. *This option is insecure and is not recommended.* + +You can set the `NOTIFY_COMMIT_ACCESS_CONTROL` value with either a link:https://www.jenkins.io/doc/book/managing/system-properties/[system property] or a link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/[Groovy hook script]. + +[[using-a-system-property-push-notification]] +Using a system property:: -[[using-a-java-system-property-push-notification]] -Using a Java system property:: +The `NOTIFY_COMMIT_ACCESS_CONTROL` value can be set from the command line that starts Jenkins. +This method is useful for environments where initial Jenkins settings are managed with command line arguments. .... java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-polling -jar jenkins.war @@ -342,21 +352,14 @@ java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-po [[using-a-groovy-script-push-notification]] Using a Groovy script:: -The property can be set using a Groovy script placed in the `init.groovy.d` directory. -This method is useful for environments where you manage Jenkins settings with link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/#post-initialization-script-init-hook[Groovy post-initialization scripts]. +The `NOTIFY_COMMIT_ACCESS_CONTROL` value can be set using a Groovy script placed in the `init.groovy.d` subdirectory of the Jenkins home directory. +This method is useful for environments where Jenkins settings are managed with link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/#post-initialization-script-init-hook[Groovy post-initialization scripts]. [source,groovy] ---- hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL='disabled-for-polling' ---- -It has two modes: - -* `disabled-for-polling` - Allows unauthenticated requests as long as they only request polling of the repository supplied in the `url` query parameter. Prohibits unauthenticated requests that attempt to schedule a build immediately by providing a -`sha1` query parameter. -* `disabled` - Fully disables the access token mechanism and allows all requests to `notifyCommit` -to be unauthenticated. *This option is insecure and is not recommended.* - When notifyCommit is successful, the list of triggered projects is returned. [#enabling-jgit] From 435ca6d08805da768cae70629df9ce2903a1c3c3 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 19:21:20 -0600 Subject: [PATCH 7/9] Retain indentation for code fragment --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index e245934e72..42e50541c1 100644 --- a/README.adoc +++ b/README.adoc @@ -344,7 +344,7 @@ Using a system property:: The `NOTIFY_COMMIT_ACCESS_CONTROL` value can be set from the command line that starts Jenkins. This method is useful for environments where initial Jenkins settings are managed with command line arguments. - ++ .... java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-polling -jar jenkins.war .... @@ -354,7 +354,7 @@ java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-po The `NOTIFY_COMMIT_ACCESS_CONTROL` value can be set using a Groovy script placed in the `init.groovy.d` subdirectory of the Jenkins home directory. This method is useful for environments where Jenkins settings are managed with link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/#post-initialization-script-init-hook[Groovy post-initialization scripts]. - ++ [source,groovy] ---- hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL='disabled-for-polling' From 21d3b0e5692ce829bd643542821a0dce3a4cc4b0 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 19:23:11 -0600 Subject: [PATCH 8/9] Remove groovy specific formatting from example Looks better without it --- README.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/README.adoc b/README.adoc index 42e50541c1..4ff733561b 100644 --- a/README.adoc +++ b/README.adoc @@ -355,7 +355,6 @@ java -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-po The `NOTIFY_COMMIT_ACCESS_CONTROL` value can be set using a Groovy script placed in the `init.groovy.d` subdirectory of the Jenkins home directory. This method is useful for environments where Jenkins settings are managed with link:https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/#post-initialization-script-init-hook[Groovy post-initialization scripts]. + -[source,groovy] ---- hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL='disabled-for-polling' ---- From 3399e39e4ec4e9291c728544d7ecb4fd746b403e Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Tue, 20 Aug 2024 19:28:22 -0600 Subject: [PATCH 9/9] Move return value description earlier --- README.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 4ff733561b..8148abd908 100644 --- a/README.adoc +++ b/README.adoc @@ -324,6 +324,8 @@ If polling finds a change worthy of a build, a build will be triggered. This allows a notify script to remain the same for all Jenkins jobs. Or if you have multiple repositories under a single repository host application (such as Gitosis), you can share a single post-receive hook script with all the repositories. +When notifyCommit is successful, the list of triggered projects is returned. + The `token` parameter is required by default as a security measure, but can be disabled by the following link:https://www.jenkins.io/doc/book/managing/system-properties/[system property]: .... @@ -359,8 +361,6 @@ This method is useful for environments where Jenkins settings are managed with l hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL='disabled-for-polling' ---- -When notifyCommit is successful, the list of triggered projects is returned. - [#enabling-jgit] === Enabling JGit