ci: pull tokens from Tokens Studio on release (#5155)

* ci: pull tokens from Tokens Studio on release

* ci: add concurrency guard, cache-miss fallback, and failure alert to tokens pull

Author: pomfrida

.github/workflows/tokens_studio_release.yaml

@@ -3,16 +3,39 @@ name: Tokens Studio release
 # CI Triggers). Studio sends a repository_dispatch event with this event
 # type when a release is created. Note: repository_dispatch only triggers
 # workflows on the default branch.
+#
+# The payload does not include the release version, so the workflow pulls
+# the current state of the sources configured in
+# packages/eds-tokens/.studio.json and opens a PR with any changes.
 on:
   repository_dispatch:
     types: [tokens-release]
+# Two releases in quick succession would otherwise race on the shared
+# tokens-studio-release branch — serialise runs instead
+concurrency:
+  group: tokens-studio-release
+  cancel-in-progress: false
 jobs:
-  handle-release:
-    name: Handle Tokens Studio release
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
+  setup:
     permissions:
       contents: read
+    uses: ./.github/workflows/_setup.yml
+    secrets: inherit
+    with:
+      cacheKey: ${{ github.sha }}-tokens-studio-release
+      checkout_paths: packages/eds-tokens
+  pull-tokens:
+    name: Pull tokens from Tokens Studio
+    runs-on: ubuntu-latest
+    needs: setup
+    timeout-minutes: 15
+    permissions:
+      # OIDC token so the studio CLI can authenticate against the
+      # Tokens Studio CI integration (no service token needed)
+      id-token: write
+      # Create the branch and pull request with the pulled changes
+      contents: write
+      pull-requests: write
     steps:
       - name: Log release payload
         env:
@@ -21,3 +44,46 @@ jobs:
         run: |
           echo "Received repository_dispatch event: $EVENT_TYPE"
           echo "$CLIENT_PAYLOAD" | jq .
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.16.0'
+      - name: Use "setup" cache
+        id: setup-cache
+        uses: actions/cache@v6
+        with:
+          path: |
+            ./*
+            ~/.pnpm-store
+          key: ${{ github.sha }}-tokens-studio-release
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          run_install: false
+      # Fallback if the cache from the setup job was evicted — without it
+      # the workspace is empty and the studio binary is missing
+      - name: Checkout (cache-miss fallback)
+        if: steps.setup-cache.outputs.cache-hit != 'true'
+        uses: actions/checkout@v7
+      - name: Install dependencies (cache-miss fallback)
+        if: steps.setup-cache.outputs.cache-hit != 'true'
+        run: pnpm install --force
+      - name: Pull tokens from Tokens Studio
+        run: pnpm --filter @equinor/eds-tokens exec studio tokens pull --ci
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        with:
+          commit-message: 'chore: update tokens from Tokens Studio release'
+          title: 'chore: update tokens from Tokens Studio release'
+          body: 'Automated pull of the token state after a Tokens Studio release, via the CI integration and `studio tokens pull`. See `packages/eds-tokens/.studio.json` for the configured sources.'
+          branch: tokens-studio-release
+      # This workflow runs unattended (release-triggered) and the PR it
+      # creates gets no CI runs, so a failed pull must not be silent
+      - name: log-errors-to-slack
+        uses: act10ns/slack@v2
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+        with:
+          status: ${{ job.status }}
+          steps: ${{ toJson(steps) }}
+        if: failure()

documentation/agent-instructions/TOKENS_STUDIO.md

@@ -30,21 +30,26 @@ The CLI is `@tokens-studio/studio-cli` (binary name `studio`), installed as a **
 
 ## Configuration (`.studio.json`)
 
-`studio config init` creates `.studio.json`; `studio config add <alias>` adds a token source (interactively, or with `--project <uuid> --branch <name> --format <fmt> --output <dir>`). The file maps aliases to sources:
+`studio config init` creates `.studio.json`; `studio config add <alias>` adds a token source (interactively, or with `--project <uuid> --branch <name> --format <fmt> --output <dir>`). The file maps aliases to sources under a `configurations` key:
 
 ```json
 {
-  "sources": {
+  "$schema": "https://tokens.studio/schema/cli",
+  "configurations": {
     "my-tokens": {
-      "project": "proj_abc123",
-      "branch": "main",
-      "output": "src/tokens/my-tokens"
+      "project": "4952a007-699a-4124-a043-124e80cc28d6",
+      "ref": {
+        "type": "branch",
+        "name": "main"
+      },
+      "output": "src/tokens/my-tokens",
+      "format": "raw"
     }
   }
 }
 ```
 
-- Sources can reference a `branch`, a `release`, or a `tag` — pin to a release for reproducible builds.
+- The `ref` can reference a `branch`, a `release`, or a `tag` — pin to a release for reproducible builds.
 - Pull formats are `raw` (default), `dtcg`, and `css`. **There is no TypeScript pull format** — pull raw/DTCG JSON and generate TS locally, as the existing Style Dictionary build does for `build/ts/*`.
 - `studio config show` displays the config; `studio config remove <alias>` (alias `rm`) removes a source from `.studio.json`. It does **not** delete already-pulled token files — clean those up manually.
 - `.studio.json` is meant to be committed for team consistency.
@@ -100,4 +105,4 @@ studio
 └── flags       --host --json --no-color --verbose
 ```
 
-Known state in this repo at snapshot time: CLI installed as a devDependency of `packages/eds-tokens` and approved in `onlyBuiltDependencies`; no `.studio.json` committed yet.
+Known state in this repo at snapshot time: CLI installed as a devDependency of `packages/eds-tokens` and approved in `onlyBuiltDependencies`. `.studio.json` lives in `packages/eds-tokens` and is pulled in CI by `.github/workflows/tokens_studio_release.yaml`, triggered by the Tokens Studio CI integration (`repository_dispatch`, event type `tokens-release`) on every platform release. CI auth is OIDC (`id-token: write` + `--ci`) — no service token stored.

packages/eds-tokens/.studio.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://tokens.studio/schema/cli",
+  "configurations": {
+    "eds-test-3": {
+      "project": "4952a007-699a-4124-a043-124e80cc28d6",
+      "ref": {
+        "type": "branch",
+        "name": "main"
+      },
+      "output": "src/tokens/eds-test-3",
+      "format": "raw"
+    }
+  }
+}