{"id":18482622,"url":"https://github.com/jenkins-infra/update-center2","last_synced_at":"2025-05-15T17:06:02.717Z","repository":{"id":1265103,"uuid":"1204101","full_name":"jenkins-infra/update-center2","owner":"jenkins-infra","description":"Jenkins Update Center backend","archived":false,"fork":false,"pushed_at":"2025-04-25T09:34:01.000Z","size":2357,"stargazers_count":135,"open_issues_count":4,"forks_count":270,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-25T10:42:42.298Z","etag":null,"topics":["java","jenkins","jenkins-infra","update-center"],"latest_commit_sha":null,"homepage":"https://updates.jenkins.io","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkins-infra.png","metadata":{"funding":{"community_bridge":"jenkins","custom":["https://jenkins.io/donate/#why-donate"]},"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-12-28T21:28:58.000Z","updated_at":"2025-04-25T09:34:05.000Z","dependencies_parsed_at":"2024-01-23T11:25:50.838Z","dependency_job_id":"a586ebaa-add5-4d39-9afa-e245f83409d4","html_url":"https://github.com/jenkins-infra/update-center2","commit_stats":{"total_commits":1389,"total_committers":177,"mean_commits":"7.8474576271186445","dds":0.5550755939524838,"last_synced_commit":"a15188d634d2c10bc6f88127a2f6b21a19ada71a"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkins-infra%2Fupdate-center2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkins-infra%2Fupdate-center2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkins-infra%2Fupdate-center2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkins-infra%2Fupdate-center2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkins-infra","download_url":"https://codeload.github.com/jenkins-infra/update-center2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","jenkins","jenkins-infra","update-center"],"created_at":"2024-11-06T12:29:23.048Z","updated_at":"2025-05-15T17:05:57.709Z","avatar_url":"https://github.com/jenkins-infra.png","language":"Java","funding_links":["https://funding.communitybridge.org/projects/jenkins","https://jenkins.io/donate/#why-donate"],"categories":[],"sub_categories":[],"readme":"= Jenkins Update Center Generator\n\nThis project is primarily used to generate the jenkins.io update center layout.\n\nWith a few modifications it could easily be used to generate your corporate update center as well.\n\n[IMPORTANT]\nThis tool is optimized for use by the Jenkins project in Jenkins project infrastructure.\nExpect incompatible changes, like options not used by the Jenkins project being dropped.\nAdditionally, this documentation is focused on how the tool is used by the Jenkins project, rather than the customizations necessary to create private update sites.\n\n== Output\n\nSee link:site/LAYOUT.md[site layout] for more detailed documentation on site structure.\n\n\n== Information Sources\n\nThe generator pulls information from:\n\n* Artifactory artifact repository (see `ArtifactoryRepositoryImpl.java`)\n  - Artifactory API for listing artifacts\n  - downloading artifact files\n  - downloading individual files in archives such as `MANIFEST.MF`\n* GitHub (see `GitHubSource.java`)\n  - determine source code repository that actually exists (sometimes metadata is wrong)\n  - plugin labels from repositories topics\n  - default branch name\n* Jenkins usage statistics (see `Popularities.java`)\n  - latest plugin installation numbers for `popularity` entries in update center JSON\n* Various metadata JSON files on `reports.jenkins.io`\n  - Plugin issue tracker metadata JSON file, see `IssueTrackerSource.java`\n  - Plugin maintainer mapping JSON file, see `MaintainersSource.java`\n  - Maintainer info JSON file, see `MaintainersSource.java`\n* link:resources/[Local resource files in this repository]\n  - GitHub topic allowlist (`resources/allowed-github-topics.properties`)\n  - Standalone deprecations (`resources/deprecations.properties`)\n  - Artifact ignore list (with deprecation URLs) (`resources/artifact-ignores.properties`)\n  - Label assignments (`resources/label-definitions.properties`)\n  - Security warnings (`resources/warnings.json`)\n  - Plugin URL overrides (`resources/wiki-overrides.properties`)\n\n\n== Features Controlled Through Resource Files\n\n=== Categorizing plugins\n\nPlugin labels are shown to users:\n\n* as categories in Jenkins before 2.224 and on the link:https://plugins.jenkins.io/[plugins site]\n* as tags in Jenkins from 2.224 and also on the plugins site.\n\nSee https://github.com/jenkinsci/jenkins/blob/master/core/src/main/resources/hudson/model/Messages.properties[this Jenkins resource file] (look for `UpdateCenter.PluginCategory`) for the localization overrides applied to labels by Jenkins.\nOther labels are categorized into general _Misc (custom-label-here)_ categories (Jenkins before 2.224) or displayed as is.\n\nTwo ways can be used to define these labels:\n\n==== GitHub\n\nAdd https://help.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics[topics] to your GitHub repository.\nFor a list of supported topics, see the link:resources/allowed-github-topics.properties[resource file] that contains all topics that can be set on GitHub repositories that will be reflected in update sites.\nTopics can be set with or without the prefix `jenkins-`. If a topics has that prefix, it is removed first:\nTo add the label `matrix` for your plugin, you would add either `matrix` or `jenkins-matrix` on your repository. \n\n==== Resource File\n\nAs an alternative to the above, plugin labels can be defined in the file https://github.com/jenkins-infra/update-center2/blob/master/resources/label-definitions.properties[`resources/label-definitions.properties`] in this repository.\n\nThis is the preferable approach when a plugin isn't in the `jenkinsci` GitHub organization, or a GitHub repository contains multiple plugins whose labels should be different.\n\n=== Plugin URL Override\n\nPlugins are generally expected to provide a `\u003curl\u003e` to their documentation in their POM.\nHistorically, these URLs have been pages on the Jenkins wiki, but can point anywhere.\n\nThis requirement no longer exists, but it may still be useful to define a documentation URL for plugins that do not specify the correct URL.\n\nThe file `resources/wiki-overrides.properties` defines these wiki page overrides.\n\nAny entries in this file are expected to be temporary, i.e. plugin maintainers are expected to fix their plugin's metadata.\n\n\n=== Deprecations\n\nPlugins are considered _deprecated_ by Jenkins 2.246 and newer when the update site metadata does one or both of the following:\n\n* Uses the label `deprecated` for the plugin.\n  This can be done via GitHub repository topics, or the `resources/label-definitions.properties` described above.\n  Jenkins will use the plugin URL as the reference URL for the deprecation notice.\n* Lists an entry with the plugin ID as key in the top-level `deprecations` map in `update-center.json`.\n  This can be done through entries in the\n  https://github.com/jenkins-infra/update-center2/blob/master/resources/deprecations.properties[`resources/deprecations.properties`]\n  file (for plugins that continue being distributed) or in\n  https://github.com/jenkins-infra/update-center2/blob/master/resources/artifact-ignores.properties[`resources/artifact-ignores.properties`]\n  for plugins that are suspended.\n  The value from the properties file will be used as the URL for the deprecation notice in Jenkins.\n  This entry and URL take precedence over a `deprecated` label, i.e. when both are set, the URL from the top-level element shall be used.\n\nThese two different approaches to plugin deprecation accomplish complementary goals:\n\n* The label approach is very simple and can easily be done by plugin maintainers themselves via GitHub labels.\n  It is also backward compatible with any earlier version of Jenkins -- it will just show the deprecation as a regular label.\n  Additionally, it doesn't bloat the JSON file size at all, since no special URL is needed.\n* The top-level `deprecations` element allows specifying a URL different from the plugin documentation URL as well as deprecating plugins no longer being distributed.\n  Especially the latter is a common requirement when plugins integrate with services that no longer exist:\n  It makes no sense to continue distributing them, but everyone having them already installed should be informed about it.\n\n\n=== Removing plugins from distribution\n\nThe update center generator allows to specify that certain plugins, or plugin releases, should not be included in the output.\n\nThere are various reasons to need to do this, such as:\n\n* A plugin release causes major regressions and a fix is not immediately available.\n* A plugin integrates with a service that has been shut down.\n\nBoth use cases (entire plugins, or specific versions) are controlled via the file `resources/artifact-ignores.properties`.\nThat file may also define URL of a deprecation notice that is shown to users who already installed the plugin.\nSee that file for usage examples.\n\n=== Security warnings\n\nSince Jenkins 2.32.2 and 2.40, Jenkins can display security warnings about core and plugins.\nThese warnings are part of the update center metadata downloaded by Jenkins.\nThese warnings are defined in the file `resources/warnings.json`.\n\n\n== Usage\n\n=== Invocation\n\nBuild (`mvn clean verify`) the generator and then invoke it as follows:\n\n    java -Dfile.encoding=UTF-8 -jar target/update-center2-*-SNAPSHOT-bin/update-center2-*-SNAPSHOT.jar --id default ...\n\nThe tool also supports batch mode execution, generating multiple update sites with a single invocation:\n\n    java -Dfile.encoding=UTF-8 -jar target/update-center2-*-SNAPSHOT-bin/update-center2-*-SNAPSHOT.jar --arguments-file \u003cfilename.txt\u003e\n\n`filename.txt` is a text file with a list of arguments on each line.\nLines that start with `#` are comments and ignored.\nExample:\n\n[source]\n----\n# one update site per line\n\n# Minimal update sites for Jenkins \u003c= 2.204 and 2.204.x LTS\n--www-dir ./www2/2.204 --limit-plugin-core-dependency 2.204.999 --write-latest-core\n--www-dir ./www2/stable-2.204 --limit-plugin-core-dependency 2.204.999 --write-latest-core --only-stable-core\n\n# Minimal update sites for Jenkins \u003c= 2.222 and 2.222.x LTS\n--www-dir ./www2/2.222 --limit-plugin-core-dependency 2.222.999 --write-latest-core\n--www-dir ./www2/stable-2.222 --limit-plugin-core-dependency 2.222.999 --write-latest-core --only-stable-core\n\n# Experimental (alpha/beta) update site, no version caps, collect files for download (including experimental files)\n--www-dir ./www2/experimental --with-experimental --downloads-directory ./download\n\n# Latest update site for Jenkins \u003e 2.222, with release-history.json, plugin-versions.json, plugin-documentation-urls.json, collect files for download, and generate plugin count\n--generate-release-history --generate-plugin-versions --generate-plugin-documentation-urls --write-latest-core --write-plugin-count --www-dir ./www2/current --download-links-directory ./www2/download --downloads-directory ./download --latest-links-directory ./www2/current/latest\n----\n\nFor a full list of arguments, invoke the tool as follows:\n\n    java -Dfile.encoding=UTF-8 -jar target/update-center2-*-SNAPSHOT-bin/update-center2-*-SNAPSHOT.jar --help\n\nNOTE: `--help` isn't a real argument, but usage instructions are printed when an invalid argument is provided.\n\n\n=== Preparing local execution\n\nRunning `./site/generate.sh` will first create the batch mode control file `./tmp/args.lst`, before actually starting the tool.\nThe following steps are therefore useful when trying to generate output corresponding to the real update sites during development:\n\n1. Implement changes in `src/main/`.\n2. Run `./site/generate.sh` until the Java tool is actually launched, then abort. This requires some environment variables to be defined.\n3. Edit `tmp/args.lst`, changing or removing the `--key`, `--certificate`, and `--root-certificate` arguments as necessary.\n4. Run `+java -Dfile.encoding=UTF-8 -jar target/update-center2-*-SNAPSHOT-bin/update-center2-*-SNAPSHOT.jar --arguments-file tmp/args.lst+`\n\nAlternatively, the closest you can get to real executions in local development:\n\n1. Implement changes in `src/main/`.\n2. Deploy a snapshot using `mvn deploy`. Requires an account in the Jenkins project, see _Deploying changes_ below.\n3. Edit `site/generate.sh` to reference the specific snapshot you deployed (including timestamp) where it is downloaded using `wget`, see previous build output.\n4. Optionally, to speed things up, edit `site/generate.sh` and remove the arguments `--downloads-directory \"$DOWNLOAD_ROOT_DIR\"` from some of the invocations.\n5. Run `./site/generate.sh \u003cwww-dir\u003e \u003cdownloads-dir\u003e`. The first argument is the output directory for metadata, the second argument is the output directory for downloads and unused unless the previous step 4 was skipped.\n\n=== Running within an IDE\n\nThe project various artifacts to be used on a site hosting a jenkins update center\nThe project produces a jar and a zip file containing all the required dependencies to run the generator.\n\nIf you want to run the generator from within your development environment,\nyou can try to use the appassembler plugin as described below.\nThe exec:java plugin won't work.\n\n    mvn package appassembler:assemble\n    sh target/appassembler/bin/app --id default ...\n\n\n=== Deploying changes\n\n`./site/generate.sh` downloads and executes a specified version of `update-center2`.\nThis is different from earlier iterations of this tool that always rebuilt from source.\nThe current iteration requires a (possible snapshot deployment) first, that is then referenced in `./site.generate.sh`.\n\nConsequently, merging larger-scale changes to both the tool itself and the wrapper script need to be mindful of this dependency:\nA new release (or at minimum a snapshot deployment) is needed, which is then referenced in `./site/generate.sh`.\n\nNOTE: As of May 2020, everyone can deploy snapshots to Artifactory, so permissions issues shouldn't hinder development.\n\n\n=== Working with htaccess/mod_rewrite rules\n\nThe wrapper script `site/generate.sh` calls the script `site/generate-htaccess.sh` with chosen arguments.\nThe latter script will generate the `.htaccess` file mostly containing mod_rewrite rules to redirect requests to appropriate tiered update sites.\nTo learn more about tiers, see link:site/LAYOUT.md[LAYOUT.md].\n\nTo test changes to `site/generate-htaccess.sh`, run `site/test/test.sh`.\nIt executes `site/generate-htaccess.sh` and places it inside an Apache HTTPD Docker container and tests whether redirect rules are correctly applied.\n\n\n=== Working with certificates\n\nTo sign JSON output files, create a development certificate:\n\n----\nopenssl genrsa -out resources/certificates/demo.key 4096\nopenssl req -new -x509 -days 180 -key resources/certificates/demo.key -out resources/certificates/demo.crt -subj \"/C=/ST=/L=/O=local-development/OU=local-development/CN=local-development/emailAddress=example@example.invalid\"\n----\n\nThen add these arguments to your tool invocation (or arguments file):\n\n----\n--key resources/certificates/demo.key --certificate resources/certificates/demo.crt --root-certificate resources/certificates/demo.crt\n----\n\nTo have your Jenkins instance accept update site JSON signed with this certificate, create a directory `update-center-rootCAs/` in the Jenkins home directory, and copy the `demo.crt` file in there.\nOnce update site JSON files are generated, configure Jenkins to download them in _Manage Jenkins » Manage Plugin » Advanced_:\nEither set up a local HTTP server so the URL would be something like `+http://localhost:8000/update-center.json+`, or specify a `file://` URL like `+file:///Users/yourname/git/update-center2/www2/update-center.json+`\n\nNOTE: For historical reason, the configured URL points to `update-center.json`, but the file actually downloaded by Jenkins (at least up to 2.235 as of this writing) is `update-center.json.html`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkins-infra%2Fupdate-center2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkins-infra%2Fupdate-center2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkins-infra%2Fupdate-center2/lists"}