Sync skills from GitHub

Use GitHub Actions to publish skills whenever their source changes on main. The repository remains the source of truth, while Atlan records the repository, commit, and path for each published version. The workflow below is a copyable CI script. It does not depend on a published Atlan GitHub Action.

Before you start

You need a GitHub repository with Actions enabled, an Atlan workspace ID, and a dedicated Atlan API key whose identity can publish to that workspace. Each skill must be a direct child of one repository directory and include a case-sensitive SKILL.md file:

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

1. Declare what to publish

Create .atlan/package.json at the repository root:

{
  "name": "example-skills",
  "configVersion": 1,
  "publishConfig": {
    "workspaces": ["workspace_01example"],
    "directory": "skills",
    "skills": "*",
    "trigger": "ci",
    "branch": "main"
  }
}

Field	Value
`configVersion`	The current manifest version: `1`.
`workspaces`	One or more destination workspace IDs. Use the older `workspace` form only for one destination; never set both fields.
`directory`	One existing, repository-relative directory containing the skill folders. Symlinks are rejected.
`skills`	`"*"` for every discovered folder, or a list such as `["meeting-brief"]`.
`trigger`	`"ci"` for this workflow.
`branch`	The only branch allowed to publish. It defaults to `main` for CI.

The manifest rejects unknown fields. In particular, use directory and skills; publishConfig.paths is not supported.

2. Add the API key to GitHub

In the GitHub repository, open Settings → Secrets and variables → Actions and create this repository secret:

Name	Value
`ATLANAI_TOKEN`	The dedicated Atlan API key.

Never add the API key to .atlan/package.json, the workflow file, logs, or screenshots. The identity behind the key must be a member of every destination workspace declared in the manifest.

3. Add the workflow

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

name: Sync skills to Atlan

on:
  push:
    branches: [main]
    paths:
      - 'skills/**'
      - '.atlan/package.json'
      - '.github/workflows/atlan-skill-sync.yml'

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

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0

      - name: Install atlanai
        env:
          ATLANAI_CHANNEL: preview
        run: |
          set -euo pipefail
          curl --fail --silent --show-error --location --retry 3 --retry-connrefused \
            https://agentgateway.atlan.engineering/install.sh -o "$RUNNER_TEMP/atlanai-install.sh"
          sh "$RUNNER_TEMP/atlanai-install.sh"
          atlanai version

      - name: Publish skills
        env:
          ATLANAI_TOKEN: ${{ secrets.ATLANAI_TOKEN }}
          CHANGED_SINCE: ${{ github.event.before }}
        run: |
          set -euo pipefail
          args=(skill publish --ci)
          if [ -n "${CHANGED_SINCE:-}" ] && [ "${CHANGED_SINCE}" != "0000000000000000000000000000000000000000" ]; then
            args+=(--changed-since "${CHANGED_SINCE}")
          fi
          atlanai "${args[@]}"

Change skills/** when the manifest uses another directory. Keep fetch-depth: 0: the CLI needs complete history to record the first and most recent source commits accurately. The script downloads the installer before it runs it. Review any change to that installer origin as a CI dependency change; do not replace it with a curl | sh pipeline. The API key remains only in the GitHub secret.

What the workflow does

Validates .atlan/package.json and the allowed publish branch.
Finds skill folders under publishConfig.directory.
Publishes skills changed since the push’s base commit. A first push, an unresolvable base commit, or an all-zero base publishes every declared skill.
Creates a skill for a new repository path or appends a version when the Registry already has that repository and path.
Skips unchanged content, waits for the Registry security scan, and fails the job when the scan blocks a skill.

The CI runner has no local tracking database. Reconciliation uses the repository and path, not a skill name, because names can be edited or repeated.

Verify the first sync

Commit the manifest and workflow to main. Confirm that the Sync skills to Atlan workflow completes, the skills appear in the intended workspace, and a skill profile shows its repository, commit, and path. If a scan remains pending after 60 seconds, the CLI prints follow-up skill get and skill runs commands. Use those commands to confirm the final scan state before treating a skill as available.

Optional workflow controls

Add one of these arguments to the args array only when the override is reviewed for that run:

Argument	Behavior
`--workspace <id>`	Override the manifest destinations. Repeat it for several workspaces.
`--branch-guard <branch>`	Override the allowed publish branch.
`--prune`	Archive repository-bound skills removed from the checkout.

--prune archives artifacts, so enable it only after confirming the expected removed skill directories. It preserves versions and traces.

Run the same publish locally

atlanai skill publish
atlanai skill publish --changed-since HEAD~1
atlanai skill publish --workspace workspace_01example
atlanai skill publish --ci

.atlan/package.json is required for skill publish. For one local skill without a repository manifest, use Publish skills with the CLI.

Troubleshooting

unknown field "paths" — replace publishConfig.paths with the supported directory and skills fields. This checkout is shallow — set fetch-depth: 0 on actions/checkout. No such resource, or it is not visible to you — confirm the workspace ID and that the identity behind ATLANAI_TOKEN can publish there. Publishing is restricted to main — merge the change to the manifest’s configured branch.

Welcome

Desktop app

Administration

Sync skills from GitHub

Sync skills from GitHub

Before you start

1. Declare what to publish

2. Add the API key to GitHub

3. Add the workflow

What the workflow does

Verify the first sync

Optional workflow controls

Run the same publish locally

Troubleshooting

​Sync skills from GitHub

​Before you start

​1. Declare what to publish

​2. Add the API key to GitHub

​3. Add the workflow

​What the workflow does

​Verify the first sync

​Optional workflow controls

​Run the same publish locally

​Troubleshooting

Sync skills from GitHub

Before you start

1. Declare what to publish

2. Add the API key to GitHub

3. Add the workflow

What the workflow does

Verify the first sync

Optional workflow controls

Run the same publish locally

Troubleshooting