docs: add basic documentation (#3)

_docs/content/_index.md

@@ -0,0 +1,76 @@
+---
+title: drone-git-action
+---
+
+[![Build Status](https://img.shields.io/drone/build/thegeeklab/drone-git-action?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/drone-git-action)
+[![Docker Hub](https://img.shields.io/badge/dockerhub-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/thegeeklab/drone-git-action)
+[![Quay.io](https://img.shields.io/badge/quay-latest-blue.svg?logo=docker&logoColor=white)](https://quay.io/repository/thegeeklab/drone-git-action)
+[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/drone-git-action)](https://github.com/thegeeklab/drone-git-action/graphs/contributors)
+[![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/drone-git-action)
+[![License: MIT](https://img.shields.io/github/license/thegeeklab/drone-git-action)](https://github.com/thegeeklab/drone-git-action/blob/main/LICENSE)
+
+Drone plugin to execute git actions.
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< toc >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```YAML
+kind: pipeline
+name: default
+
+steps:
+  - name: commit artifact
+    image: thegeeklab/drone-git-action
+    settings:
+      netrc_password: ghp_3LbMg9Kncpdkhjp3bh3dMnKNXLjVMTsXk4sM
+      author_name: octobot
+      author_email: octobot@example.com
+      message: "[skip ci] update changelog"
+```
+
+### Parameters
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< propertylist name=drone-git-action.data sort=name >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+## Build
+
+Build the binary with the following command:
+
+```Shell
+export GOOS=linux
+export GOARCH=amd64
+export CGO_ENABLED=0
+export GO111MODULE=on
+
+make build
+```
+
+Build the Docker image with the following command:
+
+```Shell
+docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-git-action .
+```
+
+## Test
+
+```Shell
+docker run --rm \
+  -e DRONE_BUILD_EVENT=pull_request \
+  -e DRONE_REPO_OWNER=octocat \
+  -e DRONE_REPO_NAME=foo \
+  -e DRONE_PULL_REQUEST=1
+  -e PLUGIN_API_KEY=abc123 \
+  -e PLUGIN_MESSAGE="Demo comment" \
+  -v $(pwd):$(pwd) \
+  -w $(pwd) \
+  thegeeklab/drone-git-action
+```

_docs/data/data.yaml

@@ -0,0 +1,75 @@
+---
+properties:
+  - name: actions
+    description: "Git actions to to execute. Supported actions: `clone|commit|push`."
+    required: true
+    type: list
+
+  - name: author_name
+    description: Git author name.
+    required: true
+    type: string
+
+  - name: author_email
+    description: Git author Email Address.
+    required: true
+    type: string
+
+  - name: netrc_machine
+    description: Netrc remote machine name.
+    type: string
+
+  - name: netrc_username
+    description: Netrc login user on the remote machine.
+    type: string
+
+  - name: netrc_password
+    description: Netrc login password on the remote machine.
+    type: string
+
+  - name: ssh_key
+    description: SSH private key for the remote repository.
+    type: string
+
+  - name: remote
+    description: URL of the remote repository.
+    type: string
+
+  - name: branch
+    description: Name of the git branch.
+    defaultvalue: main
+    type: string
+
+  - name: path
+    description: Path to git repository.
+    type: string
+
+  - name: message
+    description: Commit message.
+    defaultvalue: "[skip ci] commit dirty state"
+    type: string
+
+  - name: force
+    description: Enable force push to remote repository.
+    defaultvalue: false
+    type: bool
+
+  - name: followtags
+    description: Push all the `refs` that would be pushed without this option, and also push annotated tags in `refs/tags` that are missing from the remote.
+    defaultvalue: false
+    type: bool
+
+  - name: skip_verify
+    description: Skip SSL verification of the remote machine.
+    defaultvalue: false
+    type: bool
+
+  - name: empty_commit
+    description: Allow empty commits. Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and those commits are not allowed by default.
+    defaultvalue: false
+    type: bool
+
+  - name: no_verify
+    description: Bypass the pre-commit and commit-msg hooks.
+    defaultvalue: false
+    type: bool

cmd/drone-git-action/config.go

@@ -10,7 +10,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 	return []cli.Flag{
 		&cli.StringSliceFlag{
 			Name:        "actions",
-			Usage:       "actions to execute",
+			Usage:       "git actions to to execute",
 			EnvVars:     []string{"PLUGIN_ACTIONS"},
 			Destination: &settings.Actions,
 			Required:    true,
@@ -36,28 +36,28 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 
 		&cli.StringFlag{
 			Name:        "netrc.machine",
-			Usage:       "netrc machine",
+			Usage:       "netrc remote machine name",
 			EnvVars:     []string{"PLUGIN_NETRC_MACHINE", "DRONE_NETRC_MACHINE"},
 			Destination: &settings.Netrc.Machine,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "netrc.username",
-			Usage:       "netrc username",
+			Usage:       "netrc login user on the remote machine",
 			EnvVars:     []string{"PLUGIN_NETRC_USERNAME", "DRONE_NETRC_USERNAME"},
 			Destination: &settings.Netrc.Login,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "netrc.password",
-			Usage:       "netrc password",
+			Usage:       "netrc login password on the remote machine",
 			EnvVars:     []string{"PLUGIN_NETRC_PASSWORD", "DRONE_NETRC_PASSWORD"},
 			Destination: &settings.Netrc.Password,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "ssh-key",
-			Usage:       "private ssh key",
+			Usage:       "ssh private key for the remote repository",
 			EnvVars:     []string{"PLUGIN_SSH_KEY"},
 			Destination: &settings.SSHKey,
 			Category:    category,
@@ -65,14 +65,14 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 
 		&cli.StringFlag{
 			Name:        "remote",
-			Usage:       "url of the repo",
+			Usage:       "url of the remote repository",
 			EnvVars:     []string{"PLUGIN_REMOTE"},
 			Destination: &settings.Remote,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "branch",
-			Usage:       "name of branch",
+			Usage:       "name of the git branch",
 			EnvVars:     []string{"PLUGIN_BRANCH"},
 			Destination: &settings.Branch,
 			Value:       "main",
@@ -81,7 +81,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 
 		&cli.StringFlag{
 			Name:        "path",
-			Usage:       "path to git repo",
+			Usage:       "path to git repository",
 			EnvVars:     []string{"PLUGIN_PATH"},
 			Destination: &settings.Path,
 			Category:    category,
@@ -98,21 +98,21 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 
 		&cli.BoolFlag{
 			Name:        "force",
-			Usage:       "force push to remote",
+			Usage:       "enable force push to remote repository",
 			EnvVars:     []string{"PLUGIN_FORCE"},
 			Destination: &settings.Force,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "followtags",
-			Usage:       "push to remote with tags",
+			Usage:       "follow tags for pushes to remote repository",
 			EnvVars:     []string{"PLUGIN_FOLLOWTAGS"},
 			Destination: &settings.FollowTags,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "skip-verify",
-			Usage:       "skip ssl verification",
+			Usage:       "skip ssl verification of the remote machine",
 			EnvVars:     []string{"PLUGIN_SKIP_VERIFY"},
 			Destination: &settings.SkipVerify,
 			Category:    category,
@@ -126,7 +126,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		},
 		&cli.BoolFlag{
 			Name:        "no-verify",
-			Usage:       "bypasses commit hooks",
+			Usage:       "bypass the pre-commit and commit-msg hooks",
 			EnvVars:     []string{"PLUGIN_NO_VERIFY"},
 			Destination: &settings.NoVerify,
 			Category:    category,

git/remote.go

@@ -27,7 +27,7 @@ func RemoteAdd(name, url string) *exec.Cmd {
 	return cmd
 }
 
-// RemotePush pushs the changes from the local head to a remote branch..
+// RemotePush pushs the changes from the local head to a remote branch.
 func RemotePush(remote, branch string, force, followtags bool) *exec.Cmd {
 	return RemotePushNamedBranch(remote, "HEAD", branch, force, followtags)
 }

plugin/impl.go

@@ -44,8 +44,8 @@ type Settings struct {
 
 // Validate handles the settings validation of the plugin.
 func (p *Plugin) Validate() error {
-	if (p.settings.SSHKey == "") && (p.settings.Netrc.Login == "" || p.settings.Netrc.Password == "") {
-		return fmt.Errorf("either SSH key or netrc username and password are required")
+	if p.settings.SSHKey == "" && p.settings.Netrc.Password == "" {
+		return fmt.Errorf("either SSH key or netrc password are required")
 	}
 
 	return nil