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 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 theartifactId
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
andartifactId
) used for the artifact. Since Jenkins plugins can change group IDs and are still considered the same artifact, multiple entries are possible. - 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 nameorg/jenkins-ci
(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.
Deprecating a plugin
Remove the YAML file. The next synchronization will remove permissions for the plugin.
Renaming a plugin
Rename and edit the existing permissions file, changing both name
and the last path
component.
groupId
Changing a plugin's Change the paths
to match the new Maven coordinates, or, if further uploads for the old coordinates are expected, add a new list entry.
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).
Through additional metadata in the YAML file described above, you can define who should be contacted in the event of a report being received. Add a section like the following to your plugin's YAML file:
security:
contacts:
jira: some_user_name
email: security@acme.org
Given the above example, we will assign any security issue in Jira to some_user_name
rather than one of the developers able to release the plugin, and send an email notification to security@acme.org
to establish contact.
Either of jira
and email
are optional.
Please note that we generally reject email contacts due to the additional overhead in reaching out via email. Unless you represent a large organization with dedicated security team that needs to be involved in the coordination of a release, please refrain from requesting to be contacted via email.
Usage
To see how to run this tool to synchronize Artifactory permission targets with the definitions in this repository, see Jenkinsfile
.
It expects the following System properties to be set:
definitionsDir
- Path to directory containing permission definitions YAML filesartifactoryApiTempDir
- Path to directory (that will be created) where this tool stores Artifactory permissions API JSON payloads.
It expected the following environment variables to be set:
ARTIFACTORY_USERNAME
- Admin user name for ArtifactoryARTIFACTORY_PASSWORD
- Corresponding admin password (or API key) for Artifactory admin user
How It Works
The tool runs three steps in sequence:
- Generate JSON payloads from YAML permission definition files.
- Submit generated JSON payloads to Artifactory.
- Remove all generated permission targets in Artifactory that have no corresponding generated JSON payload file.