Repository Permissions Updater

About

The Jenkins project hosts Maven artifacts such as core and plugin releases on Artifactory.

Its permissions system is independent of GitHub's, and we limit which users (identified by the Jenkins LDAP account, same as wiki and JIRA) are allowed to upload which artifacts.

This repository contains both the definitions for Artifactory upload permissions in YAML format, as well as the tool that synchronizes them to Artifactory.

Note: These permissions are specifically for uploading artifacts to the Jenkins project's Maven repository. It is independent of GitHub repository permissions. You may have one without the other. Typically, you'll either have both, or just the GitHub repository access.

Requesting Permissions

Prerequisite: You need to have logged in once to Artifactory and Jira with your Jenkins community account (this is the same as the account you would use to login to Jira) before you can be added to a permissions target.

To request upload permissions to an artifact (typically a plugin), file a PR editing the appropriate YAML file, and provide a reference that shows you have commit permissions, or have an existing committer to the plugin comment on your PR, approving it. See this page for more information.

Managing Permissions

The directory permissions/ contains a set of files, one per plugin or artifact, that define the permissions for the respective artifacts. Files typically have a component, plugin, or pom prefix for organization purposes:

• plugin is used for Jenkins plugins.
• pom is used for parent POMs and everything else consisting of just a POM file.
• component is used for everything else, usually libraries.

These prefixes, like the rest of the file name, have no semantic meaning and just help in organizing these files.

Each file contains the following in YAML format:

• A name (typically mirrored in the file name), this is also the artifactId of the Maven artifact.
• A github field indicating the GitHub organization and repository which is expected to produce these artifacts.
• A set of paths, usually just one. These correspond to the full Maven coordinates (groupId and artifactId) used for the artifact. Since Jenkins plugins can change group IDs and are still considered the same artifact, multiple entries are possible.
• Optional releaseBlocked flag. When set to true, artifact(s) described in this file cannot be pushed to Artifactory. This is only used in rare circumstances, e.g., by the Jenkins security team if plugin code contains unreleased security issues.
• A set of user names (Jenkins community user accounts in LDAP, the same as used for wiki and JIRA) allowed to upload this artifact to Artifactory. This set can be empty, which means nobody is currently allowed to upload the plugin in question (except Artifactory admins). This can happen for plugins that haven't seen releases in several years, or permission cleanups.

Example file:

---
name: "p4"
github: "jenkinsci/p4-plugin"
paths:
  - "org/jenkins-ci/plugins/p4"
developers:
  - "p4paul"

• p4 (lines 2 and 5): artifactId
• p4-plugin (line 3): GitHub repository name
• org/jenkins-ci/plugins (line 5): groupId (with slashes replacing periods)
• p4paul (line 7): Jenkins community account user name

Adding a new plugin

Create a new YAML file similar to existing files.

Adding a new uploader to an existing plugin

Edit the developers list in the YAML file for the plugin.

Remove uploaders from an existing plugin

Remove entries from the developers list.

Deprecating a plugin

See the documentation on jenkins.io. Do not delete YAML files from this repository.

Changing plugin ID

Jenkins cannot handle plugin renames, so if a release of the plugin has been published already, it's not possible to rename it. A plugin can theoretically be replaced by a new one with a different ID, but this is difficult to get right (e.g., when both plugins are installed at the same time).

If the plugin hasn't been released yet, you can just rename and edit the existing permissions file, changing the name component. You may also edit the github component, if you wish to rename the repository.

Changing a plugin's artifactId

Changing the paths or modifying the <artifactId> in the plugin pom.xml is highly discouraged.
Modifying the path will break any Maven dependencies from other plugins. Altering the artifactId means changing the identifier by which the Jenkins plugin manager differentiates one plugin from others, and will cause chaos for users who have already installed it under the old name.

Multiple plugins in single configuration file

If multiple closely related plugins are located in the same GitHub repository, have the same maintainer and the same issue tracker, they can use a single configuration file. To define multiple plugins in a single file, please do the following:

• Add an entry to paths that includes a * character, this path has to match the paths of all included plugins, but should not be too generic.
• Add a new property extraNames, it should contain the list of names of all the plugins managed by this configuration file other than the main plugin defined by name. All these names must start with the name of the main plugin, followed by -.

Managing Continuous Delivery (JEP-229 CD)

Jenkins plugins and other components can be continuously delivered through a supported process described in JEP-229.

You can enable JEP-229 CD for your component by adding the following to your component's YAML file:

cd:
  enabled: true

For this to work, there needs to be at least one developers listed. If the list of developers is empty or missing entirely (e.g., after the last maintainer steps down), no new releases can be published through JEP-229 CD.

IMPORTANT: When using JEP-229 CD, every committer to your repository can create new releases by merging pull requests. As a result, the list of maintainer accounts maintained in your plugin's YAML file is no longer the single reference on who can publish new releases. Be sure to check which users have commit access to your repository and remove any that are unexpected before enabling CD, as well as any unexpected deploy keys. Additionally, the users listed in this repository still serve as the contacts for security issues and plugin/component governance questions. For that reason, CD permissions are also only granted to components with at least one maintainer. In particular, the Jenkins security team will not make an effort to reach out to GitHub committers when maintainers (and security contacts, see below) are unresponsive before announcing vulnerabilities without a fix.

Exclusively using JEP-229 CD

By default, enabling JEP-229 CD enables it exclusively; i.e., the listed users will not be able to create new releases, but they remain contacts for security issues and plugin/component governance questions.

It is also possible to disable exclusive JEP-229 CD, in which case both users with commit access and the listed users will be able to create new releases, with the listed users remaining contacts for security issues and plugin/component governance questions:

cd:
  enabled: true
  exclusive: false

Managing Security Process

The Jenkins project acts as a primary contact point for security researchers seeking to report security vulnerabilities in Jenkins and Jenkins plugins (learn more).

We generally assign reported issues to maintainers after a basic sanity check (learn more). Through additional metadata in the YAML file described above, you can define who else should be contacted in the event of a report being received and is authorized to make decisions regarding security updates, e.g. scheduling. Add a section like the following to your plugin's YAML file:

security:
  contacts:
    jira: some_user_name

Given the above example, we will primarily assign any security issue in Jira to some_user_name. Regular maintainers are added to the issue as well to give visibility and allow participation/discussion. This means that specifying a Jira security contact is only useful when it's an account not already listed as maintainer. jira is optional.

If you represent a company with dedicated security team that needs to be involved, we recommend you to create a Jira account backed by an email address that the team can access, like a mailing list.

Managing Issue Trackers

The YAML metadata files in this repository also hold information about issue trackers. This is used to make issue trackers more accessible, e.g. by adding them to the UI of Jenkins or on https://plugins.jenkins.io.

Declaring Issue Trackers

The top-level issues key contains a sorted list of issue tracker references in descending order of preference.

For GitHub issues, a GitHub repository must be specified as the value for the github key, and the value must start with jenkinsci/, followed by the repository name. For Jira, a component name or ID must be specified as the value for the jira key. The component name is easier to read, while the component ID is resilient in case of component renames.

Either kind of issue tracker supports the report: boolean value that controls whether new issues should be reported in this issue tracker. The default is true.

A complete example with two trackers:

issues:
  - github: 'jenkinsci/configuration-as-code-plugin' # The preferred issue tracker
  - jira: '23170' # A secondary issue tracker is the Jira component id 23170 for 'configuration-as-code-plugin'
    report: false # No new issues should be reported here

Jira component id can be found at: https://issues.jenkins.io/rest/api/2/project/JENKINS/components

When GitHub Issues is used, there would be some duplicated content in the file (between github and issues entries) which can be resolved by using a YAML reference. Example:

github: &GH 'jenkinsci/configuration-as-code-plugin' # Declare a reference
issues:
  - github: *GH # Use the reference

Consuming Issue Trackers

A file issues.index.json is generated when the tool is executed, containing a map from component names to a list of issue trackers. Only plugins are expected to specify an issue tracker here.

If a plugin does not have a corresponding key in this map, the tool did not consider it for inclusion. If a plugin has a corresponding key in this map but an empty list of issue trackers, no issue trackers are known or supported.

Each issue tracker entry will have the following keys:

• type: Currently jira (meaning issues.jenkins.io) or github (meaning GitHub issues)
• reference contains a type-specific identifier string that provides additional information how issues are tracked; for Jira it is the component name or ID and for GitHub Issues it is the orgname/reponame String.
• viewUrl is a URL to a human-readable overview page. This value may not exist if no valid URL could be determined.
• reportUrl is a URL where users can report issues. This value may not exist if no valid URL could be determined, or new issues should not be reported in this tracker.

The list is sorted in descending order of preference. The first issue tracker in the list with a reportUrl should be presented as the primary (or only) option for reporting issues. Further issue trackers are mostly provided as a reference, e.g. when listing existing issues, although a different issue tracker with reportUrl can be linked if users provide a preference for a specific kind of issue tracker.

Usage

To see how to run this tool to synchronize Artifactory permission targets with the definitions in this repository, see Jenkinsfile.

The following Java system properties can be used to customize the tool's behavior:

• dryRun - Set to true to generate the API payloads without submitting them. No modifications will be executed.
• development - Set to true during tool development to ensure production data is not overridden. This will have the following effects:
  • Permissions are only granted to deploy to the snapshots repository (rather than both snapshots and releases)
  • A different, non-colliding set of prefixes (unless overridden, see below) is used.
• definitionsDir - Path to directory containing permission definitions YAML files, defaults to ./permissions.
• artifactoryUserNamesJsonListUrl - URL to a list containing known Artifactory user names, any permissions assigned to a user not on that list will cause the tool to abort
• artifactoryApiTempDir - Path to directory (that will be created) where this tool stores Artifactory permissions API JSON payloads, defaults to ./json.
• artifactoryObjectPrefix - Override the prefix for groups and permission targets managed (created, updated, removed) using the tool. If unspecified, the value will be generatedv2- by default, or generateddev- in development mode.
• artifactoryUrl - URL to Artifactory, defaults to https://repo.jenkins-ci.org
• artifactoryTokenMinutesValid - How long authentication tokens to Artifactory for CD enabled repos should be valid for, default 240 (4 hours). Regular script execution frequency needs to be aligned with this.
• gitHubSecretNamePrefix - Prefix for secrets sent to GitHub repos. If unspecified, the value will be MAVEN_ by default, or DEV_MAVEN_ in development mode.
• jiraUserNamesJsonListUrl - URL to a list containing known Jira user names of (potential) maintainers. This is essentially a workaround to reduce the number of individual user lookups via Jira API.

It expected the following environment variables to be set:

• ARTIFACTORY_USERNAME - Admin user name for Artifactory
• ARTIFACTORY_PASSWORD - Corresponding admin password (or API key) for Artifactory admin user
• GITHUB_USERNAME - GitHub user name for a user with admin access to any CD enabled repos
• GITHUB_TOKEN - Corresponding token for the user with admin access to any CD enabled repos, requires repo scope to create/update secrets
• JIRA_USERNAME - User name (does not need admin permissions) for Jira
• JIRA_PASSWORD - Corresponding password for Jira user

How It Works

The tool runs three steps in sequence:

1. Generate JSON payloads from YAML permission definition files.
2. Submit generated JSON payloads to Artifactory.
3. Remove all generated permission targets in Artifactory that have no corresponding generated JSON payload file.