On-call schedules for OnCall OSS on Grafana Labs

API & Terraform schedules

Fri, 03 Apr 2026 16:45:36 +0000

API & Terraform schedules

If your schedules became comprehensive, or you would like to distribute the same scheduling patterns through multiple teams in the org, we suggest considering storing schedules as code.

Web-based on-call schedules

Fri, 03 Apr 2026 16:45:36 +0000

Web-based on-call schedules

Grafana OnCall allows you to map out recurring on-call coverage and automate the escalation of alert notifications to on-call users. Configure and manage on-call schedules directly in the Grafana OnCall plugin to easily customize rotations with a live schedule preview, reference teammates’ time zones, and add overrides.

This topic provides an overview of key components and features.

Schedule settings

Schedule settings are initially configured when a new schedule is created and can be updated at any time by clicking the gear icon next to an existing schedule.

Available schedule settings:

Slack channel: Choose a primary Slack channel to send notifications about on-call shifts, such as unassigned on-call shifts.
Slack user group: Choose a Slack user group to receive current on-call updates.
Notification frequency: Specify whether or not to send shift notifications to scheduled team members.
Action for slot when no one is on-call: Define how your team is notified when an empty shift causes a gap in on-call coverage.
Current shift notification settings: Select how users are notified when their on-call shift begins.
Next shift notification settings: Specify how users are notified of upcoming shifts.

Schedule view

The schedule view is a detailed calendar representation of your on-call schedule. It contains three interactive weekly calendars and a 24-hour on-call status bar for visualizing who’s on-call and what time it is for your teammates.

Understand your schedule view:

Final schedule: The final schedule provides a combined view of rotations and overrides
Rotations: The rotations calendar represents all recurring on-call rotations for a given schedule.
Overrides: The override calendar represents temporary adjustments to the recurring on-call schedule. Any events on this calendar will take precedence over the rotations calendar.

Schedule quality report

The schedule view features a quality report that provides a score for your schedule based on rotations, overrides and shift swaps. It’s calculated based on these key factors:

Gaps (amount of time when no one is on-call)
Balance (uneven distribution of on-call shifts between team members)

Quality score is a numeric value between 0 and 100. The higher the score, the better the schedule quality. Web UI uses the following scale to show the quality score:

0-20: Bad
20-40: Low
40-60: Medium
60-80: Good
80-100: Great

To improve quality score:

Minimize the amount of time when no one is on-call.
Ensure users in the schedule have a similar amount of on-call time.

Depending on the quality score, the report can also provide:

Percentage of time when no one is on-call. E.g. “29% not covered” means that 29% of the time no one is on-call for the schedule. 24/7/365 coverage is considered ideal, so reducing this number will improve the overall schedule quality.
List of overloaded users. A user is considered overloaded if they have more on-call time than average for the schedule. E.g. “+15% avg” in quality report means that user has 15% more on-call time than average for the schedule. A perfectly balanced schedule is considered ideal, so reducing this number will improve the overall schedule quality.

Note: The next 52 weeks (~1 year) are taken into account when generating the quality report.

Schedule export

Export on-call schedules from Grafana OnCall to your preferred calendar app with a one-time secret iCal URL. The schedule export allows you to view on-call shifts alongside the rest of your schedule.

Import on-call schedules

Fri, 03 Apr 2026 16:45:36 +0000

Import on-call schedules

Use your existing calendar app with iCal format to manage and customize on-call schedules — import rotations and shifts from your calendar app to Grafana OnCall for widely accessible scheduling. iCal imported schedules appear in Grafana OnCall as read-only schedules but can be leveraged similarly to a web-based schedule.

Unfortunately there is a known limitation with Google Calendar import and export. Google may take up to 24h to import OnCall’s calendar (OnCall -> Google) and sometimes our customers report delay in exporting (Google Calendar -> OnCall). If actual calendar is critical for you, we suggest checking Web-based on-call schedules

Before you begin

Verify that your calendar app supports iCal format
Ensure you have the proper permissions in Grafana OnCall

Configure an on-call schedule from iCal import

There are three key parts to configuring on-call schedules using iCal import:

Create a primary on-call calendar and an optional override calendar in your calendar app.
Import the calendars into Grafana OnCall and configure additional schedule settings.
Link your schedule to corresponding escalation chains for alert notifications to be sent to the proper on-call user.

Create your on-call schedule calendar

Create a dedicated calendar to map out your on-call coverage using calendar events. Be sure to take advantage of the features of your calendar app to configure event recurrence, duplicate events, etc.

Note: The exact steps in this section will vary based on your calendar.

To create an on-call schedule calendar:

Create a new calendar in your calendar app, then review and adjust default settings as needed.
In your new calendar, create events that represent on-call shifts. You must use Grafana usernames as the event title to associate users with each shift.
Once your on-call calendar is complete, go to your calendar settings to locate the secret iCal URL. For example, in a Google calendar, this URL can be found in Settings > Settings for my calendars > Integrate calendar > Secret address in iCal format.

To learn more about how to configure your calendar events, refer to Calendar events.

Import calendar to Grafana On-Call

Once you’ve configured on-call schedules in your calendar app, you can import them via iCal URL to your Grafana OnCall instance.

Note: Use the secret iCal URL to avoid making the calendar public. If you use the public iCal URL, the calendar and event details must be public for Grafana OnCall to read your calendar.

To import an on-call schedule:

In Grafana OnCall, navigate to the Schedules tab and click + New schedule.
Navigate to Import schedule from iCal URL and click + Create.
Copy the secret iCal URL from your calendar and paste it the Primary schedule iCal URL field. Repeat this step for the Override schedule iCal URL field if you have an override calendar.
Provide a name and review available schedule settings.
When you’re done, click Create Schedule.

Create an override calendar (Optional)

An override calendar allows for on-call flexibility without modifying the primary schedule. You can use an override calendar to enable users to schedule on-call shifts that will override the primary schedule. Events scheduled on the override calendar will always override overlapping events on the primary calendar.

Create a new calendar using the same calendar service you used to create the primary calendar.
Be sure to set permissions that allow team members to edit the calendar.
In the Schedules tab of Grafana OnCall, select the primary calendar you want to override. Click Edit.
Enter the secret iCal URL in the Overrides schedule iCal URL field and click Update.

Calendar events

Whether your schedule is basic or complex, consider how your on-call coverage is structured before configuring your calendar events. To minimize the number of calendar events you need to create, try leveraging recurrence settings and event duplication.

Note: Each calendar event represents one on-call shift for a specific user. For Grafana OnCall to associate a calendar event with the intended on-call user, you must use their Grafana username as the event title.

Create overlapping schedules (optional)

If you create schedules that overlap, you can prioritize a schedule by adding a level marker to the calendar event title. You can prioritize schedule overlaps using [L0] - [L9] prioritization. Overlapping calendar events that do not contain a level marker result in all overlapping users receiving notifications.

For example, users AliceGrafana and BobGrafana have overlapping schedules but BobGrafana is the intended primary contact. The calendar events titles would be [L1] BobGrafana and [L0] AliceGrafana - In this case AliceGrafana maintains the default [L0] status, and would not receive notifications during the overlapping time with BobGrafana.

Shift swaps

Fri, 03 Apr 2026 16:45:36 +0000

Shift swaps

Shift swaps provide a convenient way for on-call engineers to find team members to exchange on-call shifts in a schedule for a specified time span to covered planned or unplanned unavailability.

Make a swap request

To request a shift swap, you can use the OnCall mobile app or the web UI in a schedule details page.

In the app, tapping one of your shifts presents an option to construct a shift swap request for that and/or other shifts.

It is also possible to setup a request from a schedule view, tapping on the request a swap button () displayed in the top-right corner. Include shifts by tapping them and/or specify starting and ending datetimes (they don’t need to match shifts exactly). The optional description will be displayed when notifying other users about the request.

In the web UI, you can follow a similar flow via the Request shift swap button, available in the Rotations lane of a schedule, or clicking the button shown when hovering on a particular shift event in which you are on-call. Additionally, the web UI allows you to create shift swap requests on behalf of other users (this is currently not supported in the mobie app).

Note: no recurrence rules support is available when requesting a shift swap. If you need to recurrently change a shift, consider creating a higher level layer rotation with the desired updates.

Upon submitting the request, a Slack notification will be sent to the channel associated to the correspondent schedule, if there is one. A mobile push notification will be sent to team members who participate in the schedule and have the notifications enabled.

Push notifications are sent 4 weeks ahead of the requested shift swap, or shortly after creation in case the shift swap start time is less than 4 weeks away, but always during users’ working hours (by default 9am-5pm on weekdays, according to the user’s mobile device timezone).

As long as the request is open, there will be follow-up mobile notifications as well as Slack updates to remind about the request. The follow-up notifications will be sent at the following intervals before the swap start:

4 weeks
3 weeks
2 weeks
1 week
3 days
2 days
1 day
12 hours

You can delete the swap request at any time. If the swap has been taken, it will automatically be undone upon removal.

Note: if RBAC is enabled, a user is required to have the SCHEDULES_WRITE permission to create, update, take or delete a swap request. SCHEDULES_READ will be enough to get details about existing requests.

Check existing swap requests

To review existing swap requests, check the events identified with the swap request icon in a schedule view, in the mobile app or in the web UI.

Take a swap request

If you are not the request owner and the request is still open, you have the option to take the swap. By doing so, you will replace the requester in the given schedule for their respective shifts during the specified period.

If no one takes the swap request before its starting datetime, the request will be closed, and the original user will remain on-call if there is a shift at that time.

Before taking a swap, you can review the involved shifts times.

You can also check (and take) a swap request details in the web UI.

Once a swap is taken, the affected rotations and the final schedule will reflect the changes.

Google Calendar Integration

Grafana OnCall allows you to connect your Google user to your OnCall user, giving us read-only access to your Google Calendar’s Out of Office events. We periodically check your Out of Office events to see if these overlap with any of your on-call shifts. If so, we’ll go ahead and automatically generate a shift swap request for you!

Note: A Google account can only be connected to one Grafana Cloud instance at a time. If you need to use the same Google account on a new instance, you’ll first need to disconnect the account from the previously connected instance.

To link your Google user, simply head over to “View my profile” on the OnCall “Users” page. From there, follow the steps under the Google Calendar tab. Once linked, you can further configure things, such as which OnCall schedules you would like us to consider for automatic shift swap generation (by default we will consider all of the schedules that you are involved in).

Updating Out of Office Events

When you update an existing Out of Office event in your Google Calendar (for example, extending or shortening its duration), Grafana OnCall will automatically update any corresponding open shift swap requests to match the new time range. This ensures your shift swap requests always stay in sync with your Out of Office calendar events.

For example:

If you extend an Out of Office event from 45 minutes to 90 minutes, the corresponding shift swap request will be automatically extended to cover the full 90 minutes.
If you shorten an Out of Office event, the shift swap request will be shortened accordingly.
If you delete a shift swap request that was automatically created from an Out of Office event, we will respect that decision and not recreate the request, even if the Out of Office event still exists.

Ignoring events

If you would like to have Grafana OnCall ignore a specific Out of Office event from being considered for Shift Swap Request generation, simply add #grafana-oncall-ignore to the Out of Office event’s title.

Additionally, if we generate a shift swap request for you from a Google Calendar event, and you delete the shift swap request, we will not attempt to regenerate a new shift swap request.

Configuring for open source

Follow the instructions here to setup your Google OAuth2 application.
Create a Client ID for your OAuth2 app and set the SOCIAL_AUTH_GOOGLE_OAUTH2_KEY and SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET environment variables accordingly.