Merge pull request #595 from iterate-ch/issue/12

Documentation for GitHub Action

cli/index.md

@@ -151,6 +151,33 @@ Packages can also be found for [download](https://dist.duck.sh/).
 ::::
 :::::
 
+### Docker Image
+
+_Cyberduck CLI_ is available as a [Docker Image](https://github.com/iterate-ch/cyberduck/pkgs/container/cyberduck). Install from the command line with
+
+    docker pull ghcr.io/iterate-ch/cyberduck:latest
+
+### GitHub Action
+
+_[Cyberduck CLI GitHub Action](https://github.com/iterate-ch/cyberduck-cli-action)_ is available for [GitHub Actions](https://github.com/features/actions). It runs Cyberduck CLI within a docker container. 
+
+    uses: iterate-ch/cyberduck-cli-action@v1
+    env:
+        USERNAME: <username>
+        PASSWORD: <password>
+        IDENTITY: <identity file>
+    with:
+        mode: list|longlist|upload|download|delete|purge|raw
+        url: <remote file or directory>
+        path: <local file or directory>
+        args: '<additional parameters>'
+
+:::{admonition} Tutorial
+:class: tip
+
+Follow the [step-by-step instructions](../tutorials/cli_github_action.md) to use the Cyberduck CLI GitHub Action.
+:::
+
 ## Usage
 
 `Usage:duck [options...]`
@@ -161,8 +188,7 @@ URLs in arguments must be fully qualified. You can reference files relative to y
 `/~ftps://[email protected]/~/`.
 
 :::{attention}
-Paths can either denote a remote file `ftps://[email protected]/resource` or folder `ftps://[email protected]/directory/`
-with a trailing `/`.
+Paths can either denote a remote file `ftps://[email protected]/resource` or folder `ftps://[email protected]/directory/` with a trailing `/`.
 :::
 
 ### Connection Profiles
@@ -408,6 +434,14 @@ You can move or rename remote files using the `--move` command. Use an absolute
 duck  --move protocol:/<folder>/<name> <file>
 ```
 
+### Copy files using `--copy`
+
+You can copy files using the `--copy` command. Use an absolute path for the target filename. Server-side [copy support](../cyberduck/copy.md#copy-files-and-folders-between-servers) is limited to some protocols.
+
+```{code-block}
+duck  --copy protocol:/<folder>/<name> <file>
+```
+
 ### Cryptomator
 
 Access to your [Cryptomator](../cryptomator/index.md) Vaults from the command line. When accessing a vault using

tutorials/cli_github_action.md

@@ -0,0 +1,43 @@
+Use Cyberduck CLI GitHub Action
+===
+
+Use Cyberduck CLI in a [GitHub Actions](https://docs.github.com/en/actions) workflow conveniently in a docker container.
+
+## Usage in Custom Workflow
+
+1. Add the `cyberduck-cli-action` action to a workflow `.yml` with a step like 
+
+   ```
+    - name: Upload
+      uses: iterate-ch/cyberduck-cli-action@v1
+      env:
+          USERNAME: ${{secrets.S3_ACCESS_KEY}}
+          PASSWORD: ${{secrets.S3_SECRET_KEY}}
+      with:
+          mode: upload
+          url: 's3:/bucket/path/'
+          path: 'release/*'
+          args: '--verbose'
+   ```    
+
+2. Choose a `mode`. Several modes are supported like `download`, `list` and `upload` probably the most common usage. If you want to any of the supported command line parameters use `raw` and omit the `path` and `url` options. 
+
+3. Set the `url` input option to a valid URI that references the protocol, optional server and destination upload file or directory as [documented](https://docs.duck.sh/cli/#uri). For [S3](https://docs.duck.sh/protocols/s3/) this would be `s3:/<bucket>/<key>` or for [SFTP](https://docs.duck.sh/protocols/sftp/) `sftp://<server>/<directory>/`. 
+
+    :::{attention}
+    Make sure to include a trailing `/` in `url` input to denote a directory.
+    :::
+
+4. Specify credentials in the environment with `USERNAME`, `PASSWORD`. Additionally `IDENTITY` can be used for SFTP connections equivalent to the `--identity` parameter. The example assumes you have `S3_ACCESS_KEY` and `S3_SECRET_KEY` defined as a [secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). Alternatively specify `--username ${{secrets.USER}} --password ${{secrets.PASSWORD}}` in `args`.
+
+5. Add additional arguments for Cyberduck CLI. Any of the available [generic options](https://docs.duck.sh/cli/#generic-options) can be passed with the `args` input.
+
+    :::{tip}
+    Only overwrite existing files on changes using  `args: '--existing compare'`.
+    :::
+
+6. Read output in a next step using the key `log` using `jobs.<job_id>.outputs.log` [output](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputsoutput_id).
+
+## References 
+
+* Cyberduck CLI GitHub Action [README](https://github.com/iterate-ch/cyberduck-cli-action/blob/main/README.md)

tutorials/index.md

@@ -9,6 +9,7 @@ custom_oauth_client_id
 iam
 vault_localdisk
 sftp_publickeyauth
+cli_github_action
 :::
 
 Find detailed step-by-step instructions for setup, connecting and most common use-cases as well as tutorials for more complicated workarounds.
@@ -26,4 +27,7 @@ IAM allows you to create credentials for third parties accessing your S3 account
 Both [Cyberduck](../cyberduck/index.md) and [Mountain Duck](../mountainduck/index.md) support accessing vaults on your local disk.
 
 ## [Configure Public Key Authentication for SFTP](sftp_publickeyauth.md)
-Configure Public Key Authentication for SFTP using OpenSSH tools.
+Configure Public Key Authentication for SFTP using OpenSSH tools.
+
+## [Use Cyberduck CLI GitHub Action](cli_github_action.md)
+Use Cyberduck CLI Docker Container in GitHub Actions