From e7b4cfda7ab533becdc6df92b5bf3f8ac425f3f0 Mon Sep 17 00:00:00 2001 From: Benjamin Renard Date: Tue, 3 Jan 2023 01:14:13 +0100 Subject: [PATCH] Add doc file designed to be used to reference the plugin on the Woodpecker CI website --- docs.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs.md diff --git a/docs.md b/docs.md new file mode 100644 index 0000000..d3fe381 --- /dev/null +++ b/docs.md @@ -0,0 +1,65 @@ +--- +name: Aptly +icon: https://www.aptly.info/img/logo.svg +description: plugin to publish Debian package on a Aptly repository +authors: Benjamin Renard +tags: [APT, aptly, publish] +containerImage: brenard/aptly-publish +containerImageUrl: https://hub.docker.com/r/brenard/aptly-publish +url: https://gitea.zionetrix.net/bn8/aptly-publish +--- + +Woodpecker CI plugin to publish one (or more) Debian package on a Aptly repository using its API. + +## Features + +This plugin will try to : +- List all changes files in the specified directory and filter on the specified source package name (if specified) +- Iter on detected changes files and foreach of then: + - the changes file is parsed to detect the source package name, the distribution and included files + - the repository name is computed (if not specified). __Format:__ `{prefix}_{distribution}_{component}`. __Note:__ if the default prefix is specified (`.`), it will not be used to compute the repository name. + - the current published distribution is retreived using APTLY Publish API to: + - check it was already manally published a first time + - check it used a snapshot kind of sources + - retreive other components source snapshot + - Upload the changes file and all its included files using APTLY File Upload API in a directory named as the source package + - Include the changes file using APTLY Local Repos API + - Compute a snapshot name for the repository based on the current date and the repository name. __Format:__ `YYYYMMDD-HHMMSS_{repository name}` + - Create a snapshot of the repository using APTLY Local Repos API + - Update the published distribution with this new snapshot as source of the specified component and keeping other components source snapshot. + +In case of error, it will exit with a detailed error message (within the limits of what is provided by the Aptly API). + +## Settings + +| Settings Name | Default | Description +| --------------------------| ----------------- | -------------------------------------------- +| `api_url` | *none* | Your Aptly API URL (required) +| `api_username` | *none* | Username to authenticate on your Aptly API (required) +| `api_password` | *none* | Password to authenticate on your Aptly API (required) +| `prefix` | `.` | The publishing prefix +| `repo_component` | `main` | The component name to publish on +| `repo_name` | `{prefix}_{distribution}_{component}` | The repository name to publish on. If not specified, it will be computed using the specified prefix and component and the detected package distribution. See above for details. +| `path` | `dist` | Path to the directory where files to publish are stored +| `source_name` | *none* | Name of the source package to publish (optional, default: all `changes` files are will be publish) +| `max_retries` | *none* | The number of retry in case of error calling the Aptly API (optional, default: no retry) + + +## Example + +```yaml +pipeline: + publish: + image: brenard/aptly-publish + settings: + api_url: https://your.aptly.tld/api + api_username: myproject + api_password: + from_secret: aptly_api_password + prefix: debian + repo_component: main + repo_name: debian_stable_main + path: dist + source_name: myproject + max_retries: 2 +```