Why GitLab integration defaults decide how consistent your instance is
Administrators who connect a self-managed GitLab instance to issue trackers, chat, secrets managers or CI systems face a choice early on: configure every project by hand, or set the integration once at the top and let projects inherit it. Instance and group integration settings are the mechanism for the second approach. On GitLab Self-Managed, an integration can be configured at instance level and again at group level, and each project can either use those defaults or carry its own custom settings. When an organization has dozens or hundreds of projects, this is the difference between a consistent setup and a patchwork that nobody can fully describe.
The precedence rules are the part to plan around. Group settings override instance settings, so a group that needs a different chat channel or tracker URL can set its own value without changing the rest of the instance. Projects then sit beneath the group, using either the inherited default or a custom configuration. Before rollout, map which groups own which projects, decide which integrations are instance-wide by policy, and record which groups are allowed to diverge. Confirm the current inheritance behavior for each integration type in the GitLab integrations documentation, because individual integrations expose different fields and not every one follows the same pattern.
Administrators also need the integration allowlist. It lets an instance administrator restrict which integrations can be enabled at all, so that a project owner cannot connect an unapproved external service and send source code metadata or pipeline data to it. This is a control decision, not only a convenience: list the integrations your security and data-handling reviews have approved, and test that a project owner outside those approvals cannot enable anything else. Teams that need this typically run GitLab for regulated or internal-only work, or have several business units sharing one instance. Confirm the allowlist behavior on your installed version, since the settings page and its options are the source of truth for your environment.
Which integration setting level fits each situation
This table compares the five controls that decide where an integration is configured: instance defaults, group settings, project inheritance, project custom settings and the allowlist. Read each row for who sets it, when it fits and the main risk, then confirm exact field names in your GitLab version before you write the standard.
| Level | What it controls, who sets it and when it fits | Main risk |
|---|---|---|
| Instance-level defaults | Integration values that apply across the self-managed instance. Set by an administrator. Fits shared services such as one chat workspace or one secrets manager used by all teams. | A wrong value propagates to every group and project that inherits it, and the change reaches many teams at once. |
| Group-level settings | Defaults for the projects in one group, which override instance settings for that group. Set by group owners. Fits teams with different tools, such as a regulated business unit using its own issue tracker. | Group owners can diverge from the standard, so drift builds up unless groups are reviewed periodically. |
| Project inheritance | Projects use the instance or group default rather than their own values. Set by the project's maintainers through the integration choice. Fits most projects, because one change updates all of them. | Maintainers may assume inherited values are correct without checking which level supplies them. |
| Project custom settings | Values entered directly on one project, which replace inherited defaults for that project only. Set by project maintainers. Fits a project with a documented exception, such as a different endpoint or notification channel. | Custom values are invisible at group or instance review and often hold credentials or endpoints that nobody rotates. |
| Integration allowlist | Administrator restriction on which integrations users may enable at all. Set by an instance administrator. Fits organizations that must limit outbound connections and third-party data flows. | If the list is too narrow, teams work around it with unmanaged tools; if it is never reviewed, new integrations stay open. |
| Required settings check | Whether the administrator can require a single configuration across groups and projects. Confirm in your version whether this exists and which integrations it covers. | Assuming enforcement exists when only defaults are set, so teams believe a control is in place when it is not. |
How to set integration defaults in the right order
This sequence sets approved integrations once at the instance level, then layers group settings and project inheritance on top, so every project inherits the same controlled defaults and blocked integrations stay blocked.
Agree the list of approved integrations
Before touching the instance, the platform owner and security lead agree which integrations the organization permits, such as the issue tracker, secrets manager, chat tool and Kubernetes connection. Record each approved integration with its owner and the data it may receive. Done means the list is signed off by the people who will be asked to support it, and any integration left off the list has a stated reason.
Define the integration allowlist first
An administrator restricts the available integrations in the instance settings so that only the approved items can be enabled anywhere on the instance. Set the allowlist before configuring any defaults, so that no group or project can add an unapproved tool while the defaults are being built. Check the result by logging in as a non-administrator with project maintainer rights, opening the integrations page of a test project, and confirming that a blocked integration cannot be enabled.
Configure instance defaults for shared services
Once the allowlist is in place, the administrator sets instance-level integration defaults for services every team uses, such as the company chat workspace or the shared secrets manager. Credentials and endpoints should be entered by the person who owns that service, and secrets should be stored only in the places GitLab documents for them. Done means each shared integration shows as configured at instance level, and the credential holder has confirmed the endpoint responds from the GitLab host.
Set group settings for teams with different tools
Group owners configure settings where a team uses a tool that differs from the instance default, for example a different issue tracker or a separate chat channel. Group settings override instance settings for the projects in that group, so the group owner should confirm that the override is intentional and documented. Done means each group that differs from the instance shows its own configured value, and the group owner can name the reason for the difference.
Verify inheritance on a sample project
Create or pick a test project in each group that has different settings and open its integrations page. Confirm that projects using the instance or group default show the inherited value, and that a project with a custom setting shows its own configuration. Done means the inherited values match what was configured at each level, and a short record of the test results is kept with the change request.
Re-test the allowlist after each change
Repeat the blocked-integration test from a non-administrator account whenever the allowlist or a group setting changes, because a new integration added later can otherwise reach projects unnoticed. Done means a blocked integration still cannot be enabled in a test project, and any newly approved integration appears in the allowlist before it is used.
Document the defaults and their owners
Write down the approved list, the instance defaults, each group override and the owner of every credential, and store the record where administrators and group owners can find it. Confirm the record matches the live settings by comparing it with a fresh review of the instance and group integration pages. Done means someone outside the original team could follow the record to find every setting and its owner.
How inheritance works across instance, group and project
When one team owns the whole instance, the simplest model is to set integration defaults at the instance level and let projects inherit them. Administrators configure each integration once, decide which projects should use the instance default, and keep the number of exceptions small. Because there is only one set of owners, the main risk is not conflicting settings but settings that were enabled once and never reviewed.
- Instance holds the default: Configure shared integrations such as issue tracker or chat notifications at the instance level so new projects start with the same behavior.
- Projects inherit by default: Projects using the instance setting follow later changes automatically, so one edit updates every inheriting project.
- Exceptions stay visible: Track projects that use custom settings in a short list, since these are the ones that stop following the default.
- Credentials need an owner: Integration secrets entered at the instance level should be tied to a named service account or team, not a personal account that may leave.
- Drift appears in old projects: Projects created before a default changed may carry stale custom settings that nobody revisits.
Before relying on inheritance, confirm in your own instance which integrations appear at the instance level and which must still be set per project.
When several groups use different tools, such as one group on Jira and another on a different tracker, the instance default is often too broad. Group settings sit between the instance and the project. Group settings override instance settings for projects in that group, which lets each group keep its own defaults while the instance still sets the outer boundary.
- Group holds the team default: Each group that uses a different tool sets its integration at group level, so its projects inherit that choice instead of the instance one.
- Instance sets the boundary: The instance-level allowlist decides which integrations any group may enable, so group choices cannot go outside approved tools.
- Subgroups add another layer: Nested groups inherit from their parent group unless they set their own values, so check the chain when a subgroup behaves unexpectedly.
- Drift follows reorganizations: Moving a project or renaming a group can change which default applies, so review inheritance after structural changes.
- Shared services create confusion: When two groups send alerts to the same channel, duplicated or missing notifications often trace back to group-level settings that differ.
Confirm the current group and subgroup inheritance behavior in the integrations documentation for your GitLab version before writing a standard.
Some projects need settings that differ from their group, such as a release project that posts to a restricted channel or a regulated repository that must not send data to an external tool. A project can use the instance or group default, or define custom settings. Custom settings take precedence for that project only, and they stop receiving later default changes.
- Custom means detached: A project with its own settings no longer follows changes made at the group or instance level, which is the intended behavior but easy to forget.
- Record the reason: Note why each override exists in the project description or a central register so future administrators do not remove it by mistake.
- Limit who can override: Decide which roles may enable custom integrations, and keep sensitive integrations at group or instance level where they are reviewed centrally.
- Check allowlist conflicts: A custom setting cannot use an integration blocked by the allowlist, so an override that worked before may fail after a policy change.
- Audit periodically: Compare project settings against the group default on a schedule, since overrides accumulate quietly over time.
Before rolling out the model, ask your GitLab administrators which override actions are visible in audit events for your edition and tier.
Decisions to make before you restrict integrations
Restricting integrations is a governance change as much as a configuration change. The decisions below determine what the allowlist permits, who maintains it, and how existing projects and group owners are brought along without surprises.
Approved integrations by data classification
Decide which integrations may be enabled for each class of data your organization handles. An integration that sends pipeline metadata, issue titles or commit messages to an outside service may be acceptable for internal tooling but not for projects with regulated or customer data. Map each candidate integration to the data it reads and writes, then record the classification it is approved for. Confirm the data flows with the integration's documentation before adding it to the allowlist.
Ownership of the allowlist
Name who can add, remove or change entries on the integration allowlist, and who approves those changes. If group owners can edit it indirectly through their own settings, the allowlist stops being a control. Decide whether changes go through a ticket, a change record or a review by security, and write down the approval path so audit evidence exists for each change.
Existing integrations before restriction
Inventory integrations already enabled at instance, group and project level before tightening the allowlist. Restricting the list can disable or block integrations that pipelines and teams rely on, such as notifications or deployment triggers. Decide for each one whether to keep it, replace it, or move it to an approved alternative, and set a date for the change. Check each project for custom settings that will not follow an instance-level change.
Communicating changes to group owners
Group owners and project maintainers need to know which integrations are no longer available, why, and what replaces them. Decide who sends the notice, through which channel, and how far in advance it goes out. Include a named contact for exceptions and the process for requesting one. Without this, teams discover restrictions when a pipeline or integration fails.
Reviewing the list after upgrades
Schedule a review of the allowlist after each GitLab upgrade. Upgrades can add, rename or change the behavior of integrations, and new integrations may appear that are not on your list. Compare the available integrations against your approved set at each upgrade, and confirm the upgrade notes for any changes to integration settings. Pair this review with your existing upgrade stop planning so it happens as part of the same change window.
External trackers and chat tools
Issue trackers and chat tools receive event data from GitLab, so each one extends where project information can travel. Decide whether an external tracker or chat workspace is approved for the data in the projects it will connect to, and who can host it. Confirm where that tool stores messages and whether it is inside your infrastructure. Treat each one as a separate data destination in the classification review.
Security risks when integration defaults are set too loosely
Instance and group integration defaults are inherited by every project beneath them, so a weak setting made once can spread quietly. The cards below cover the places where that inheritance creates exposure: stored credentials, who can read or change them, what data leaves the instance, how changes are recorded, and what happens when group ownership changes.
Credentials stored in integration settings
Many integrations ask for a token, webhook secret or API key that GitLab stores in its database as part of the integration configuration. A credential entered once at the instance or group level can then be used by every inheriting project. Before go-live, confirm with your GitLab version's documentation how each integration stores and masks these values, and whether the credential is one with the narrowest scope the external system allows. Rotate credentials on a schedule you control, and record who owns each one.
Who can view or change secrets
Access to an integration setting is governed by the role a person holds at the level where the setting lives. An instance administrator, a group owner or a project maintainer may each be able to open an integration form that holds a secret. Map each level to the people who actually hold it, and check whether a project maintainer can override an inherited group integration with their own credential. Overrides at lower levels are where unexpected secrets tend to appear.
Data sent to external systems by default
An enabled integration sends event data to an outside service, which can include commit messages, branch names, merge request titles, pipeline results and user names. When an integration is set at group or instance level, that flow starts for every project that inherits it, including projects that hold sensitive or regulated code. List each enabled integration, the event types it sends and the destination's hosting location, and decide whether an external endpoint is acceptable for each project class.
Limiting which integrations can be enabled
An allowlist controls which integrations administrators and group owners may turn on. Without one, any integration offered by the product can be configured against any project, including ones that send data to tools your security team has not reviewed. Build the allowlist from your approved tool register, and confirm in your version's administration documentation how entries are added and how existing integrations are treated when an entry is removed.
Audit visibility of configuration changes
A change to an instance or group integration can alter where data flows for many projects in a single edit. Check whether your GitLab version records who changed an integration, when, and which setting moved, and whether those records reach your central log store. If the record is incomplete for your version, plan a periodic export of integration settings and compare it against an approved baseline. Ask your GitLab representative or confirm in the audit event documentation before relying on it as evidence.
Review after group ownership changes
When a group is transferred, reorganized or handed to a new owner, the integrations it provides keep running under settings chosen by the previous owner. Credentials may belong to someone who has left, and endpoints may no longer match current policy. Include integration settings in every ownership handover checklist, and confirm which user account owns each credential so it can be rotated when that person's access ends.
Keeping integration settings consistent after upgrades and team changes
Integration defaults set once at the instance level stay useful only if someone reviews them after every upgrade and every change of team ownership. Plan that review as recurring work with a named owner, not as a one-time setup task. Start by tying it to your upgrade calendar. GitLab requires upgrades to pass through required upgrade stops, and the GitLab upgrade paths documentation lists them. Each time you move to a stop, check the integration allowlist, the instance-level defaults for each integration you use, and whether any integration that was enabled before the upgrade still connects and sends data. Record the result next to the upgrade ticket so the evidence exists when an auditor or a new administrator asks.
Give each group a written record of which integration settings it owns. Group settings override instance settings, so a group that changes a default silently changes what its projects inherit from the instance, and project-level overrides can hide the same change further down. Keep a simple register that lists each instance default, each group that sets its own value, and the person accountable for that value. When a group is onboarded, add it to the register, confirm which instance defaults it inherits, and decide with the instance administrator which integrations it may enable under the allowlist. Review the register when administrators or group owners leave, because orphaned settings are the most common reason integrations keep running after nobody can explain them.
Test every integration change in a non-production GitLab instance before it reaches the production instance. Use the same version as production, including after an upgrade stop, and replay the settings you plan to change, such as an allowlist entry or a new group default. Confirm with the integration's own system, such as the issue tracker or secrets manager, that the connection still authenticates and that events arrive in both directions. Ask your vendor or the integration owner to confirm any version compatibility that the GitLab documentation does not settle for your combination of systems. Keep the staging instance close enough to production that its results mean something, and treat a failed test as a reason to delay the change rather than force it through.
Limits to confirm in your environment
Instance and group integration defaults depend on the GitLab tier, the version and the network your instance runs in. The cards below list the points to confirm against your own installation rather than assume from general guidance, and each one changes how you design the defaults.
Allowlist contents for your version
The allowlist controls which integrations users can enable, so its contents decide what your defaults can actually reach. Confirm which integrations appear in the list on your installed version, because the set changes between releases and an integration you planned around may be absent. Export or screenshot the list before you lock it, and record it alongside the rest of your instance configuration so later upgrades can be compared against it.
Tier availability on self-managed
Not every integration is offered on every GitLab tier, and some features tied to an integration depend on Premium or Ultimate. Confirm that each integration in your design is available on self-managed instances at the tier you license, using the pricing page and the integration docs for your version. A default that depends on a higher tier will silently fail to appear for groups on a lower one.
Locking group settings for subgroups
Group settings override instance settings, but you need to confirm whether a group owner can lock an integration so that subgroups and projects cannot change it. Without a lock, a subgroup owner may replace a required endpoint or disable an audit integration. Test the behavior on a non-production group and document which settings are enforceable and which are only suggested defaults.
Inheritance for new projects
Confirm exactly what a newly created project receives: the instance default, the group default, or an empty configuration that someone must complete by hand. Also confirm whether changing a group default later updates existing projects or only projects created afterward. The answer determines whether your defaults are a control or only a starting point, and it should be verified with a test project in each group type you run.
Endpoints inside air-gapped networks
Integrations that call external services need those endpoints reachable from the GitLab instance and sometimes from runners. In an offline or air-gapped installation, confirm which integration endpoints must be hosted inside the network, such as an internal issue tracker, chat service or secrets manager, and which features simply stop working. GitLab documents offline environments separately, so check that guidance against each integration you plan to enable.
Ownership of allowlist changes
Confirm who can change the allowlist and the instance-level defaults, and whether those changes are recorded in a way your change management process accepts. Administrator roles are often broader than the team responsible for integrations, so the owner of each default should be named in writing. Check how changes appear in the audit events available on your tier before relying on them as evidence.
Questions administrators ask before setting integration defaults
How much effort does setting integration defaults take, and what drives it?
The effort depends mostly on how many groups and projects inherit settings, how many integrations you intend to allow, and how many approval steps sit between a technical change and a business decision. A single instance with a few top-level groups and two or three integrations is a small configuration task. A large organization with nested groups, separate owners for each business unit and several integrations that touch secrets or Kubernetes clusters takes longer because each override needs a decision and a test. Ask any partner for a written scope that lists the groups, the integrations, the tier you run and the approvals you require, then compare quotes against that same list.
Can an internal team set integration defaults without a partner?
Yes, in most organizations. Instance and group integration settings are administrative configuration in GitLab, so a team that already runs the instance can do the work with the right access. A partner adds value when the inventory is unclear, when integrations need credentials or network paths that the platform team does not control, or when the allowlist must be designed against a written policy. Decide early which parts your team will own, because the allowlist and the group defaults are easiest to maintain when one team holds the change record.
What does the work need from our team before it starts?
Three things matter most. You need administrator access to the self-managed instance, a written inventory of the integrations people currently use or want, and a named owner for each group who can approve the settings that group inherits. Without the inventory, the allowlist becomes guesswork, and without group owners, overrides are approved by whoever is available. Also collect the external systems each integration connects to, such as issue trackers, secrets managers and chat tools, along with the accounts or service identities that will authenticate to them.
Which integration settings should an engineer check before enabling an integration?
Check whether the integration is on the allowlist, whether the instance default is set, and whether any group or project overrides it. Confirm which credentials the integration stores and who can read them, because project maintainers may be able to change settings that a group owner expects to control. Verify network reachability from the GitLab instance to the external service, and test the integration on one non-production project first. Confirm the behavior in the integration documentation for your GitLab version, since available options and tier requirements vary by integration.
What changes after go-live, and who keeps the settings current?
After go-live, the main ongoing work is handling new integration requests, reviewing overrides when groups reorganize, and removing integrations from the allowlist when they are retired. Upgrades can also change integration options or tier requirements, so review the settings during each planned upgrade. Assign one owner for the allowlist and a documented process for group owners to request changes. This recurring work is usually small, but it is easy to skip, and skipped reviews are how stale overrides and unused credentials accumulate.
Which tier do we need for the integrations we plan to enable?
Tier requirements differ by integration and by feature, so the answer comes from the integration documentation and your current license, not from a general rule. GitLab's pricing page lists Premium and Ultimate features for self-managed installations, and some integration-related capabilities depend on those tiers. Ask a partner to map each planned integration to its documented tier requirement in the written scope, and confirm the result with GitLab or your license holder before you approve the allowlist.
How should we scope a quote for integration defaults?
Ask for a quote that is built from a written scope. The scope should list the instance settings to configure, each group and its owner, the integrations on the allowlist, the projects that need overrides, the test plan and the handover material. Ask which items are one-time work, such as the initial configuration and testing, and which are recurring, such as an allowlist review or support during upgrades. Ask how changes after delivery are priced and approved. DeployOpen does not publish a price list, and a quote follows from the written scope.
How DeployOpen scopes and supports GitLab integration defaults
DeployOpen plans, implements, documents and supports self-managed GitLab inside your own infrastructure, including the instance and group integration defaults that decide which tools projects can connect to. Engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory which external tools teams need to connect, such as issue trackers, secrets managers, clusters and chat.
- Decide which integrations are set at instance level, which are set per group, and which projects may override them.
- Define the integration allowlist and record who approves changes to it in the written scope.
How we build
- Configure instance and group integration settings in a staged environment before changing production defaults.
- Test inheritance by checking that a sample project receives group defaults and that permitted overrides still save.
- Verify that disallowed integrations cannot be enabled by project maintainers, using accounts with each role.
How we hand over
- Provide a written record of every instance and group default, the allowlist entries and the reason for each.
- Walk administrators and group owners through how to request a new integration and who must approve it.
- Document the rollback steps for each default so changes can be reverted during a maintenance window.
How we support
- Review the allowlist and integration defaults when GitLab upgrades or the team's tool landscape changes.
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing.
- Confirm with your own administrators which integration options your GitLab version and tier provide before scoping.
