Update the README.md file

README.md

@@ -1,19 +1,31 @@
-# Woodpecker CI plugin to publish Debian package on a Aptly repository
+# CI plugin to publish Debian package on a Aptly repository
 
-This docker image could be used as an Woodpecker CI plugin to publish one (or more) Debian package on a Aptly repository using its API.
+This docker image could be used as an Woodpecker CI plugin to publish one (or more) Debian package on a Aptly repository using its API. It also could be used with Gitlab CI to define a publishing job.
 
 This plugin will try to :
-- locate all `changes` files in the `dist` directory (that matched `source_name` if provided)
+- List all changes files in the specified directory and filter on the specified source package name (if specified)
-- extract files that are mentioned by the changes files and upload it using Aptly files API. Files are published on a subdirectory of the name of the source package
+- Iter on detected changes files and foreach of then:
-- include all processed changes files using Aplty repos API
+ - the changes file is parsed to detect the source package name, the distribution and included files
-- create a snapshot of the repository named using current datetime and repository name (format: `YYYYMMDD-HHMMSS-repo`) using Aptly snapshot API
+ - 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.
-- update the published snapshot of the repository using Aptly publish API
+ - 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).
 
 [![status-badge](https://ci.zionetrix.net/api/badges/bn8/aptly-publish/status.svg)](https://ci.zionetrix.net/bn8/aptly-publish)
 
 # Usage
 
-The below pipeline configuration demonstrates simple usage:
+## With Woodpecker CI
+
+The below pipeline configuration demonstrates simple usage as Woodpecker CI plugin:
 
 ```
 pipeline:
@@ -24,15 +36,66 @@ pipeline:
       api_username: myproject
       api_password:
         from_secret: aptly_api_password
-      repo_name: stable
+      prefix: debian
+      repo_component: main
+      repo_name: debian-stable-main
       path: dist
       source_name: myproject
+      max_retries: 2
 ```
 
 __Parameters:__
 - __api_url:__ Your Aptly API URL (required)
 - __api_username:__ Username to authenticate on your Aptly API (required)
 - __api_password:__ Password to authenticate on your Aptly API (required)
-- __repo_name:__ Repository name to publish on (optional, default: `stable`)
+- __prefix:__ The publishing prefix (optional, default: `.`)
+- __repo_component:__ The component name to publish on (optional, default: `main`)
+- __repo_name:__ 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:__ Path to the directory where files to publish are stored (optional, default: `dist`)
 - __source_name:__ Name of the source package to publish (optional, default: all `changes` files are will be publish)
+- __max_retries:__ The number of retry in case of error calling the Aptly API (optional, default: no retry)
+
+## With Gitlab CI
+
+The following pipeline configuration demonstrates a simple usage to build and publish a debian package:
+
+```
+stages:
+  - build
+  - publish
+
+build:
+  image: debian:11
+  stage: build
+  rules:
+    - if: $CI_COMMIT_TAG
+  script:
+    - ./build.sh
+  artifacts:
+    paths:
+      - dist/*
+
+publish:
+  image:
+    name: brenard/aptly-publish:latest
+    entrypoint: ["/bin/sh", "-c"]
+  stage: publish
+  variables:
+    APTLY_API_URL: "https://your.aptly.tld/api"
+    APTLY_API_USERNAME: myproject
+    APTLY_PREFIX: "debian"
+    APTLY_REPO_COMPONENT: "main"
+    APTLY_REPO_NAME: "debian-stable-main"
+    APTLY_PATH: "dist"
+    APTLY_SOURCE_NAME: "myproject"
+    APTLY_MAX_RETRIES: 2
+  script:
+    - echo "Publish Bullseye debian packages on APT repository..."
+    - aptly-publish
+  needs:
+    - 'build'
+  rules:
+    - if: $CI_COMMIT_TAG
+```
+
+The parameters are passed using environment variables as designed with a Woodpecker CI plugin. Consequently, you could refer to the previous section for details about these parameters. For the password to request Aptly API, you have to set the `APTLY_API_PASSWORD` CI variable in your Gitlab project configuration (be sure to check _Masked variable_).