// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[centralized-repository-declaration]]
= Centralizing Repository Declarations

Instead of declaring repositories in every subproject of your build or via an `allprojects` block, Gradle provides a way to declare them centrally for all projects.

NOTE: Central declaration of repositories is an incubating feature.

You can declare repositories that will be used by convention in every subproject in the `settings.gradle(.kts)` file:

====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=declare_repositories_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=declare_repositories_settings]"]
====

The `dependencyResolutionManagement` repositories block accepts the same notations as in a project, including Maven or Ivy repositories, with or without credentials.

[[sec:repositories-mode]]
== Repositories mode

By default, repositories declared in a project’s `build.gradle(.kts)` file will override those declared in `settings.gradle(.kts)`.
However, you can control this behavior using the `repositoriesMode` setting:

====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=prefer_projects]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=prefer_projects]"]
====

[[sec:available-modes]
== Available modes

There are three modes for dependency resolution management:

[cols="1,1,1,1"]
|===
|Mode |Description |Default? |Use-Case

|`PREFER_PROJECT`
|Repositories declared in a project override those declared in `settings.gradle(.kts)`.
|Yes
|Useful when teams need to use different repositories specific to their subprojects.

|`PREFER_SETTINGS`
|Repositories declared in `settings.gradle(.kts)` override those declared in a project.
|No
|Useful for enforcing the use of approved repositories across large teams.

|`FAIL_ON_PROJECT_REPOS`
|Declaring a repository in a project triggers a build error.
|No
|Strictly enforces the use of repositories declared in `settings.gradle(.kts)`.
|===

You can change the behavior to prefer the repositories in `settings.gradle(.kts)`:

====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=prefer_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=prefer_settings]"]
====

[[sec:fail-build-on-project-repositories]]
Gradle will warn you if a project or plugin declares a repository when using this mode.

To enforce that *only* repositories declared in `settings.gradle(.kts)` are used, you can configure Gradle to fail the build when a project plugin is declared:

====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=enforce_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=enforce_settings]"]
====
