doc: add new plan commands to readme

README.md

@@ -9,15 +9,19 @@ To learn more about the recommended way to build workflows, read our guide on
 
 ## Actions
 
-| Action | Description |
-|--------------------------------------------------------------------|---------------------------------------------------------|
-| [ariga/setup-atlas](#arigasetup-atlas) | Setup the Atlas CLI and optionally login to Atlas Cloud |
-| [ariga/atlas-action/migrate/push](#arigaatlas-actionmigratepush) | Push migrations to Atlas Cloud |
-| [ariga/atlas-action/migrate/lint](#arigaatlas-actionmigratelint) | Lint migrations (required `atlas login` ) |
-| [ariga/atlas-action/migrate/apply](#arigaatlas-actionmigrateapply) | Apply migrations to a database |
-| [ariga/atlas-action/migrate/down](#arigaatlas-actionmigratedown) | Revert migrations to a database |
-| [ariga/atlas-action/migrate/test](#arigaatlas-actionmigratetest) | Test migrations on a database |
-| [ariga/atlas-action/schema/test](#arigaatlas-actionschematest) | Test schema on a database |
+| Action | Description |
+|-------------------------------------------------------------------------------|------------------------------------------------------------------|
+| [ariga/setup-atlas](#arigasetup-atlas) | Setup the Atlas CLI and optionally login to Atlas Cloud |
+| [ariga/atlas-action/migrate/push](#arigaatlas-actionmigratepush) | Push migrations to [Atlas Registry](https://atlasgo.io/registry) |
+| [ariga/atlas-action/migrate/lint](#arigaatlas-actionmigratelint) | Lint migrations (required `atlas login` ) |
+| [ariga/atlas-action/migrate/apply](#arigaatlas-actionmigrateapply) | Apply migrations to a database |
+| [ariga/atlas-action/migrate/down](#arigaatlas-actionmigratedown) | Revert migrations to a database |
+| [ariga/atlas-action/migrate/test](#arigaatlas-actionmigratetest) | Test migrations on a database |
+| [ariga/atlas-action/schema/test](#arigaatlas-actionschematest) | Test schema on a database |
+| [ariga/atlas-action/schema/push](#arigaatlas-actionschemapush) | Push a schema to [Atlas Registry](https://atlasgo.io/registry) |
+| [ariga/atlas-action/schema/plan](#arigaatlas-actionschemaplan) | Plan a declarative migration for a schema transition |
+| [ariga/atlas-action/schema/plan/approve](#arigaatlas-actionschemaplanapprove) | Approve a declarative migration plan |
+| [ariga/atlas-action/schema/apply](#arigaatlas-actionschemaapply) | Apply a declarative migrations to a database |
 
 ## Examples
 
@@ -294,7 +298,7 @@ All inputs are optional as they may be specified in the Atlas configuration file
 
 ### `ariga/atlas-action/migrate/test`
 
-Test migrations on a database.
+Run schema migration tests. Read more in [Atlas website](https://atlasgo.io/testing/migrate).
 
 #### Inputs
 
@@ -316,7 +320,7 @@ All inputs are optional as they may be specified in the Atlas configuration file
 
 ### `ariga/atlas-action/schema/test`
 
-Test schema on a database.
+Run schema tests on the desired schema. Read more in [Atlas website](https://atlasgo.io/testing/schema).
 
 #### Inputs
 
@@ -335,6 +339,109 @@ All inputs are optional as they may be specified in the Atlas configuration file
  For example: `'{"var1": "value1", "var2": "value2"}'`.
 * `working-directory` - The working directory to run from. Defaults to project root.
 
+### `ariga/atlas-action/schema/apply`
+
+Apply a declarative migrations to a database.
+
+#### Inputs
+
+* `to` - The URL(s) of the desired schema state.
+* `plan` - Optional plan file to use for applying the migrations. For example: `atlas://<schema>/plans/<id>`.
+* `dry-run` - Print SQL (and optional analysis) without executing it. Either `true` or `false`. Defaults to `false`.
+* `auto-approve` - Automatically approve and apply changes. Either `true` or `false`. Defaults to `false`.
+* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`.
+ Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
+* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file
+ named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`.
+ Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects).
+* `env` - The environment to use from the Atlas configuration file. For example, `dev`.
+* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file.
+ For example: `'{"var1": "value1", "var2": "value2"}'`.
+* `working-directory` - The working directory to run from. Defaults to project root.
+
+#### Outputs
+
+* `error` - The error message if the action fails.
+
+### `ariga/atlas-action/schema/push`
+
+Push a schema to [Atlas Registry](https://atlasgo.io/registry) with an optional tag.
+
+#### Inputs
+
+* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
+* `tag` - The tag to apply to the pushed schema. By default, the current git commit hash is used.
+* `latest` - Whether to implicitly push the `latest` tag. True by default.
+* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`.
+ Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
+* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file
+ named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`.
+ Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects).
+* `env` - The environment to use from the Atlas configuration file. For example, `dev`.
+* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file.
+ For example: `'{"var1": "value1", "var2": "value2"}'`.
+* `working-directory` - The working directory to run from. Defaults to project root.
+
+#### Outputs
+
+* `slug` - The slug of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
+* `link` - The URL of the schema in [Atlas Registry](https://atlasgo.io/registry).
+* `url` - The URL of the pushed schema version in Atlas format. For example, `atlas://app`.
+
+### `ariga/atlas-action/schema/plan`
+
+Plan a declarative migration for a schema transition.
+
+#### Inputs
+
+* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
+* `from` - URL(s) of the current schema state to transition from.
+* `to` - URL(s) of the desired schema state to transition to.
+* `name` - Optional name for the plan. If not provided, a default plan is generated by Atlas.
+* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`.
+ Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
+* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file
+ named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`.
+ Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects).
+* `env` - The environment to use from the Atlas configuration file. For example, `dev`.
+* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file.
+ For example: `'{"var1": "value1", "var2": "value2"}'`.
+* `working-directory` - The working directory to run from. Defaults to project root.
+
+#### Outputs
+
+* `plan` - The URL of the generated plan in Atlas format. For example, `atlas://app/plans/123`.
+* `link` - The URL of the plan in [Atlas Registry](https://atlasgo.io/registry).
+* `status` - The status of the plan. For example, `PENDING` or `APPROVED`.
+
+### `ariga/atlas-action/schema/plan/approve`
+
+Approve a declarative migration plan.
+
+#### Inputs
+
+* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
+* `from` - URL(s) of the current schema state to transition from.
+* `to` - URL(s) of the desired schema state to transition to.
+* `plan` - Optional URL of the plan to be approved. For example, `atlas://<schema>/plans/<id>`. By default, Atlas
+ searches in the registry for a plan corresponding to the given schema transition and approves it (typically, this plan
+ is created during the PR stage). If multiple plans are found, an error will be thrown.
+* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`.
+ Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
+* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file
+ named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`.
+ Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects).
+* `env` - The environment to use from the Atlas configuration file. For example, `dev`.
+* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file.
+ For example: `'{"var1": "value1", "var2": "value2"}'`.
+* `working-directory` - The working directory to run from. Defaults to project root.
+
+#### Outputs
+
+* `plan` - The URL of the generated plan in Atlas format. For example, `atlas://app/plans/123`.
+* `link` - The URL of the plan in [Atlas Registry](https://atlasgo.io/registry).
+* `status` - The status of the plan. For example, `PENDING` or `APPROVED`.
+
 ### Legal 
 
 The source code for this GitHub Action is released under the Apache 2.0

atlasaction/action.go

@@ -93,7 +93,7 @@ type AtlasExec interface {
  SchemaApplySlice(context.Context, *atlasexec.SchemaApplyParams) ([]*atlasexec.SchemaApply, error)
 }
 
-// Context holds the context of the environment the action is running in.
+// TriggerContext holds the context of the environment the action is running in.
 type TriggerContext struct {
  SCM SCM // SCM is the source control management system.
  Repo string // Repo is the repository name. e.g. "ariga/atlas-action".

schema/apply/action.yml

@@ -31,7 +31,7 @@ inputs:
  URL(s) of the desired schema state.
  required: false
  plan:
- description: The plan to apply. (ig. `atlas://<schema>/plans/<id>`)
+ description: The plan to apply. For example, `atlas://<schema>/plans/<id>`.
  required: false
  dry-run:
  description: Print SQL without executing it. Either "true" or "false".

schema/plan/action.yml

@@ -47,7 +47,7 @@ outputs:
  link: # id of the output
  description: Link to the schema plan on Atlas.
  status:
- description: The status of the plan. (ig. `PENDING`, `APPROVED`)
+ description: The status of the plan. For example, `PENDING` or `APPROVED`.
 runs:
  using: node20
  main: index.js

schema/plan/approve/action.yml

@@ -29,6 +29,8 @@ inputs:
  plan:
  description: |
  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.
  required: false
  schema-name:
  description: The name (slug) of the project in Atlas Cloud.

schema/push/action.yml

@@ -27,7 +27,9 @@ inputs:
  Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
  required: false
  schema-name:
- description: The name (slug) of the project in Atlas Cloud.
+ description: |
+ The name (slug) of the schema repository in Atlas Registry.
+ Read more in Atlas website: https://atlasgo.io/registry.
  required: false
  description:
  description: The description of the schema changes.
@@ -37,8 +39,7 @@ inputs:
  required: false
  tag:
  description: |
- The tag to apply to the pushed migration directory. By default the
- current git commit hash is used.
+ The tag to apply to the pushed schema. By default, the current git commit hash is used.
  required: false
  latest:
  description: |