aptly-publish/README.md

160 lines
6.1 KiB
Markdown
Raw Normal View History

2022-12-13 21:20:16 +01:00
# CI plugin to publish Debian package on a Aptly repository
2022-05-02 16:12:52 +02:00
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 and Forgejo Actions to define a publishing job.
2022-05-02 16:12:52 +02:00
This plugin will try to :
2022-12-13 21:20:16 +01:00
- 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 retrieved using APTLY Publish API to:
- check it was already manally published a first time
- check it used a snapshot kind of sources
- retrieve 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.
2022-12-13 21:20:16 +01:00
In case of error, it will exit with a detailed error message (within the limits of what is provided by the Aptly API).
2022-05-02 16:12:52 +02:00
2022-05-02 16:15:10 +02:00
[![status-badge](https://ci.zionetrix.net/api/badges/bn8/aptly-publish/status.svg)](https://ci.zionetrix.net/bn8/aptly-publish)
2022-05-02 16:12:52 +02:00
# Usage
2022-12-13 21:20:16 +01:00
## With Woodpecker CI
The below pipeline configuration demonstrates simple usage as Woodpecker CI plugin:
2022-05-02 16:12:52 +02:00
```yaml
2022-05-02 16:12:52 +02:00
pipeline:
publish:
image: brenard/aptly-publish
settings:
api_url: https://your.aptly.tld/api
api_username: myproject
api_password:
from_secret: aptly_api_password
2022-12-13 21:20:16 +01:00
prefix: debian
repo_component: main
repo_name: debian_stable_main
2022-05-02 16:12:52 +02:00
path: dist
source_name: myproject
2022-12-13 21:20:16 +01:00
max_retries: 2
2023-07-19 19:25:29 +02:00
force_overwrite: true
2022-05-02 16:12:52 +02:00
```
**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)
- **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)
- **force_overwrite:** When publishing, overwrite files in `pool/` directory without notice (optional, default: false)
2022-12-13 21:20:16 +01:00
## With Gitlab CI
The following pipeline configuration demonstrates a simple usage to build and publish a debian package:
```yaml
2022-12-13 21:20:16 +01:00
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"
2022-12-13 21:20:16 +01:00
APTLY_PATH: "dist"
APTLY_SOURCE_NAME: "myproject"
APTLY_MAX_RETRIES: 2
2023-07-19 19:25:29 +02:00
APTLY_FORCE_OVERWRITE: true
2022-12-13 21:20:16 +01:00
script:
- echo "Publish Bullseye debian packages on APT repository..."
- aptly-publish
needs:
- "build"
2022-12-13 21:20:16 +01:00
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_).
## With Forgejo Actions
The following workflow configuration demonstrates a simple usage to build and publish a debian package:
```yaml
---
name: Build and publish forgejo-runner Debian package
on: [create]
jobs:
build:
steps:
- name: Check out repository code
uses: actions/checkout@v4
- name: Build Debian package
run: ./build.sh
- name: Upload Debian package files
uses: actions/upload-artifact@v3
with:
name: dist
path: |
dist/*.buildinfo
dist/*.changes
dist/*.deb
dist/*.dsc
dist/*.tar.gz
publish:
runs-on: docker
container:
image: docker.io/brenard/aptly-publish:latest
steps:
- name: "Download Debian package files"
uses: actions/download-artifact@v3
with:
name: dist
- name: "Publish Debian package on Aptly repository"
uses: https://gitea.zionetrix.net/bn8/aptly-publish@master
with:
api_url: https://your.aptly.tld/api
api_username: myproject
api_password: ${{ secrets.APTLY_API_PASSWORD }}
prefix: debian
repo_component: main
repo_name: debian_stable_main
path: "./"
source_name: myproject
max_retries: 2
force_overwrite: true
```
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` Actions secret in your Forgejo project configuration.