skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
ariga/atlas72 installs

atlas-action

Atlas in CI/CD pipelines with the Atlas actions: ariga/setup-atlas and ariga/atlas-action on GitHub Actions, the GitLab CI components, the CircleCI orb, the Bitbucket pipe, and the Azure DevOps AtlasAction task. The CI/CD steps (migrate lint, push, diff, hash, autorebase, test, apply, down, set, drift; schema plan, plan approve, push, apply, lint, test; script exec, query, loop, test, push; security scan; monitor schema; create-repo) with its inputs, outputs, tokens, permissions, and pull request comments, plus pinning versions, runners, and fixing a failed run. Use with the atlas skill whenever a pipeline runs Atlas or an Atlas check in CI fails.

How do I install this agent skill?

npx skills add https://github.com/ariga/atlas --skill atlas-action
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is safe and follows security best practices for integrating the Atlas database migration tool into CI/CD pipelines. It provides clear guidance on secret management, identifies risks associated with pull request triggers, and uses official vendor-controlled sources for downloads and tool installations.

  • Socketwarn

    1 alert: gptAnomaly

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Atlas Actions: CI/CD Pipelines

Atlas runs in pipelines through one binary, atlas-action, shipped as GitHub Actions (ariga/atlas-action/<step>), GitLab CI components, a Bitbucket pipe, a CircleCI orb, and an Azure DevOps task. Each step wraps one Atlas command. The steps a platform has, the input names and defaults, and the outputs a later job can read differ by platform (references/actions.md, references/platforms.md). The atlas skill covers the CLI and the workflows; this skill covers the steps that run them in CI: which step, its inputs and outputs, the tokens and permissions it needs, and what to do when one fails.

Files

This skill is SKILL.md plus fourteen reference files under references/, each served at https://atlasgo.io/skills/atlas-action/references/<name>. Read a reference when the task needs it:

FileRead it for
references/setup.mdsetup-atlas, which job gets which credential, permissions, comment tokens, common inputs, outputs, runners and dev databases, pinning versions, GitHub Enterprise, monorepos, gh atlas init-action
references/actions.mdEach step's inputs, defaults, and outputs, and their names on each platform
references/lint.mdmigrate/lint (which files are new, comments, failures) and schema/lint
references/diff.mdFailing a pull request on a missing migration, and migrate/diff and migrate/hash, the steps that commit to the branch
references/rebase.mdmigrate/autorebase, atlas.sum conflicts, out-of-order migrations, exec-order
references/push.mdmigrate/push, schema/push, script/push, create-repo, registry URLs and tags
references/apply.mdmigrate/apply (deploy env checks, baseline, several targets, promotion), migrate/down, migrate/set
references/declarative.mdschema/plan, schema/plan/approve, schema/apply, ad-hoc approval
references/testing.mdmigrate/test, schema/test, script/test
references/drift.mdmigrate/drift on a schedule, drift at deploy time, monitor/schema
references/scripts.mdscript/exec, script/query, script/loop in pipelines
references/security-scan.mdsecurity/scan: severities, failing, the report
references/platforms.mdGitLab CI, CircleCI, Bitbucket Pipelines, Azure DevOps, and CI systems without an integration, such as Jenkins or TeamCity
references/troubleshooting.mdReading a failed run, each error message with its cause and fix, and common questions

Requires

The atlas skill, installed next to this one (../atlas/SKILL.md). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to ../atlas/SKILL.md and each reference file listed in its Files section to ../atlas/references/<name>. Paths below that start with atlas/ point into that skill. For the dev database and engine rules, also use the database skill installed next to this one for the project's engine, such as atlas-postgres or atlas-mysql, and for Kubernetes deploys, atlas-operator.

Setup Path

  1. Read atlas.hcl: the workflow (versioned or declarative), the env names, the registry repo (atlas/SKILL.md, Choosing a Workflow). Find the CI system from the repository (.github/workflows/, .gitlab-ci.yml, .circleci/, bitbucket-pipelines.yml, azure-pipelines.yml).
  2. Credentials (references/setup.md): one Atlas Cloud bot token, a repository secret that every job uses, and the database URLs as secrets of environments only the default branch can use. An organization admin creates the bot; the user stores the secrets.
  3. An env "ci" in atlas.hcl with the dev database, the registry repo, and the lint policy; database URLs only through getenv(); the organization pinned with atlas { cloud { org = "<org>" } } (references/setup.md). Check the file with atlas config validate before committing it: it needs the login and no database.
  4. The registry repo exists (atlas cloud repo list); if not, ask the user to approve the name, then the first push or create-repo creates it (references/push.md).
  5. The pull request workflow: migrate/lint (plus the test steps) or schema/plan.
  6. The merge workflow: migrate/push, or schema/plan/approve then schema/push.
  7. The deploy workflow, from the registry, with the drift check in the deploy env (references/apply.md, references/declarative.md). Production only when the user asks, in its own pull request.
  8. Optional jobs, when they fit: migrate/diff, migrate/autorebase, scheduled migrate/drift, security/scan, monitor/schema, Data Scripts.
  9. Verify: the pull request's Atlas check ran and commented (gh pr checks), the merge pushed a version (atlas cloud repo describe), and the first deploy is recorded (atlas cloud migration list); a file:// deploy is recorded only with report = true (references/apply.md).

Steps

StepRunsWhen
migrate/lintatlas migrate lint against the registry repoPull request
migrate/test, schema/test, script/testThe Atlas test framework on the dev databasePull request
migrate/diffGenerates a missing migration and commits itPull request
migrate/hashRecomputes atlas.sum and commits itPull request
migrate/autorebaseMoves the branch's files after the base's, fixes atlas.sumPush to a feature branch
migrate/pushPushes the directory to the registryMerge to the default branch
migrate/applyDeploys pending migrationsDeploy
migrate/downReverts applied migrations, with approvalOn demand
migrate/setMarks versions applied without running themOn demand, with approval
migrate/driftChecks a database against its migration historySchedule
schema/planPlans and lints the declarative change, comments itPull request
schema/plan/approveApproves the pull request's planMerge to the default branch
schema/pushPushes the desired schema to the registryMerge to the default branch
schema/applyApplies the approved plan, or waits for an ad-hoc approvalDeploy
schema/lintLints the whole desired schema, comments itPull request
script/exec, script/query, script/loopData Scripts on a targetSchedule or on demand
script/pushPushes Data Scripts to the registryMerge to the default branch
security/scanReports vulnerable server versions and extensions in databasesSchedule
monitor/schemaSends a schema snapshot to Atlas Cloud monitoringSchedule
create-repoCreates a registry repoOnce

Rules

  1. Every job logs in with a bot token from Atlas Cloud before its first Atlas step. On GitHub Actions, ariga/setup-atlas@v0 installs the CLI and logs in with cloud-token, and monitor/schema takes its own cloud-token. The other platforms log in as references/platforms.md shows. Logged out, most steps fail, but inspect and diff pass without views, functions, triggers, extensions, and other objects that need the login, with at most a notice in the log. Pin the organization in atlas.hcl and select an env on every step that takes one, so a job that is not logged in fails instead. A user without an account starts a free trial with atlas login.
  2. Database URLs stay out of pull request jobs. A job that a branch triggers runs that branch's workflow file and atlas.hcl, whose data "external" blocks run programs, so it can read every secret it gets. Keep the URLs in environments that only the default branch can use, and name them only in deploy and scheduled jobs. Never run Atlas on pull_request_target with the pull request's code (references/setup.md).
  3. Configuration lives in atlas.hcl, selected with env. Database URLs come from secrets through getenv() or the url input; never write one with a password into a workflow file.
  4. migrate/lint always takes dir-name, the registry repo slug. It lints the files that the repo's latest tag does not have, so migrate/push runs on every merge to the default branch, and only there: a push from a pull request moves latest to unreviewed files.
  5. Pull request comments need a pull request event (pull_request on GitHub, not pull_request_target; merge request pipelines on GitLab) and the platform's comment token. On GitHub: GITHUB_TOKEN in the step's env and pull-requests: write. A failed comment does not change the step's result.
  6. Steps that commit (migrate/diff, migrate/hash, migrate/autorebase) push with a token that the branch's code can read. Prefer failing the pull request and letting the developer commit the fix. Where the team uses them, they need contents: write, a git identity, fetch-depth: 0, and a checkout with a fine-grained token limited to this repository, so their commit starts lint (references/diff.md).
  7. Deploy from the registry with a pinned tag (atlas://<repo>?tag=<commit>). Safety checks (drift, deny rules, baseline) go in the deploy env, not in the workflow. Answer connected database is not clean with baseline, not allow-dirty, unless the user confirms the existing objects stay outside the directory.
  8. Declarative: plan on the pull request, approve and push on merge, apply the approved plan. All three read the same current state (references/declarative.md).
  9. Pin what must not move: the action at a release tag or the full SHA of a release commit (v1.15.4 or later), and the CLI with setup-atlas's version where a broken pipeline costs more than a missed fix.
  10. Runners: the GitHub steps download a linux/amd64 binary. On ARM or macOS runners, add ariga/atlas-action/setup to build it on the runner; Windows runners are not supported. docker:// dev URLs work only where Docker runs (GitHub-hosted Ubuntu); elsewhere use a service container, and give steps that create server-level objects (roles) their own dev database.
  11. On Azure DevOps and Bitbucket, input defaults do not apply: set latest: true on push steps there, and on the CircleCI orb's schema_push (references/platforms.md).
  12. Fix a failed step from its log (gh run view <id> --log-failed), with references/troubleshooting.md. Reproduce against dev databases only.
  13. Commit migration files with LF line endings (* text=auto eol=lf in .gitattributes): a CRLF checkout breaks atlas.sum (https://atlasgo.io/faq/checksum-mismatch).

Permissions

ActionRule
Reading runs, logs, checks, and atlas cloud state; lint and validate on a dev databaseRun
Writing workflow files and atlas.hcl on a branch, opening a pull requestRun; the pull request is the gate
Creating registry reposAsk first
Bot tokens and CI secretsThe user creates them; values never enter the conversation (gh secret list prints names only)
Triggering, rerunning, or approving a workflow run, deployment, revert, or planNever; tell the user what is waiting and where
Production deploy workflowsOnly in a separate pull request, when the user asks

Quick Answers

QuestionAnswer
atlasaction: missing required parameter dir-nameAdd dir-name: <repo slug> to migrate/lint, even when the env names the repo
slug must be lowercase alphanumeric and may contain /.-_dir-name holds atlas:// or a display name: pass the slug alone, the part of the repo URL after atlas://
Lint fails on old files in every pull requestThe registry repo has no pushed version, so every file is new: push on merge (references/lint.md)
--latest, --git-base, and --base are mutually exclusiveRemove latest (and git) from the env's lint block, and the step's git-base input: the action always passes --base
Lint ran, but no comment on the pull requestNot a pull_request event, or GITHUB_TOKEN/pull-requests: write missing (references/setup.md)
Resource not accessible by integrationThe job's token cannot write to the pull request: add permissions: pull-requests: write to the job
Where is the lint report link?The report-url output
Lint without Atlas CloudThe step needs the login and a registry repo. Without a registry, run atlas migrate lint --env ci --git-base origin/<branch> in a plain step (references/lint.md)
A CLI step ignores the lint policy in atlas.hclAtlas reads atlas.hcl only with --env, or with -c for its top-level blocks: run atlas migrate lint --env ci
Invalid version: <ref>Pin a release tag, or the full SHA of a release commit (v1.15.4 or later); for any other commit, build with ariga/atlas-action/setup@<sha>
A step fails at once on an ARM or macOS runnerThe downloaded binary is linux/amd64: add ariga/atlas-action/setup before the steps
Pipeline broke after an Atlas release, nothing changed in the repoPin version in setup-atlas to the last good release
The specified Atlas version does not exist or is no longer supported.The pinned CLI version was retired: move version to a current release
command requires 'atlas login'cloud-token is missing or empty in this job: fork pull requests and protected variables get no secrets
Which secrets go in which job?One bot token, a repository secret, in every job. Database URLs only in deploy and scheduled jobs, from environments only the default branch can use; a read-only user's for drift, scan, and monitoring (references/setup.md)
A merge job cannot push or approve after protected flows were turned onGive the bot the Writer role on the repo (https://atlasgo.io/cloud/roles-and-permissions)
The commit from migrate/diff, migrate/hash, or migrate/autorebase did not trigger lintCheck out with a PAT
atlas.sum conflict between branchesmigrate/autorebase on push to feature branches, then lint (references/rebase.md)
checksum mismatch in CI onlyLine endings: * text=auto eol=lf in .gitattributes, renormalize, rehash
migration file ... was added out of orderRebase the branch's files; exec-order only for environments that need it (references/rebase.md)
missing scheme for dir url or "<path>" is not a dir from migrate/applydir takes a migration directory URL with its scheme (file://migrations, atlas://app); a schema file deploys with schema/apply
connected database is not clean on the first deploybaseline = "<version>" in the deploy env's migration block
A renamed table or column shows as a drop and a create in the plan or lint commentCI cannot answer the rename prompt: declare the rename with renamed_from (HCL) or -- atlas:renamed_from (SQL), not with nolint (https://atlasgo.io/guides/destructive-change-policy)
ariga/atlas-action@v0, ariga/atlas-sync-action, or ariga/atlas-deploy-action in a workflowDeprecated in October 2023 and no longer updated: replace them with migrate/lint@v1, migrate/push@v1, and migrate/apply@v1 after ariga/setup-atlas@v0 with a token (references/troubleshooting.md)
Deploy stopped on the drift checkRun migrate/drift on the target to see the difference
the action should be run in a branch contextschema/plan/approve runs on push to the default branch, not on pull requests
found multiple schema plans, please approve or delete the existing plansDelete stale pending plans in Atlas Cloud, or pass plan
The plan "From" hash does not match the current state hashPlan, approve, and apply must read the same state; re-plan
plan approval pending, review here: <url>The user approves in Atlas Cloud and reruns, or the step sets wait-timeout
auto-approve is not allowed when a lint policy is set to "<policy>"The env sets lint { review }, which decides the approval: remove auto-approve: true (references/declarative.md)
exec: "docker": executable file not found in $PATHNo Docker where the step runs: use a service container dev database
role "..." already exists on a later stepA shared service-container dev database keeps roles: separate the steps
Failed to download atlas-action binary from all sourcesAllow atlasbinaries.com and release.ariga.io, or build with ariga/atlas-action/setup
create-repo rejects type: migrationThe CLI takes migration_directory (or m) and schema (or s); it fails if the repo exists
required input "cloud-token" is missingmonitor/schema does not use setup-atlas's login: pass it cloud-token
security/scan passes with CVEs reportedBy design: set fail-on to the severity that must fail the job
Bitbucket pipe runs an old binaryUse arigaio/atlas-action:v1 or a release tag, not master or latest
latest tag does not move on Azure DevOps, Bitbucket, or the orb's schema_pushSet latest: true (Bitbucket: ATLAS_INPUT_LATEST: "true")
How to fail CI when a migration was not generatedatlas migrate diff --env ci, then fail on git status --porcelain (references/diff.md)
Lint, test, or plan reports on GitLab merge requestsgitlab-token input, and run in merge request pipelines (references/platforms.md)
Jenkins, TeamCity, Buildkite, or another CIRun the CLI in a script step: atlas login --token, then each command with --env (references/platforms.md)
A step is missing on the CircleCI orb or the Azure DevOps taskThey lag the release: run the step's CLI command in a script step (references/platforms.md)

Documentation

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/ariga/atlas/atlas-action">View atlas-action on skillZs</a>