From 05857f9db34748d993d5c8f5157dc94c1a4deb25 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Mon, 28 Nov 2022 15:36:01 +0100 Subject: [PATCH] docs: add basic documentation (#3) --- _docs/content/_index.md | 76 ++++++++++++++++++++++++++++++++++ _docs/data/data.yaml | 75 +++++++++++++++++++++++++++++++++ cmd/drone-git-action/config.go | 24 +++++------ git/remote.go | 2 +- plugin/impl.go | 4 +- 5 files changed, 166 insertions(+), 15 deletions(-) create mode 100644 _docs/content/_index.md create mode 100644 _docs/data/data.yaml diff --git a/_docs/content/_index.md b/_docs/content/_index.md new file mode 100644 index 0000000..d8d2f45 --- /dev/null +++ b/_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. + + + +{{< toc >}} + + + +## 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 + + + +{{< propertylist name=drone-git-action.data sort=name >}} + + + +## 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 +``` diff --git a/_docs/data/data.yaml b/_docs/data/data.yaml new file mode 100644 index 0000000..44eef11 --- /dev/null +++ b/_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 diff --git a/cmd/drone-git-action/config.go b/cmd/drone-git-action/config.go index 4aeaa54..8321109 100644 --- a/cmd/drone-git-action/config.go +++ b/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, diff --git a/git/remote.go b/git/remote.go index a455b83..24a08a0 100644 --- a/git/remote.go +++ b/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) } diff --git a/plugin/impl.go b/plugin/impl.go index a12f1f6..f61d87f 100644 --- a/plugin/impl.go +++ b/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