Clarify limitations and backwards compatibility

Author: jeromepochat

docs/github-app.adoc

@@ -167,13 +167,34 @@ The following default permissions strategies are available:
 * **All permissions available to the app installation** (default)
     ** The access tokens generated in untrusted contexts will have the same permissions as the app installation in GitHub
 
-==== Repository access strategies and Pipeline libraries
+==== Repository access strategies limitations
+
+===== Jobs using plain Git
+
+The inference-based modes for GitHub App Credentials are supported for Organization Folders and Multibranch Pipelines only. There are not supported in other contexts using plain Git such as:
+* Pipeline script from SCM
+* Standalone Pipeline
+* Freestyle jobs
+
+===== Pipeline libraries
+
+Note that Pipeline libraries do not support inference, and will instead be inferred to have the same owner as the main SCM for the build itself. If the library's SCM is in a different repository than the build, you will not be able to use "Infer accessible repository" for the credentials used by the library.
+
+If the library's SCM is in a different GitHub organization than the SCM for the build, you will also not be able to use "Infer owner and allow access to all owned repositories". To avoid these issues, you can configure the Pipeline library to use a credential with the "Specify accessible repositories" mode that allows access to the repository that contains the library itself.
 
-Repository inference for GitHub App Credentials does not work when checking out Pipeline libraries.
-If you have a GitHub App Credential for an Organization Folder or Multibranch Pipeline whose individual Pipeline jobs access a Pipeline library, the contextually inferred repository for the library checkout will be the repository for the Pipeline job rather than the library.
 This means that the library will be inaccessible if you use an inference-based repository access strategy which only provides access to a single contextually-inferred repository, or if the Pipeline library is in a different GitHub organization than the repository being built.
+
 For now, in this case, you either need to use a less restrictive strategy for the GitHub App credential, such as "Infer owner and allow access to all owned repositories", or you can define a second credential specifically for the Pipeline library which uses "Specify accessible repositories" and only allows access to the repository for the Pipeline library.
 
+==== Backwards compatibility
+
+[IMPORTANT]
+The new configuration options are not fully backwards compatible.
+
+For existing GitHub App credentials which do not have the owner field set, the migration to the new format is not fully compatible. These credentials migrate to the “Infer owner and allow access to all owned repositories” mode described in the documentation, which means that they will only work in contexts where the owner can be inferred, such as Organization Folders and Multibranch Pipelines.
+
+If you are using the credentials in a context where inference is not supported, you will need to reconfigure these credentials to use the “Specify accessible repositories” mode instead, specifying the appropriate owner (or leaving it blank if the app is installed in a single GitHub organization).
+
 === Help?
 
 Raise an issue on link:https://issues.jenkins-ci.org/[Jenkins jira]