How to make a Confluence group watch a space (and keep it updated when people join)

#confluence #atlassian #productivity #tutorial

A common ask from team leads: "everyone on the team should get updates from our Confluence space." In Confluence Cloud that turns out to be harder than it sounds, because watching is something each person does for themselves. Here is what actually works, and where each option stops.

What the built-in behaviour is

Each person selects Watch on a page or a space. Watching a space covers all its pages and blog posts.
Only user accounts can watch. There is no way to add a group as a watcher, so a group of 40 people is 40 separate watches.
People see what they watch under Notifications, Watching, and can unwatch whenever they like.

So the native options are: ask everyone to click Watch (works for five people, not for fifty), or have an admin set the watches for them.

Option 1: an admin sets the watches with the REST API

Confluence's REST API can create a watch for another person, one at a time:

Space: POST /wiki/rest/api/user/watch/space/{spaceKey}?accountId={accountId}
Page: POST /wiki/rest/api/user/watch/content/{pageId}?accountId={accountId}

You need the header X-Atlassian-Token: no-check, and the caller must be a Confluence Administrator, or a Space Administrator of that space. Anyone else can only add a watch for themselves. A watch never grants access, so members who can't see the space are skipped.

Here is a one-time script that adds every member of one group to one space. It needs an API token for your own account, curl and jq:

SITE="https://your-site.atlassian.net"
AUTH="you@example.com:your-api-token"
SPACE="TEAM"          # the space key
GROUP="developers"    # the group name

# 1. Look up the group's ID
GROUP_ID=$(curl -s -u "$AUTH" "$SITE/wiki/rest/api/group/picker?query=$GROUP" \
  | jq -r --arg n "$GROUP" '.results[] | select(.name == $n) | .id')

# 2. Read the members, 200 at a time, and add a watch for each
start=0
while :; do
  page=$(curl -s -u "$AUTH" "$SITE/wiki/rest/api/group/$GROUP_ID/membersByGroupId?start=$start&limit=200")
  for id in $(echo "$page" | jq -r '.results[] | select((.accountType // "atlassian") == "atlassian") | .accountId'); do
    curl -s -o /dev/null -w "%{http_code} $id\n" -u "$AUTH" -X POST \
      -H "X-Atlassian-Token: no-check" \
      "$SITE/wiki/rest/api/user/watch/space/$SPACE?accountId=$id"
  done
  [ "$(echo "$page" | jq -r '._links.next // empty')" = "" ] && break
  start=$((start + $(echo "$page" | jq '.results | length')))
done

A 204 means the watch was added. For one page, use the page endpoint with the page ID from the URL.

Prefer a script? There's a free MIT one here: https://github.com/kayabyte-2/atlassian-admin-scripts#confluence-group-watch

Where the script stops

It is a snapshot. Fine for a one-time rollout, but groups change:

Joiners are not added until you run it again.
Leavers keep watching, and keep getting emails about a space that is not theirs any more.
People who unwatched on purpose get added back on the next run, and usually respond by filtering the emails.
Watches people set up themselves look identical to the ones you added, so a cleanup script can't tell which ones it may remove.

You can put the script on a schedule, but then you also need a record of which watches you added, who opted out and who already watched before. That record is the real work.

Option 2: Automation for Confluence

I looked for a way to do this with Automation for Confluence rules and did not find a built-in "add watcher" action for a group's members, so I would not count on it. You can have a rule send a notification or post when a page is created in a space, which covers "tell the team about new pages" but not "make the team watchers". If you know of a way I missed, I'd like to hear it.

If watchers say they get no email

Before changing anything, check the email defaults. New pages and page edits in watched content go into the daily digest by default, while comments are emailed straight away. Each person can change it under their profile picture, Settings, Email. Updates also show under Notifications, Watching in Confluence itself.

Option 3: an app that keeps the watches in sync

Full disclosure: we build Group Watchers, so weigh this accordingly. Group Watchers: Auto-Watch Spaces & Pages for Confluence maps one or more groups to a space or a single page and keeps the watches in line with the groups:

It runs right after you change a rule and then every hour.
Joiners start watching. For leavers it removes only the watches it added, and you can switch removal off.
People who unwatch are not added back, and watches people already had are never touched.
It runs on Atlassian's Forge platform and sends no data outside Atlassian.

There are other Marketplace apps for this too, one of them free. I put a comparison on our site: https://kayabyte.dev/atlassian/guides/confluence-group-watch-apps-compared

If your group is small and stable, the script above is enough. The app earns its place when people move around often and you don't want to own the bookkeeping.

Confluence and Atlassian are trademarks of Atlassian. Kayabyte is independent and not affiliated with or endorsed by Atlassian.

DEV Community