Skip to main content

GitLab CI Components

GitLab CI is an automation tool integrated into GitLab that helps streamline code testing, building, and deployment through configurable pipelines. Using a .gitlab-ci.yml file, developers define jobs and stages that GitLab executes automatically, enabling consistent integration and delivery workflows.

Atlas provides CI/CD components for easy integration in any project. Click here to see the full list of components in the CI/CD catalog.

Check out this guide for full examples of the versioned and declarative flows using the GitLab components.

info

To use the components in a self-hosted instance, you must mirror the component project.

migrate-push​

Pushes a migration directory to the cloud.

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-push@~latest
    inputs:
      stage: push
      branches:
        - main
      dir: "file://migrations"
      dir-name: "my-project"
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • working-directory - (Optional) Atlas working directory, default is project root
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
  • dir - The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name - (Optional) The name (slug) of the project in Atlas Cloud.
  • tag - (Optional) The tag to apply to the pushed migration directory. By default the current git commit hash is used.
  • latest - (Optional) If true, push also the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

migrate-lint​

Use this component to lint new migration files in any merge request.

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - lint

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-lint@~latest
    inputs:
      stage: lint
      dir: "file://migrations"
      dir-name: "my-project"
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root.
  • stage - (Optional) The CI stage to run the job in.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about here.
  • dir - (Optional) The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name: The name (slug) of the project in Atlas Cloud.
  • atlas-cloud-token- (Optional) A token for Atlas Cloud.
  • atlas-version: The version of Atlas to install.
  • gitlab-token- (Optional) A GitLab access token for posting merge request comments.

migrate-apply​

Use this component to deploy migration files to your database directly from your CI runner. You can either deploy a local directory (i.e from your git repository) or a directory stored in Atlas Cloud.

info

Atlas needs network access to your database to deploy migrations, so make sure your database is either publicly accessible or that you have otherwise running this component from a runner that has network access to your database.

Usage​

Deploy a directory from the git repository​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      dir: "file://migrations"
      url: $DATABASE_URL

Deploy a directory from the cloud​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      dir: "atlas://my-project"
      url: $DATABASE_URL
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • url - (Optional) The URL of the target database to apply changes to. For example: mysql://root:pass@localhost:3306/prod.
  • dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
  • dry-run - (Optional) If true, print SQL without executing it.
  • revisions-schema - (Optional) The name of the schema containing the revisions table.
  • atlas-cloud-token - (Optional) A token for Atlas Cloud.
  • atlas-version - Install a specific Atlas version.

schema-plan​

Creates a plan for a declarative schema change. Read more about pre-planning schema changes here.

To enable Atlas comments on merge requests, you need create an access token with appropriate role and permissions, set it as a CI/CD variable and pass it to the component in the "gitlab-token" input. See the usage example below:

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - plan

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-plan@~latest
    inputs:
      stage: plan
      env: dev
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN
      gitlab-token: $GITLAB_TOKEN

Inputs​

  • stage - (Optional) The CI stage to run the job in.
  • working-directory - (Optional) Atlas working directory, default is project root
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
  • dir - The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name - (Optional) The name (slug) of the project in Atlas Cloud.
  • tag - (Optional) The tag to apply to the pushed migration directory. By default the current git commit hash is used.
  • latest - (Optional) If true, push also the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.
  • gitlab-token- (Optional) A GitLab access token for posting merge request comments.

schema-plan-approve​

Approves a pending plan in Atlas Cloud for a specific change (i.e. the diff between the current and desired states). Run this job on the main branch of your project to automatically approve plans that were generated by the schema-plan job in previous merge requests.

If more than one pending plan is found for a given change, the job will exit with a non-zero code. In this case you will need to Choose the prefered plan and delete the others, before re-runnig the job.

Usage​

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-plan-approve@~latest
    inputs:
        stage: push
        branches:
            - main
        env: gitlab
        atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: https://atlasgo.io/registry.
  • from - (Optional) URL(s) of the current schema state.
  • to - (Optional) URL(s) of the desired schema state.
  • plan - (Optional) The URL of the plan to be approved. For example, atlas://<schema>/plans/<id>. If not provided, Atlas will search the registry for a plan corresponding to the given schema transition and approve it (typically, this plan is created during the PR stage). If multiple plans are found, an error will be thrown.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

schema-push​

Pushes a declarative schema to the cloud.

Usage​

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-push@~latest
    inputs:
      stage: push
      branches:
        - main
      env: dev
      latest: true
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: https://atlasgo.io/registry.
  • url - (Optional) Desired schema URL(s) to push. For example: file://schema.hcl.
  • schema - (Optional) List of database schema(s). For example: public.
  • description - (Optional) The description of the schema.
  • latest - (Optional) If true, push also to the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) a specific Atlas version.

schema-apply​

Use this component to apply a schema to your database directly from your CI runner. You can either deploy a local state (i.e from your git repository) or a schema stored in Atlas Cloud.

info

Atlas needs network access to your database to deploy migrations, so make sure your database is either publicly accessible or that you have otherwise running this component from a runner that has network access to your database.

Usage​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      env: dev
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN # Needed only for deploying a schema from Atlas Cloud.

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: https://atlasgo.io/registry.
  • to - (Optional) URL(s) of the desired schema state.
  • url - (Optional) The URL of the target database to apply changes to. For example: mysql://root:pass@localhost:3306/prod.
  • schema - (Optional) List of database schema(s). For example: public.
  • dry-run - (Optional) If true, print SQL without executing it.
  • auto-approve - (Optional) If true, automatically approve and apply changes.
  • plan - (Optional) The plan to apply. For example, atlas://<schema>/plans/<id>.
  • atlas-cloud-token - (Optional) A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.