Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Glean Agent Sync Action

A GitHub Action that keeps your git-managed Glean agents in sync with your Glean workspace.

  • On pull requests — creates a draft preview in Glean and posts a comment with preview links
  • On merge — syncs updated agent definitions into Glean (staged or published) and posts run links back to the PR

Usage

name: Glean Agent Sync

on:
  pull_request:
    paths:
      - '.glean/agents/**'
  push:
    branches:
      - main
    paths:
      - '.glean/agents/**'
  workflow_dispatch:
    inputs:
      agent_folder:
        description: 'Specific agent folder to sync (leave blank to sync all changed)'
        required: false
      is_draft:
        description: 'Force draft preview mode even on push'
        required: false
        default: 'false'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # required for git diff to detect changed folders

      - uses: askscio/glean-agent-import-action@v1
        with:
          instance-url-fe: 'https://your-company.glean.com'
          instance-url-be: 'https://your-company-be.glean.com'
          api-token: ${{ secrets.GLEAN_API_TOKEN }}

Note: fetch-depth: 0 is required. The action uses git diff to detect which agent folders changed since the base commit.

Inputs

Input Required Default Description
instance-url-fe ✅ — Frontend instance URL used for preview/run links in PR comments (e.g. https://acme.glean.com)
instance-url-be ✅ — Backend instance URL for API calls (e.g. https://acme-be.glean.com)
api-token ✅ — Glean client API token with AGENTS (legacy) or AGENTS_WRITE scope
agent-directory ❌ .glean/agents Path within the repo where agent folders live
shared-root ❌ .glean/common Root directory for shared reusable agent resources. Changes here trigger downstream agent re-sync via symlink dependency resolution.
default-sync-mode ❌ staged Default sync mode on push/merge: staged or published. Can be overridden per-agent via sync-mode in glean-sync.yaml

Outputs

Output Description
synced-agents JSON array of per-agent results: [{agentId, agentName, agentMode, mode, message, previewId, status}]. status may be success, error, or conflict; durable results may include resultHash and baselineHash. previewId is the transient preview workflow's id, set only for draft_preview.

Workflow dispatch inputs

When triggered via workflow_dispatch, the action reads these inputs from github.event.inputs:

Input Description
agent_folder Sync a specific agent folder by name, skipping diff detection
is_draft Set to true to force draft preview mode even on a push event

Agent folder structure

Each agent lives in its own subfolder under agent-directory, containing a spec.yaml.

Autonomous agents (spec.yaml)

.glean/agents/
└── my-agent/
    ├── spec.yaml          # Agent config: id, name, description, tools, skills, etc.
    ├── instructions.md    # Agent instructions (referenced by spec.yaml)
    ├── .glean-sync.yaml   # Generated by export/headless pull — published baseline (definitionHash)
    └── glean-sync.yaml    # Optional — override sync-mode or message

spec.yaml example:

id: agent-abc123
name: My Agent
description: Does something useful
tools:
  - toolProviderId: glean-search
actions:
  - actionId: bravewebsearch
serviceCredentials:
  - credentialId: credential-abc123

Use tools for MCP/action servers and actions for standalone built-in actions. Glean Search remains configured through gleanSearchConfig so its knowledge-source restrictions can be represented cleanly. Use serviceCredentials for service-account credentials the agent may access at runtime.

glean-sync.yaml reference

agent-id: agent-abc123    # Required for workflow agents; optional override for autonomous agents
sync-mode: staged         # Optional: "staged" (default) or "published"
message: "My release note" # Optional: version message shown in Glean (defaults to PR title or commit subject)
base-published-definition-hash: 3f2a9c... # Legacy: still honored as a fallback for the published baseline

Sync modes

Mode Trigger Behaviour
draft_preview Pull request (always) Creates an isolated, throwaway preview agent in Glean. The real agent's draft, staged, and published content are left untouched. Preview link posted to the PR.
staged Push/merge (default) Saves a new staged version pending moderator approval in Glean.
published Push/merge (opt-in) Immediately publishes the agent to all users.

To publish on merge, set default-sync-mode: published on the action input, or set sync-mode: published in a specific agent's glean-sync.yaml.

Published baseline guard

Export/headless pull records the published definition hash in .glean-sync.yaml at the agent folder root:

definitionHash: abcdef0123456789abcd

The Action uses a non-empty definitionHash from .glean-sync.yaml first, after trimming whitespace. If that field is blank or missing (or the file is absent), it falls back to base-published-definition-hash in the legacy glean-sync.yaml. If both contain different non-empty hashes, the new file wins and the Action emits a notice. With neither value, there is no baseline. A malformed non-empty value in the new file fails published sync instead of falling back.

Only the baseline moves: agent-id, sync-mode, and message are still read exclusively from glean-sync.yaml. Both files are excluded from upload bundles. The Action reads but never writes either file. Refresh the export or headless-builder pull after a successful publish to update the repository baseline.

Configuration Behavior
staged or draft_preview The baseline is ignored, including an unparseable .glean-sync.yaml; staged sync remains last-write-wins.
published with a plausible baseline Sends the baseline to the server, which rejects a stale publish with HTTP 409.
published without a baseline Publishes without the guard and emits a notice.
published with a malformed baseline or unparseable .glean-sync.yaml Fails locally before making a request.

An HTTP 409 means the agent was published outside this Git sync after the repository baseline was taken. The Action marks the result as conflict, leaves the server-side agent unchanged, and reports the server message. Pull/export the latest published version, commit the refreshed .glean-sync.yaml, and re-merge. A successful published sync reports its new hash in the merge comment as a recovery aid.

Durable syncs now send versionSource=GIT, so synced versions appear as Synced from Git in builder version history. This is version-level provenance; Git sync no longer makes the agent read-only in the UI.

How it works

  1. Detect — diffs changed files against the base SHA to find which agent folders changed. On workflow_dispatch, syncs all folders (or the specific folder provided via agent_folder input).
  2. Package — packages each agent folder into a ZIP with one top-level agent directory, matching the server’s import format. Symlinks are validated to stay inside the checkout, then dereferenced so the upload contains only regular files and directories, including dotfiles and nested assets.
  3. Import — uploads the ZIP as multipart form data to POST /rest/api/v1/agents/{id}/import. Durable imports include syncMode=STAGED|PUBLISHED and versionSource=GIT, plus Git metadata when available. Published imports include publishedBaselineHash when the sidecar provides a plausible baseline. PR imports remain isolated transient previews and do not send provenance or baseline fields.
  4. Comment — posts a PR comment with draft preview links (on pull requests) or sync status + run links (on push/merge).

Shared resources (shared-root)

Agents can depend on shared resources (skills, sub-agents, prompts, artifacts) via symlinks. When a shared resource changes, the action automatically detects all downstream agents that depend on it and re-syncs them.

How it works

  1. Files under shared-root (default .glean/common/) are monitored for changes.
  2. When a shared file changes, the action scans all agent directories for symlinks.
  3. Each symlink is resolved canonically. If the resolved target is inside shared-root, that agent is marked as a dependent.
  4. All affected agents are unioned with directly changed agents and synced in one batch.

Repo layout example

.glean/
  agents/
    agent-a/
      spec.yaml
      skill.md -> ../../common/skills/foo/skill.md     # symlink dependency
    agent-b/
      spec.yaml
      bundle -> ../../common/bundles/bar/               # directory symlink
    agent-c/
      spec.yaml
      local-only.md                                     # no shared deps
  common/
    skills/foo/skill.md
    bundles/bar/config.json

In this layout:

  • Changing .glean/common/skills/foo/skill.md triggers a re-sync of agent-a
  • Changing .glean/common/bundles/bar/config.json triggers a re-sync of agent-b
  • Changing both triggers a single combined sync of agent-a and agent-b
  • agent-c is only synced when its own files change directly

Workflow config with shared-root

on:
  pull_request:
    paths:
      - '.glean/agents/**'
      - '.glean/common/**'      # trigger on shared resource changes too
  push:
    branches: [main]
    paths:
      - '.glean/agents/**'
      - '.glean/common/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: askscio/glean-agent-import-action@v1
        with:
          instance-url-fe: 'https://your-company.glean.com'
          instance-url-be: 'https://your-company-be.glean.com'
          api-token: ${{ secrets.GLEAN_API_TOKEN }}
          shared-root: '.glean/common'

Dependency contract

  • Only symlink-resolved dependencies are detected (v1).
  • All paths are canonicalized before comparison.
  • Symlinks that resolve outside the repo workspace are rejected.
  • Broken symlinks emit a warning but are not counted as dependencies.

API token

Create a Glean client API token with the AGENTS (legacy) or AGENTS_WRITE scope and store it as a GitHub Actions secret (e.g. GLEAN_API_TOKEN).

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages