Mobile push notification settings

GitLab can deliver mobile push notifications for to-dos through the Apple Push Notification service (APNs), using Apple provider token (p8) authentication. Delivery is skipped entirely when no signing key is configured.

The server-side feature is controlled by feature flags that are disabled by default: mobile_push_registration_api gates the mobile push subscriptions API that devices register with, and mobile_push_notifications_dispatch and mobile_push_notifications gate delivery. Devices cannot register and no pushes are delivered until an administrator enables all three.

Prerequisites:

• An APNs provider token signing key (.p8 file) from an Apple Developer account, together with its key ID and the Apple Developer team ID.

To configure APNs delivery:

1. Copy the .p8 signing key to a path readable by GitLab, for example /etc/gitlab/mobile_push_apns_auth_key.p8, and restrict access to it:

   sudo chown git:root /etc/gitlab/mobile_push_apns_auth_key.p8
   sudo chmod 0400 /etc/gitlab/mobile_push_apns_auth_key.p8

   /etc/gitlab is world-readable, so without the chmod a plain copy leaves the private signing key readable by every local user. The key must stay readable by the git user: a root-only key passes gitlab-ctl reconfigure (which runs as root) but silently breaks delivery for the application (which runs as git).

2. Add the following to /etc/gitlab/gitlab.rb:

   gitlab_rails['mobile_push_apns_auth_key_path'] = "/etc/gitlab/mobile_push_apns_auth_key.p8"
   gitlab_rails['mobile_push_apns_key_id'] = "YOUR-APNS-KEY-ID"
   gitlab_rails['mobile_push_apns_team_id'] = "YOUR-APPLE-TEAM-ID"

   Optionally, set gitlab_rails['mobile_push_apns_topic'] to override the apns-topic header sent for device subscriptions that don’t carry a bundle identifier. When unset, the topic defaults to com.gitlab-mobile.app.

3. Save the file and run gitlab-ctl reconfigure.

The auth key path, key ID, and team ID must all be set together: gitlab-ctl reconfigure fails when only some of them are set. If no file exists at the configured key path, reconfigure prints a warning, and APNs delivery fails until the key is placed there and is readable by the git user.

Device registration is exposed through the mobile push subscriptions API.