Sync skills from GitHub

Syncing from GitHub keeps Git as the source of truth for a collection of skills: changes go through reviewed pull requests, and when one reaches the protected branch, a GitHub Actions workflow runs aireg with the Atlan adapter to publish the skills whose files changed. Use it when a team maintains several skills in one repository and wants every published version to come from a reviewed merge. To publish one skill from your own terminal instead, see Publish skills with aireg.

The example pins aireg and the Atlan adapter independently. Check both versions when upgrading an existing SkillSync workflow.

Before you begin

Before you start, make sure you have:

Repository: A GitHub repository with Actions enabled and a protected publish branch, normally main.
Skill folders: One or more folders, each with a case-sensitive SKILL.md file at its root.
Workspace administration: Permission to administer the destination workspace, so you can grant an API key access to it.

The examples assume this layout:

skills/
├── meeting-brief/
│   ├── SKILL.md
│   └── references/
└── release-notes/
    └── SKILL.md

Each part of the setup controls one thing:

Configure in	It controls
`.github/workflows/atlan-skill-sync.yml`	The one branch allowed to publish (`on.push.branches`), the skill folders, and the destination workspace.
GitHub branch protection	Required pull requests, reviews, and direct-push policy for that same branch.
GitHub Secrets	The API key. Nothing else in the repository holds a credential.

Find destination workspace

The workflow names the destination workspace by its name, as aireg registry show atlan lists it.To find it from a script instead, list the workspaces your identity can see with GET /registry/v1/workspaces, or client.workspaces.list() in the Workspaces. To copy a workspace’s ID, open the workspace in Atlan Trident desktop app, open its More actions (⋯) menu at the top of the page, and select Copy workspace ID.In GitHub, protect the branch the workflow will name. Require reviewed pull requests and prevent direct pushes. Protect changes to .github/workflows/** through the repository’s normal code-ownership process.

Add publish credential

Create a dedicated API key in Atlan Trident:

Open Settings, then select API keys.
Select New API key to create a key, or select an existing key.
Grant the key access to the destination workspace. When creating a key, select the workspace; for an existing key, add the workspace access before using it.
Copy the key value. It is shown only when the key is created. The dialog stays open until you select I’ve stored the API key somewhere safe, then Done. The same dialog shows the date the key expires. Before then, select Rotate on the key and save the new value as the ATLAN_API_KEY secret.

The key represents a service account. Use one key per repository, not a personal key or one shared by unrelated repositories.In GitHub, open Settings → Secrets and variables → Actions and create a repository secret named ATLAN_API_KEY with the key value. Do not put the key in the workflow file, logs, or screenshots. The workflow hands it to aireg as AIREG_TOKEN_ATLAN, a variable named AIREG_TOKEN_ followed by the registry’s name in capitals. aireg uses it for that run and never stores it; an API key works this way, not with aireg auth login.To add an approval gate, create a GitHub Environment such as atlan-publish, store ATLAN_API_KEY as an Environment secret, configure its required reviewers and allowed branches, and bind the publish job to it:

jobs:
  publish:
    environment: atlan-publish

Creating an Environment without the job-level environment setting does not gate the workflow or expose its Environment secret to the job.

Add publish workflow

Create .github/workflows/atlan-skill-sync.yml:

name: Sync skills to Atlan

on:
  push:
    branches: [main]
    paths:
      - "skills/**"

permissions:
  contents: read

concurrency:
  group: atlan-skill-sync-${{ github.repository_id }}
  cancel-in-progress: false

jobs:
  publish:
    runs-on: ubuntu-24.04
    env:
      AIREG_DISABLE_UPDATE_CHECK: "1"
    steps:
      - name: Check out full Git history
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Install pinned aireg and Atlan adapter
        shell: bash
        run: |
          set -euo pipefail
          curl --fail --location --proto '=https' --tlsv1.2 \
            https://aireg.sh/artifacts/v0.1.3/aireg-linux-amd64 \
            --output "$RUNNER_TEMP/aireg"
          printf '%s  %s\n' \
            '3796bb0ec1095a1f746e17d0f84f1e3a66150d2c7054229cf2ffac83d6b0d881' \
            "$RUNNER_TEMP/aireg" | sha256sum --check
          chmod +x "$RUNNER_TEMP/aireg"
          printf '%s\n' "$RUNNER_TEMP" >> "$GITHUB_PATH"
          "$RUNNER_TEMP/aireg" adapter install atlan@0.1.5

      - name: Publish changed skills
        env:
          AIREG_TOKEN_ATLAN: ${{ secrets.ATLAN_API_KEY }}
          WORKSPACE: release-tools
          BEFORE: ${{ github.event.before }}
        shell: bash
        run: |
          set -euo pipefail
          aireg registry add https://api.atlan.com --as atlan -g
          if git cat-file -e "${BEFORE}^{commit}" 2>/dev/null; then
            aireg publish 'skills/*' --to "atlan/${WORKSPACE}" --changed-since "${BEFORE}" --yes
          else
            aireg publish 'skills/*' --to "atlan/${WORKSPACE}" --yes
          fi

Replace main with the exact branch your branch protection protects, and release-tools with the workspace’s name. An ID also works, but aireg then lists every skill as add. Keep the paths filter and the aireg publish glob aligned with your skill folders, and repeat the aireg publish line once per workspace to publish to more than one.On the first push to a branch there is no previous commit, so the workflow publishes every skill. The workflow pins aireg 0.1.3 and Atlan adapter 0.1.5, verifies the binary checksum before execution, and disables automatic update checks for that run. When upgrading, update the version and checksum together. The install step gets no credential; only the publish step reads the secret. For how globs and --changed-since work, and why the checkout needs fetch-depth: 0, see aireg publish in the aireg CLI reference.

Review changes in pull requests

Review the full pull request diff, including references, templates, scripts, and assets inside each skill folder, before you merge. An automated pull request report (preflight) is not available with aireg yet. Do not give the publish credential to a workflow that runs on pull requests.

Verify publishing

Merge the pull request into the protected branch, open the Sync skills to Atlan workflow run, and confirm that it:

Installs aireg and the Atlan adapter.
Lists each skill whose files changed as add or update, or same when Atlan already serves those files.
Prints Published …. It fails if Atlan Trident refuses a skill, for example blocked <name>: its security scan rejected this skill, so it was not published.

aireg does not wait for or report the security scan, and a new version stays unavailable until its scan and any review pass. Open the skill in Atlan Trident and inspect Source. When the checkout has an origin remote, aireg records the repository and the skill’s folder with each version. If the run failed, see Skill errors.Recording a source repository does not archive a skill when its folder is deleted from Git. Review deleted skills and Archive skill when they should no longer be served.

Run same publish locally (optional)

With aireg set up for Atlan (see Use aireg with Atlan), preview and run the same publish from a checkout:

aireg publish 'skills/*' --to atlan/release-tools --changed-since HEAD~1 --dry-run
aireg publish 'skills/*' --to atlan/release-tools --changed-since HEAD~1

Keep an agent in sync too

An agent can live under the same source of truth. Its definition is a folder with an AGENT.md file — front matter with name and description, and the prompt as the body — plus the files beside it that it needs; a repository that already defines an agent as a single file under .claude/agents/ keeps that shape. Set the sync up with /atlan-link-skill: it exports the folder in the repository manifest .registry/manifest.yml, with depends_on naming the skills the agent uses, and CI publishes the agent and its files on every merge, at the same paths. Publishing an agent this way needs Atlan adapter 0.1.17 or later. The pull request’s preview shows what each merge publishes. What the folder does not hold, CI leaves as it is: the model, tools, framework, provider, step limit, and public URL. Set those once after the first publish. An edit in Atlan Trident to the agent’s instructions, files, or skill pins does not last: the next merge publishes the repository’s version over them. See Atlan commands and skills for coding agents for what /atlan-link-skill and /atlan-link-agent do.

Troubleshooting

If the workflow cannot find a commit, fails to authenticate, publishes to the wrong workspace, fails to install aireg, or reports a blocked scan, see Skill errors.

Next steps

Release skill version: Choose which published version a channel serves.

Publish or update skill

Release and use skills

Improve and maintain

How skills work

Troubleshoot

Before you begin

Keep an agent in sync too

Troubleshooting

Next steps

See also