docs/md: updating github actions page (#1919)

ariga · Jul 31, 2023 · a10c4fc · a10c4fc
1 parent 5d6b54d
commit a10c4fc
Showing 1 changed file with 149 additions and 2 deletions.
diff --git a/doc/md/integrations/github-actions.mdx b/doc/md/integrations/github-actions.mdx
@@ -17,7 +17,17 @@ One of the powerful features of GitHub Actions is its extensibility: it is
 very easy to package a piece of functionality as a module (called an "action")
 that can later be re-used by many projects. 
 
-## CI for database schema changes
+Atlas provides a number of GitHub Actions that can be used to automate
+database schema management tasks.
+
+| Action                                                | Use Case                                            |
+|-------------------------------------------------------|-----------------------------------------------------|
+| [ariga/atlas-action](https://github.com/ariga/atlas-action)        | CI for schema changes                               |
+| [ariga/atlas-sync-action](https://github.com/ariga/atlas-sync-action)   | Sync your migration directory to Atlas Cloud (atlasgo.cloud) |
+| [ariga/atlas-deploy-action](https://github.com/ariga/atlas-deploy-action) | Deploy versioned migrations from GitHub Actions    |
+
+
+## `ariga/atlas-action` (CI)
 
 Teams using GitHub that wish to ensure all changes to their database schema are safe
 can use the [`atlas-action`](https://github.com/ariga/atlas-action) GitHub Action.
@@ -218,4 +228,141 @@ be checked out locally or you will see an error such as:
 Atlas failed with code 1: Error: git diff: exit status 128
 ```
 
-The full list of input options can be found in [action.yml](https://github.com/ariga/atlas-action/blob/master/action.yml).
+The full list of input options can be found in [action.yml](https://github.com/ariga/atlas-action/blob/master/action.yml).
+
+## `ariga/atlas-deploy-action`
+
+You can use [ariga/atlas-deploy-action](https://github.com/ariga/atlas-deploy-action) to deploy migrations to your database directly from
+GitHub Actions.
+
+:::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 enabled
+network access to it from your GitHub Actions runners.
+
+:::
+
+This action supports two workflows:
+
+- *Local* - the migration directory is checked in to the repository.
+- *Cloud* - the migration directory is [connected to Atlas Cloud](https://atlasgo.io/cloud/directories).
+Runs are reported to your Atlas Cloud account.
+
+### Examples
+
+
+Notice that the following examples rely on a `DATABASE_URL` secret being set in your repository.
+
+To learn how to set secrets, read [GitHub's documentation](https://docs.github.com/en/actions/reference/encrypted-secrets).
+
+The `DATABASE_URL` secret should be set to the URL of your database, for examples please see [Atlas URL formats](/concepts/url).
+
+#### Local
+
+```yaml
+name: Deploy Database Migrations
+on:
+  push:
+    branches:
+      - master
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Deploy Atlas Migrations
+        uses: ariga/atlas-deploy-action@v0
+        with:
+          url: ${{ secrets.DATABASE_URL }}
+          dir: path/to/migrations
+```
+
+#### Deploy from Cloud
+
+```yaml
+name: Deploy Database Migrations
+on:
+  push:
+    branches:
+      - master
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Deploy Atlas Migrations
+        uses: ariga/atlas-deploy-action@v0
+        with:
+          url: ${{ secrets.DATABASE_URL }}
+          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
+          cloud-dir: hello # replace with your directory name
+```
+
+### Reference
+
+#### Inputs
+
+- `url`: URL to target database (should be passed as a secret). (Required)
+- `dir`: Local path of the migration directory in the repository. (Optional)
+- `cloud-token`: Token for using Atlas Cloud (should be passed as a secret). (Optional)
+- `cloud-dir`: Name of the migration directory in the cloud. (Must be set if `cloud-token` is set)
+- `cloud-tag`: Tag of the migration version in the cloud. (Optional)
+
+Note: Either `dir` or `cloud-dir` must be set. If both are provided, an error will be thrown.
+
+#### Outputs
+
+- `error`: Error message if any.
+- `current`: Current migration version.
+- `target`: Target migration version.
+- `pending_count`: Number of pending migrations.
+- `applied_count`: Number of applied migrations.
+
+## `ariga/atlas-sync-action`
+
+You can use [ariga/atlas-sync-action](https://github.com/ariga/atlas-sync-action) to sync your
+migration directory from your GitHub repository to [Atlas Cloud](https://atlasgo.cloud).
+
+Use this action in your workflow to sync your migration directory to Atlas Cloud.
+It is highly recommended that you only run this action on the main branch of your repository,
+as its purpose is to persist the desired state of your migration directory.
+
+To use this action, you must first have a Bot Token with permissions to write to your
+account. To learn how to create tokens, read [Atlas Cloud Bots](/cloud/bots).
+
+### Example
+
+```yaml
+name: Sync Atlas Migrations
+on:
+  push:
+    branches:
+      - master # Only run on our main branch
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ariga/atlas-sync-action@v0
+        with:
+          dir: path/to/migrations
+          driver: mysql # or: postgres | sqlite
+          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
+```
+
+### Reference
+
+Configure this action with the following inputs:
+
+#### `dir`
+
+**Required** The path to the directory containing your migrations.
+
+#### `driver`
+
+**Required** The database driver to use. One of: `mysql`, `postgres`, `sqlite`.
+
+#### `cloud-token`
+
+**Required** The Atlas Cloud token to use for authentication.