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
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: 0is required. The action usesgit diffto detect which agent folders changed since the base commit.
| 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 |
| 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. |
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 |
Each agent lives in its own subfolder under agent-directory, containing a 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.
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
| 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.
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.
- 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 viaagent_folderinput). - 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.
- Import — uploads the ZIP as multipart form data to
POST /rest/api/v1/agents/{id}/import. Durable imports includesyncMode=STAGED|PUBLISHEDandversionSource=GIT, plus Git metadata when available. Published imports includepublishedBaselineHashwhen the sidecar provides a plausible baseline. PR imports remain isolated transient previews and do not send provenance or baseline fields. - Comment — posts a PR comment with draft preview links (on pull requests) or sync status + run links (on push/merge).
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.
- Files under
shared-root(default.glean/common/) are monitored for changes. - When a shared file changes, the action scans all agent directories for symlinks.
- Each symlink is resolved canonically. If the resolved target is inside
shared-root, that agent is marked as a dependent. - All affected agents are unioned with directly changed agents and synced in one batch.
.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.mdtriggers a re-sync ofagent-a - Changing
.glean/common/bundles/bar/config.jsontriggers a re-sync ofagent-b - Changing both triggers a single combined sync of
agent-aandagent-b agent-cis only synced when its own files change directly
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'
- 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.
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).