Skip to content

Commit 2701391

Browse files
appleboyappleboy
committed
docs: overhaul documentation for CI compatibility and enhanced usability
- Expand documentation to formally support GitHub Actions alongside Drone and Woodpecker - Add detailed table of contents for easier navigation - Introduce a features section highlighting plugin capabilities - List supported CI platforms and their compatibility - Add extensive usage examples for Drone, Woodpecker, and GitHub Actions - Document available parameters and authentication methods - Improve build and Docker instructions for clarity and multi-arch support - Update license section for consistency in all language variants Signed-off-by: appleboy <appleboy.tw@gmail.com>
1 parent 282cb78 commit 2701391

3 files changed

Lines changed: 525 additions & 69 deletions

File tree

‎README.md‎

Lines changed: 175 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -9,30 +9,192 @@
99
[![Go Report Card](https://goreportcard.com/badge/github.com/appleboy/drone-git-push)](https://goreportcard.com/report/github.com/appleboy/drone-git-push)
1010
[![Docker Pulls](https://img.shields.io/docker/pulls/appleboy/drone-git-push.svg)](https://hub.docker.com/r/appleboy/drone-git-push/)
1111

12-
[Drone](https://www.drone.io/) / [Woodpecker](https://woodpecker-ci.org/) plugin to push changes to a remote `git` repository.
13-
For the usage information and a listing of the available options please take a look at [the docs](DOCS.md).
12+
A CI/CD plugin for [Drone](https://www.drone.io/), [Woodpecker](https://woodpecker-ci.org/), and [GitHub Actions](https://github.com/features/actions) to push changes to a remote Git repository.
1413

15-
## Build
14+
## Table of Contents
1615

17-
Build the binary with the following commands:
16+
- [drone-git-push](#drone-git-push)
17+
- [Table of Contents](#table-of-contents)
18+
- [Features](#features)
19+
- [Supported Platforms](#supported-platforms)
20+
- [Usage](#usage)
21+
- [Drone / Woodpecker](#drone--woodpecker)
22+
- [GitHub Actions](#github-actions)
23+
- [Parameter Reference](#parameter-reference)
24+
- [Authentication](#authentication)
25+
- [SSH Key](#ssh-key)
26+
- [HTTPS with Username/Password](#https-with-usernamepassword)
27+
- [Build from Source](#build-from-source)
28+
- [Run with Docker](#run-with-docker)
29+
- [License](#license)
30+
31+
## Features
32+
33+
- Push commits to remote repositories via SSH or HTTPS
34+
- Mirror all refs to a remote repository
35+
- Auto-commit dirty changes before pushing
36+
- Tag support with follow-tags option
37+
- Rebase before push
38+
- Force push support
39+
- Custom commit messages
40+
- Empty commit support
41+
- Git LFS support
42+
43+
## Supported Platforms
44+
45+
| CI Platform | Status |
46+
| -------------- | --------------- |
47+
| Drone | Fully supported |
48+
| Woodpecker | Fully supported |
49+
| GitHub Actions | Fully supported |
50+
51+
## Usage
52+
53+
### Drone / Woodpecker
54+
55+
Basic push to a remote branch:
56+
57+
```yaml
58+
- name: push commit
59+
image: appleboy/drone-git-push
60+
settings:
61+
branch: master
62+
remote: git@github.com:foo/bar.git
63+
ssh_key:
64+
from_secret: deploy_key
65+
```
66+
67+
Push with commit changes:
68+
69+
```yaml
70+
- name: push commit
71+
image: appleboy/drone-git-push
72+
settings:
73+
branch: master
74+
remote: git@github.com:foo/bar.git
75+
force: false
76+
commit: true
77+
commit_message: "[skip ci] Update generated files"
78+
ssh_key:
79+
from_secret: deploy_key
80+
```
81+
82+
Push to the current repository:
83+
84+
```yaml
85+
- name: push commit
86+
image: appleboy/drone-git-push
87+
settings:
88+
remote_name: origin
89+
branch: gh-pages
90+
local_ref: gh-pages
91+
```
92+
93+
Mirror all refs to a remote repository:
94+
95+
```yaml
96+
- name: mirror push
97+
image: appleboy/drone-git-push
98+
settings:
99+
remote: git@github.com:foo/bar-mirror.git
100+
mirror: true
101+
ssh_key:
102+
from_secret: deploy_key
103+
```
104+
105+
Push with tagging:
106+
107+
```yaml
108+
- name: push with tag
109+
image: appleboy/drone-git-push
110+
settings:
111+
branch: master
112+
remote: git@github.com:foo/bar.git
113+
commit: true
114+
tag: v1.0.0
115+
followtags: true
116+
ssh_key:
117+
from_secret: deploy_key
118+
```
119+
120+
### GitHub Actions
121+
122+
```yaml
123+
- name: Push changes
124+
uses: appleboy/drone-git-push@master
125+
with:
126+
remote: git@github.com:foo/bar.git
127+
branch: master
128+
ssh_key: ${{ secrets.DEPLOY_KEY }}
129+
```
130+
131+
## Parameter Reference
132+
133+
| Parameter | Description | Default |
134+
| ---------------- | ------------------------------------------ | ------------------------------ |
135+
| `ssh_key` | Private SSH key for the remote machine | - |
136+
| `remote` | Target remote repository URL | - |
137+
| `remote_name` | Name of the remote to use locally | `deploy` |
138+
| `branch` | Target remote branch | `master` |
139+
| `local_branch` | Local branch or ref to push | `HEAD` |
140+
| `path` | Path to git repository | Current directory |
141+
| `force` | Force push using `--force` flag | `false` |
142+
| `skip_verify` | Skip verification of HTTPS certs | `false` |
143+
| `commit` | Add and commit the contents before pushing | `false` |
144+
| `commit_message` | Custom commit message | `[skip ci] Commit dirty state` |
145+
| `empty_commit` | Create an empty commit | `false` |
146+
| `no_verify` | Bypass pre-commit and commit-msg hooks | `false` |
147+
| `tag` | Tag to add to the commit | - |
148+
| `followtags` | Push with `--follow-tags` option | `false` |
149+
| `rebase` | Pull `--rebase` before pushing | `false` |
150+
| `mirror` | Push all refs with `--mirror` | `false` |
151+
| `author_name` | Author name for the commit | CI commit author |
152+
| `author_email` | Author email for the commit | CI commit author email |
153+
154+
## Authentication
155+
156+
### SSH Key
157+
158+
Provide a private SSH key for authentication:
159+
160+
```yaml
161+
settings:
162+
ssh_key:
163+
from_secret: deploy_key
164+
```
165+
166+
### HTTPS with Username/Password
167+
168+
Use netrc credentials for HTTPS authentication:
169+
170+
```yaml
171+
settings:
172+
username:
173+
from_secret: git_username
174+
password:
175+
from_secret: git_password
176+
```
177+
178+
## Build from Source
179+
180+
Build the binary:
18181

19182
```sh
20183
go build
21184
go test
22185
```
23186

24-
## Docker
25-
26-
Build the docker image with the following commands:
187+
Build Docker image:
27188

28189
```sh
190+
# Build for Linux amd64
29191
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -a -tags netgo -o release/linux/amd64/drone-git-push
30-
docker build --rm -t appleboy/drone-git-push .
31-
```
32192
33-
## Usage
193+
# Build Docker image
194+
docker build --rm -t appleboy/drone-git-push -f docker/Dockerfile .
195+
```
34196

35-
Execute from the working directory:
197+
## Run with Docker
36198

37199
```sh
38200
docker run --rm \
@@ -47,16 +209,6 @@ docker run --rm \
47209
appleboy/drone-git-push
48210
```
49211

50-
Mirror all refs to a remote repository:
212+
## License
51213

52-
```sh
53-
docker run --rm \
54-
-e DRONE_COMMIT_AUTHOR=Octocat \
55-
-e DRONE_COMMIT_AUTHOR_EMAIL=octocat@github.com \
56-
-e PLUGIN_SSH_KEY="$(cat "${HOME}/.ssh/id_rsa")" \
57-
-e PLUGIN_REMOTE=git@github.com:foo/bar.git \
58-
-e PLUGIN_MIRROR=true \
59-
-v "$(pwd):$(pwd)" \
60-
-w "$(pwd)" \
61-
appleboy/drone-git-push
62-
```
214+
MIT License - see the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)