Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-472

Add more 'best practices' details about credentials handling + external credentials providers to the Jenkins User Documentation


    • Type: Task
    • Status: To Do (View Workflow)
    • Priority: Minor
    • Resolution: Unresolved
    • Component/s: content
    • Labels:
    • Similar Issues:


      We need to ensure that the following best practices list has been captured in the Jenkins User Documentation pages:

      The best practices for managing credentials in relation to Pipeline are largely the same as for Jenkins in general:

      • Scope credentials appropriately - Use system credentials for secrets that are only used in the context of the Jenkins instance configuration (not by any specific Users, Folders, Jobs, or Pipelines). See attached 'system-scope.png' image. Don't confuse this with the System categorization for credentials, which are described here and relates to the System Credentials Provider - or global domain.
      • Use Domains to further limit the contexts in which credentials can be used. For more info, see:
      • (optional) Add credentials to specific Users, Folders, Jobs, or Pipelines that will need or use them and then use Project-based Matrix Authorization Strategy to restrict access to those items as appropriate.
        • Project-based Matrix Authorization Strategy is required for non-Pipeline-related items - e.g. folder and freestyle projects.
        • There is no difference with respect to configuring permission through Project-based Matrix Authorization Strategy or just Matrix Authorization Strategy for Pipeline projects.
      • Use meaningful Credential Id strings to make Jobs and Pipelines more readable and maintainable
      • (Non-Pipeline items like freestyle jobs or folders) Only expose/use credentials that are needed by that item - do not add credentials to an item that doesn't use them.
      • (Pipeline) Expose credentials only to stages or steps that need them - use "env { credentials () }" on individual stages instead of whole Pipelines. When using "withCredentials", wrap a few steps as possible.

      Also, scour the content on https://github.com/jenkinsci/credentials-plugin/blob/master/docs/user.adoc (which has information about external credential providers) and migrate any existing relevant content on this page to the appropriate areas of the User Handbook in the Jenkins User Documentation.



          There are no comments yet on this issue.


            • Assignee:
              ggaskell Giles Gaskell
            • Votes:
              0 Vote for this issue
              1 Start watching this issue


              • Created: