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.
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.
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:
pluginis used for Jenkins plugins.pomis used for parent POMs and everything else consisting of just a POM file.componentis 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 theartifactIdof the Maven artifact. - A
githubfield 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 (
groupIdandartifactId) 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):artifactIdp4-plugin(line 3): GitHub repository nameorg/jenkins-ci/plugins(line 5):groupId(with slashes replacing periods)p4paul(line 7): Jenkins community account user name
Create a new YAML file similar to existing files.
Edit the developers list in the YAML file for the plugin.
Remove entries from the developers list.
See the documentation on jenkins.io. Do not delete YAML files from this repository.
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 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.
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: trueFor 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.
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: falseThe 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_nameGiven 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.
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.
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: 'configuration-as-code-plugin' # A secondary issue tracker is the Jira component 'configuration-as-code-plugin'
report: false # No new issues should be reported hereWhen 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 referenceA 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: Currentlyjira(meaning issues.jenkins.io) orgithub(meaning GitHub issues)referencecontains atype-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 theorgname/reponameString.viewUrlis a URL to a human-readable overview page. This value may not exist if no valid URL could be determined.reportUrlis 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.
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 totrueto generate the API payloads without submitting them. No modifications will be executed.development- Set totrueduring tool development to ensure production data is not overridden. This will have the following effects:- Permissions are only granted to deploy to the
snapshotsrepository (rather than bothsnapshotsandreleases) - A different, non-colliding set of prefixes (unless overridden, see below) is used.
- Permissions are only granted to deploy to the
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 abortartifactoryApiTempDir- 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 begeneratedv2-by default, orgenerateddev-in development mode.artifactoryUrl- URL to Artifactory, defaults tohttps://repo.jenkins-ci.orgartifactoryTokenMinutesValid- How long authentication tokens to Artifactory for CD enabled repos should be valid for, default240(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 beMAVEN_by default, orDEV_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 ArtifactoryARTIFACTORY_PASSWORD- Corresponding admin password (or API key) for Artifactory admin userGITHUB_USERNAME- GitHub user name for a user with admin access to any CD enabled reposGITHUB_TOKEN- Corresponding token for the user with admin access to any CD enabled repos, requiresreposcope to create/update secretsJIRA_USERNAME- User name (does not need admin permissions) for JiraJIRA_PASSWORD- Corresponding password for Jira user
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.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent