<!-- Title suggestion: [FF] `direct_transfer_preallocate_iids` -- Pre-allocate IIDs for Direct Transfer imports --> ## Summary This issue is to roll out [the feature](https://gitlab.com/gitlab-org/gitlab/-/work_items/520996) on production, that is currently behind the `direct_transfer_preallocate_iids` feature flag. This feature adds IID pre-allocation to the Direct Transfer (Bulk Import) importer. When importing projects or groups via Direct Transfer, a new `MaxIidsPipeline` fetches a `max_iids.json` file from the source instance and calls `Gitlab::Import::IidPreallocator` to reserve IID ranges for issues, merge requests, milestones, CI pipelines, designs, epics, and iterations **before** any relation imports begin. This prevents IID conflicts when users create records while an import is in progress. The export side (source instance generating `max_iids.json`) is always enabled — the feature flag only gates the import-side pre-allocation. ## Owners - Most appropriate Slack channel to reach out to: `#g_import` - Best individual to reach out to: @carlad-gl ## Expectations ### What are we expecting to happen? When the feature flag is enabled, Direct Transfer imports will reserve the highest IID from the source instance for all IID-bearing resource types at the start of the import. This ensures that if a user creates a record (e.g., a new issue) while the import is in progress, the new record will receive an IID that does not conflict with any imported records. ### What can go wrong and how would we detect it? - **IID gaps**: If the pre-allocated IID is higher than the actual imported max, future records will have a gap in IIDs. This is cosmetic and not a data loss issue. - **Pre-allocation failure**: If the `max_iids.json` file is missing or corrupt on the source, the pipeline will gracefully skip pre-allocation and imports continue as before (existing behaviour). Monitor import error rates and look for `MaxIidsPipeline` failures in the import logs. - **Source version incompatibility**: The import pipeline has `minimum_source_version: '18.11.0'`. Imports from older source instances will simply skip this pipeline. ## Rollout Steps Note: Please make sure to run the chatops commands in the Slack channel that gets impacted by the command. ### Rollout on non-production environments - Verify the MR with the feature flag is merged to `master` and has been deployed to non-production environments with `/chatops gitlab run auto_deploy status <merge-commit-of-your-feature>` - [ ] Deploy the feature flag at a percentage (recommended percentage: 50%) with `/chatops gitlab run feature set direct_transfer_preallocate_iids <rollout-percentage> --actors --dev --pre --staging --staging-ref` - [ ] Monitor that the error rates did not increase (repeat with a different percentage as necessary). - [ ] Enable the feature globally on non-production environments with `/chatops gitlab run feature set direct_transfer_preallocate_iids true --dev --pre --staging --staging-ref` - [ ] Verify that the feature works as expected. The best environment to validate the feature in is [`staging-canary`](https://about.gitlab.com/handbook/engineering/infrastructure/environments/#staging-canary) as this is the first environment deployed to. Make sure you are [configured to use canary](https://next.gitlab.com/). - [ ] If the feature flag causes end-to-end tests to fail, disable the feature flag on staging to avoid blocking [deployments](https://about.gitlab.com/handbook/engineering/deployments-and-releases/deployments/). ### Before production rollout - [ ] If the change is significant and you wanted to announce in [#whats-happening-at-gitlab](https://gitlab.enterprise.slack.com/archives/C0259241C), it best to do it before rollout to `gitlab-org/gitlab-com`. ### Specific rollout on production For visibility, all `/chatops` commands that target production must be executed in the [`#production` Slack channel](https://gitlab.slack.com/archives/C101F3796) and cross-posted (with the command results) to the responsible team's Slack channel. - Ensure that the feature MRs have been deployed to both production and canary with `/chatops gitlab run auto_deploy status <merge-commit-of-your-feature>` - [ ] For **project-actor**: `/chatops gitlab run feature set --project=gitlab-org/gitlab,gitlab-org/gitlab-foss,gitlab-com/www-gitlab-com direct_transfer_preallocate_iids true` - [ ] Verify that the feature works for the specific actors. ### Preparation before global rollout - [ ] Set a milestone to this rollout issue to signal for enabling and removing the feature flag when it is stable. - [ ] Check if the feature flag change needs to be accompanied with a [change management issue](https://about.gitlab.com/handbook/engineering/infrastructure-platforms/change-management/#feature-flags-and-the-change-management-process). - [ ] Ensure that you or a representative in development can be available for at least 2 hours after feature flag updates in production. - [ ] Ensure that documentation exists for the feature, and the [version history text](https://docs.gitlab.com/development/documentation/feature_flags/#add-history-text) has been updated. - [ ] Notify the [`#support_gitlab-com` Slack channel](https://gitlab.slack.com/archives/C4XFU81LG) and your team channel. ### Global rollout on production For visibility, all `/chatops` commands that target production must be executed in the [`#production` Slack channel](https://gitlab.slack.com/archives/C101F3796) and cross-posted (with the command results) to the responsible team's Slack channel. - [ ] [Incrementally roll out](https://docs.gitlab.com/development/feature_flags/controls/#process) the feature on production. - Example: `/chatops gitlab run feature set direct_transfer_preallocate_iids <rollout-percentage> --actors`. - Between every step wait for at least 15 minutes and monitor the appropriate graphs on https://dashboards.gitlab.net. - [ ] After the feature has been 100% enabled, wait for at least one day before releasing the feature. ### Release the feature - [ ] Create a merge request to remove the `direct_transfer_preallocate_iids` feature flag. - [ ] Ensure that the cleanup MR has been included in the release package. - [ ] Close [the feature issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/520996) to indicate the feature will be released in the current milestone. - [ ] Once the cleanup MR has been deployed to production, clean up the feature flag from all environments: `/chatops gitlab run feature delete direct_transfer_preallocate_iids --dev --pre --staging --staging-ref --production` - [ ] Close this rollout issue. ## Rollback Steps - [ ] This feature can be disabled on production by running the following Chatops command: ``` /chatops gitlab run feature set direct_transfer_preallocate_iids false ``` - [ ] Disable the feature flag on non-production environments: ``` /chatops gitlab run feature set direct_transfer_preallocate_iids false --dev --pre --staging --staging-ref ``` - [ ] Delete feature flag from all environments: ``` /chatops gitlab run feature delete direct_transfer_preallocate_iids --dev --pre --staging --staging-ref --production ```