Change calendar
The company's Change calendar tab sets when changes may go out: change freezes (periods during which merges are held, or every change is critical risk) and change windows (the times changes are expected, which make up the timing part of a change's risk score). Windows apply to every repository and policy of the company; a freeze does too unless it is narrowed to some repositories, branches or policies, and a policy can be exempt from freezes.
How freezes act on the merge gate and the risk score, and how change windows are scored, is described in Risk → Change freezes and Risk → Change window. This page describes the tab itself and the Change calendar view under Insights.
Where to find it
Administration → Company (platform admins: Administration → Companies → the company), tab Change calendar. The company page opens for company admins and platform admins only. The policy editor links here too (Company change calendar, next to the change freeze note).
All times on the tab are wall-clock times in the company's Time zone (company General tab; UTC when it is not set). See General.
Change freezes
Freezes in the company's time zone, applied whether risk assessment is on or not. Hold stops merges (approval can still go ahead); emergency only lets only emergency changes through; score only raises the risk to critical (every freeze does). A merge made during a freeze that holds it is marked non-compliant. A freeze can be narrowed to repositories, target branches or policies; a policy can be exempt, or let one held change go ahead with a reason. (See Risk → Change freezes for exemptions and releasing one change.)
The card lists the company's freezes; without any it says No freezes yet. Add period adds a row:
| Field (label in the UI) | What it is |
|---|---|
| Freeze name | Shown on held merge requests (Change freeze … until …) and in the calendar view. Required, and unique within the company (ignoring case and spaces around it) |
| Start, End | Date and time. The freeze runs from Start up to, not including, End |
| Freeze mode | Hold merges (the default for a new row), Emergency changes only or Raise risk only |
| Repositories (path patterns) | Optional: the freeze covers only repositories whose path matches one of these patterns (for example payments/*). Empty: every repository |
| Target branches | Optional: only changes into a matching branch (for example release/*). Empty: every branch |
| Only changes under these policies | Optional: tick policies to cover only their changes. None ticked: every policy |
| Bin icon (Remove freeze) | Removes the row |
Next to a Raise risk only freeze, the tab warns No effect while risk assessment is off: such a freeze only raises the risk score, and nothing is scored while risk assessment is off (company Risk tab). Hold merges and Emergency changes only work whether risk assessment is on or not.
What each mode does to the merge gate and the risk score, overlapping freezes and merges made during a freeze are described in Risk → Change freezes. The fields, defaults and API values are listed in Risk → Change calendar tab.
Change windows
Times are in company timezone. Each window has its own risk score (0 adds no timing risk). Changes outside all windows get the out-of-window score. While risk assessment is off, the card adds Change windows count only while risk assessment is on (Risk tab).
At the top of the card:
- Out-of-window score: Risk score applied when a change falls outside all defined windows. Default 0.75, 0 to 1 (API
risk_config.out_of_window_score).
Without any window the card says No change windows configured. All times will be treated equally. (every change then gets a timing score of 0.25). Add window adds a window:
| Field (label in the UI) | What it is | New window |
|---|---|---|
| Window name | Shown in the calendar view. Required | Empty |
| Score | The timing score of a change inside this window, 0 to 1, in steps of 0.05 | 0.25 |
| Sun, Mon, Tue, Wed, Thu, Fri, Sat | The days the window starts on. A window without any day ticked never applies | None ticked |
| Start time to End time | Times to the minute. The window covers Start time up to, not including, End time; an end before the start runs overnight into the next day (the tab says Runs past midnight into the next day); an end of 00:00 is midnight at the end of the day | 09:00 to 17:00 |
| Bin icon (Remove change window) | Removes the window |
How the timing factor is scored is described in Risk → Change window.
Saving
The tab is saved with Save changes in the bar at the bottom of the company page, together with the other tabs (PUT /api/v1/companies/{id} with the risk_config object, which also holds the Risk tab's settings).
- A freeze or window that was filled in but not named stops the save: the page switches to this tab and says Name every change freeze and change window you filled in, or remove it. A row with no name that was not filled in is dropped.
- Saving is refused for two freezes with the same name (two change freezes have the same name "…": give each its own), for a freeze whose End is not after its Start, whose pattern looks like a regular expression or that names another company's policy, and for a window whose times are equal or out of range (see Risk → Change calendar tab for the messages).
- With four-eyes review on (company Governance tab), a change to the freezes or windows waits until another administrator approves it (Risk settings and change freezes). Until then the old calendar applies. See Governance.
- Every saved state of the risk settings, the calendar included, is kept as a version (
GET /api/v1/companies/{id}/risk-config/versions, the last 100, newest first).
The Change calendar view
Insights → Change calendar shows the company's calendar month by month, with the merges made on each day. It is not opened from the company page: it is in the Insights section for every role, showing the signed-in person's company (for platform admins, the company selected in the header; without one it says Select a company).
| Part | What it shows |
|---|---|
| Month and arrows | Previous month, Next month. The current month first |
| Timezone: … | The company's time zone, in which days are counted |
| Refresh | Loads the month again |
| Banner | When the company has no change window: No change windows configured for this company. Configure them in Company > Change calendar. |
| Legend | Window hours (a green dot), Change freeze (a red day), Merged, High-risk, Collision |
| Day | A green dot when a change window applies on that day, an overnight window on both days it spans; a red background when the day falls in a change freeze of any mode; the number of merges, and of high-risk merges; a warning sign when the day has a collision. Today is outlined |
| Selected day | Change window: the windows of that day with their hours, or No window. An overnight window shows on both days: Fri 22:00 to 06:00 as Fri 22:00–24:00 and Sat 00:00–06:00. Change freeze: the freeze's name with its mode, (merges held), (emergency changes only) or (risk raised only), or None. Merges: N merged, N high-risk, N in a change freeze. The day's collisions |
| Merge collisions | Every collision of the month, or No collisions detected this month. |
How the numbers are counted:
- Merged: merge requests merged that day, in the company's time zone.
- High-risk: those whose risk level was high or critical. Merge requests without a risk assessment (risk assessment off) do not count.
- In a change freeze: those whose merge time falls in one of the company's change freezes (of any mode), whether risk assessment is on or not.
- A collision is two or more merges into the same repository and target branch within the same two-hour slot of the day (00:00 to 02:00, 02:00 to 04:00, …), of which at least one was high-risk or in a change freeze (counted as above). Each shows the slot, the repository and branch, the number of merges, and how many were high-risk or in a freeze.
API: GET /api/v1/dashboard/change-calendar with month (YYYY-MM, the current month when left out); platform admins add company_id. The answer holds days[] (date, merged_count, high_risk_count, blackout_count), collisions[] (date, hour_bucket, repo_id, target_branch, merged_count, high_risk, in_blackout), the company's change_windows, blackout_periods (name, start, end, mode: hold, emergency_only or score) and timezone.
Related pages
- Risk: the risk score, the change window factor, change freezes, accepting a risk.
- Approval: emergency changes, which an Emergency changes only freeze lets through.
- General: the company's time zone.
- Governance: four-eyes review of risk settings and change freezes.
- Company overview.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →