readme: basic docs (#7)

Author: rotemtam

README.md

@@ -1,2 +1,76 @@
 # atlas-deploy-action
-A GitHub Action to deploy schema migrations with Atlas
+
+A GitHub Action to deploy versioned migrations with [Atlas](https://atlasgo.io).
+
+## Supported 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 
+
+### Local Workflow
+
+```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
+```
+
+### Cloud Workflow
+
+```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.
+
+## License
+
+This project is licensed under the [Apache License, Version 2.0](LICENSE).

action.yml

@@ -7,11 +7,29 @@ inputs:
   url:
     description: 'URL to target database (should be passed as a secret).'
     required: true
+  dir:
+    description: 'Local path of the migration directory in the repository'
+    required: false
   cloud-token:
     description: 'Token for using Atlas Cloud (should be passed as a secret).'
     required: false
   cloud-dir:
     description: 'Name of the migration directory in the cloud'
+    required: false
+  cloud-tag:
+    description: 'Optional. Tag of a migration version in the cloud'
+    required: false
+outputs:
+  error:
+    description: 'Error message if any'
+  current:
+    description: 'Current migration version'
+  target:
+    description: 'Target migration version'
+  pending_count:
+    description: 'Number of pending migrations'
+  applied_count:
+    description: 'Number of applied migrations'
 runs:
   using: 'docker'
   image: 'docker://arigaio/atlas-deploy-action:latest'

main.go

@@ -100,6 +100,7 @@ func Load(act *githubactions.Action) (*Input, error) {
 		return nil, fmt.Errorf("cloud-token is required when cloud-dir is set")
 	}
 	i.Cloud.URL = act.GetInput("cloud-url")
+	i.Cloud.Tag = act.GetInput("cloud-tag")
 	return i, nil
 }
 

main_test.go

@@ -113,12 +113,14 @@ func TestLoad(t *testing.T) {
 				"INPUT_URL":         "sqlite://file.db",
 				"INPUT_CLOUD-DIR":   "dir",
 				"INPUT_CLOUD-TOKEN": "token",
+				"INPUT_CLOUD-TAG":   "tag",
 			},
 			expect: &Input{
 				URL: "sqlite://file.db",
 				Cloud: Cloud{
 					Token: "token",
 					Dir:   "dir",
+					Tag:   "tag",
 				},
 			},
 		},