Skip to content

13 Integrations

This chapter summarizes common external systems that integrate with Athene and clarifies whether each system primarily produces packages, consumes packages, or does both.

13.1 Prerequisites

  • A running Athene server.
  • Repository authentication configured for non-local access.
  • At least one repository created and tested with a manual import.

13.2 Integration Roles at a Glance

  • Apt: consumer (installs packages from Athene).
  • RPM: consumer (installs packages from Athene via dnf/yum).
  • Maven: producer and consumer (publishes artifacts and resolves dependencies).
  • Files: producer and consumer (stores arbitrary files using configurable metadata-driven paths).
  • Jenkins: producer and consumer orchestrator (builds, publishes, and can also consume).
  • GitHub Actions: producer orchestrator (builds and publishes artifacts to Athene in CI workflows).
  • Sync Targets (S3/SFTP): distribution and replication destinations for repository export.
  • User Backend (LDAP): global user authentication source.
  • Jsign Signers (JKS/SPCPVK/SafeNet): signing providers used by Athene signer integrations.
  • Apple Codesign (rcodesign): Apple code-signing + notarization signer integration for files workflows.

Tip

You can view consumer setup instructions for each repository from the Browse feature in the Web User Interface.

13.3 Apt (Consumer)

Use Apt clients to consume Debian packages that Athene serves.

Typical flow:

  1. Configure your Apt source to point to the Athene Debian repository URL.
  2. Refresh package metadata with apt update.
  3. Install packages with apt install.

When repository authentication is enabled, provide credentials through supported transport/auth patterns for your environment.

Example /etc/apt/sources.list.d/athene.list:

deb [trusted=yes] http://localhost:19191/r/debian/main/ ./

Then refresh and install:

apt update
apt install my-package

Authenticated Apt example (/etc/apt/auth.conf.d/athene.conf):

machine localhost:19191
login alice
password <personal-access-token>

13.4 RPM (Consumer)

Use RPM clients to consume RPM packages that Athene serves.

Typical flow:

  1. Configure your dnf/yum repository definition to point to the Athene RPM repository URL.
  2. Refresh metadata with dnf makecache (or yum makecache).
  3. Install packages with dnf install (or yum install).

When repository authentication is enabled, provide credentials through supported transport/auth patterns for your environment.

Example /etc/yum.repos.d/athene.repo:

[athene-main]
name=Athene RPM Main
baseurl=http://localhost:19191/r/rpm/main/
enabled=1
gpgcheck=0

Then refresh and install:

dnf makecache
dnf install my-package

Authenticated RPM example (/etc/yum.repos.d/athene.repo):

[athene-main]
name=Athene RPM Main
baseurl=http://localhost:19191/r/rpm/main/
enabled=1
gpgcheck=0
username=alice
password=<personal-access-token>

13.5 Maven (Producer and Consumer)

Maven commonly uses Athene in both directions:

  • Producer: publish built artifacts to Athene.
  • Consumer: resolve dependencies from Athene-hosted repositories.

Typical flow:

  1. Configure distributionManagement (publish target) and repository entries (resolve source).
  2. Authenticate using token-based credentials.
  3. Run mvn deploy for publication and normal build commands for dependency resolution.

Example pom.xml fragment (consumer + producer endpoints):

<repositories>
    <repository>
        <id>athene-main</id>
        <url>http://localhost:19191/r/maven/main/</url>
    </repository>
</repositories>

<distributionManagement>
    <repository>
        <id>athene-main</id>
        <url>http://localhost:19191/r/maven/main/</url>
    </repository>
</distributionManagement>

Authenticated Maven example (~/.m2/settings.xml):

<settings>
    <servers>
        <server>
            <id>athene-main</id>
            <username>alice</username>
            <password>&lt;personal-access-token&gt;</password>
        </server>
    </servers>
</settings>

Tip

Ensure <server><id> in settings.xml exactly matches the <repository><id> used in both pom.xml <repositories> and <distributionManagement>. If the IDs differ, Maven will not apply credentials.

Then resolve and publish:

mvn -U verify
mvn deploy

13.5.1 Alternative: Athene Maven Import Plugin

Use the dedicated Athene plugin when you need to import non-standard artifacts (for example .deb files produced by jdeb) and pass backend-specific import options.

Example pom.xml plugin fragment:

<plugin>
    <groupId>com.jadaptive</groupId>
    <artifactId>athene-maven-plugin</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <executions>
        <execution>
            <goals>
                <goal>import</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <url>https://acme.com/r/debian/my-packages</url>
        <serverId>athene-main</serverId>
        <attached>false</attached>
        <files>
            <file>${project.build.directory}/**/*.deb</file>
        </files>
        <options>
            <distribution>bookworm</distribution>
            <components>main</components>
            <architectures>amd64</architectures>
        </options>
    </configuration>
</plugin>

Credentials come from ~/.m2/settings.xml via the configured serverId:

<settings>
    <servers>
        <server>
            <id>athene-main</id>
            <username>alice</username>
            <password>&lt;personal-access-token&gt;</password>
        </server>
    </servers>
</settings>

If required options are missing, if file patterns match nothing, or if Athene rejects any uploaded file in the aggregated batch response, the plugin fails the build.

13.6 Jenkins (Producer and Consumer Orchestration)

Store the complete <username>:<token> as secret text and expose it as ATHENE_PAT only for command scope:

withCredentials([string(credentialsId: 'athene-pat', variable: 'ATHENE_PAT')]) {
    sh 'athene debian import my-repo build/package.deb'
}

In most delivery pipelines Jenkins acts as:

  • Producer when it publishes new build outputs to Athene.
  • Consumer when it pulls dependencies or test fixtures from Athene repositories.

13.7 GitHub Actions (Producer)

GitHub Actions is commonly used as a producer to publish build artifacts into Athene repositories as part of CI/CD workflows.

Typical flow:

  1. Build package artifacts in a workflow job.
  2. Store Athene credentials as repository or organization secrets.
  3. Call the Athene GitHub Action with repository URL, file globs, and optional backend import options.

Example workflow step:

- name: Import artifacts into Athene
  uses: jadaptive-ltd/athene-github-action@v1
  with:
      url: https://athene.example.com/r/debian/main
      username: ${{ secrets.ATHENE_USERNAME }}
      password: ${{ secrets.ATHENE_PASSWORD }}
      files: |
          target/**/*.deb
      options: |
          distribution=bookworm
          component=main
          architectures=amd64

The action validates repository URL format, resolves globs, uploads all matching files in one multipart request, and fails the workflow if Athene reports HTTP errors or per-file import failures.

13.8 Sync Targets: S3

Use the s3 sync target when exporting repository content to Amazon S3 for backup, replication, or distribution.

Example repository configuration:

;----------------------------------------
; S3 Synchronisation - Configuration for 
; syncing to S3.  This is used for backup
; and replication of repositories.
;----------------------------------------
[s3]

; Region - The Amazon region.
region = eu-west-1

; Bucket - The S3 bucket.
bucket = my-bucket

; Path - The path under the bucket to which the repository will be synchronised to.
path = /

; Access Key ID - The AWS access key ID to use for S3 access.
access-key-id = XXXXXXXXXXXXXXXXX

; Secret Access Key - The AWS secret access key to use for S3 access.
secret-access-key = XXXXXXXXXXXXXXXXX

13.9 Sync Targets: SFTP

Use the sftp sync target when exporting to a remote SSH/SFTP server.

Example repository configuration:

;----------------------------------------
; SFTP Synchronisation - Configuration 
; options synchronising repositories to 
; and from remote SFTP files system.
;----------------------------------------
[sftp]

; Hostname - The hostname of the remote SFTP service.
hostname = my-ssh-server

; Port - The port on which the remote SFTP service listens.
port = 22

; Path - The path on the remote host to which the repository will be synchronised to.
path = /

; Username - The username of the remote user.
username = joeb

; Password - The password of the remote user.
password = XXXXXXXX

13.10 User Backend: LDAP

LDAP is a global authentication backend, not a per-repository setting. Configure it with:

athene configuration authentication

The [ldap] section is part of the broader authentication configuration. Example fragment:

;----------------------------------------
; LDAP - The LDAP authenticator must be configured before it can be used. At minimum a hostname is required.
;----------------------------------------
[ldap]

; Hostname - The hostname where the LDAP service running.
hostname = 10.0.0.2
;hostname = dc1.southpark.lan

; Port - The port on which the LDAP service running. When not set, the default 389 will be used unless SSL is enabled, in which case 636 will be used.
port = 3268
;port = 636

; SSL - Whether or not to use LDAPS (SSL) or plain LDAP.
ssl = false
;ssl = true

; Ignore SSL Errors - Ignore any SSL errors with certificates.
ignore-ssl-errors = true

; Base DN - Base DN under which users are searched, e.g. `dc=example,dc=com`.
base-dn = "ou=Employees,dc=hypersocket,dc=io"
;base-dn = "dc=southpark,dc=lan"

; Bind DN - Optional bind DN for a service account used to look up users by short username.
bind-dn = "cn=Athene,ou=Service Accounts,dc=hypersocket,dc=io"

; Bind Password - If bind DN is set, a password must be provided.
bind-password = "XXXXXXXX"

; Username Attribute - Typically `uid` for OpenLDAP and `sAMAccountName` for Active Directory.
username-attribute = sAMAccountName

; User Search Filter - Optional search filter for resolving short usernames to a DN.
;user-search-filter = ($[username-attribute]={0})

Tip

Restart Athene after changing which authenticators are enabled or disabled. Normal LDAP detail updates (for example bind-password, hostname, or base-dn) can be applied without a restart.

13.11 Files Backend (Flexible File Store)

Use the files backend when you need a generic artifact store whose directory and filename layout is controlled by placeholders.

Example repository configuration:

[files]
layout = %p/%v/%p-%a-%v.%x
filename-namespace-separator = .
folder-namespace-separator = /

Layout rules:

  1. The last layout segment defines the stored filename.
  2. All preceding segments define the folder path.
  3. If layout has only one segment, files are stored at repository root.

Supported placeholders:

  • %p package name
  • %v version
  • %a architecture
  • %x extension
  • %n namespace (separator depends on filename/folder context)

CLI import example with generic metadata:

athene files import generic ./build/demo-amd64-1.2.3.zip --package=demo --version=1.2.3 --architecture=amd64 --extension=zip --namespace=com.example

When overriding signing per import, use --key=<signer-type>/<key-id-or-name>. The signer type must be the signer id (for example apple-codesign), not a CLI alias (for example rcodesign).

Apple files import signing example:

athene files import binaries ./MyApp.pkg --package=myapp --version=2.0.0 --architecture=amd64 --extension=pkg --key=apple-codesign/222d3c8e269a4e5f98e3c9575aa8e810 --passphrase "changeit" --notarize --staple

Important behavior:

  • If a placeholder exists in layout, the corresponding metadata becomes required.
  • Athene attempts to derive values from the upload filename when possible.
  • If a required value cannot be derived and is not provided, import fails with a missing-options response.

13.12 Jsign Signers and SafeNet Runtime

Athene can use Jsign-backed signer integrations (jks, spcpvk, safenet) for file signing workflows.

  • jks: Java keystore based signing (JKS/JCEKS/PKCS12).
  • spcpvk: legacy SPC certificate + PVK key based signing.
  • safenet: token/HSM signing through SafeNet middleware.

Runtime requirements:

  1. Install jsign in the Athene runtime image/host (Athene Docker images can install the upstream Debian package).
  2. For safenet, install and configure vendor middleware (for example SafeNet Authentication Client and PKCS#11 provider files) in the runtime container/host.
  3. Ensure any token middleware paths and provider files are readable by the Athene runtime user.
  4. In Docker deployments, share the host USB bus into the container (for example /dev/bus/usb:/dev/bus/usb) so token middleware can access the physical device.

SafeNet key creation behavior:

  • --alias is optional for athene safenet create-key.
  • Athene resolves and persists the token alias during key creation.
  • If multiple token aliases exist, provide --alias to choose one explicitly.

13.12.1 Installing SafeNet Client Debian Packages via Extensions

Athene startup scans <config>/extensions for .deb files and attempts a non-interactive install of each package. This is intended for extension middleware that cannot be redistributed directly in the base image (for example SafeNet client packages).

Typical Docker/Compose flow:

  1. Place the vendor .deb package files in the config mount under extensions (for example ./docker/config/extensions).
  2. Ensure USB bus passthrough is configured for the Athene container.
  3. Restart Athene so startup installation runs.

Notes:

  • Installation is attempted on every startup.
  • Existing/already-installed packages do not hard-fail startup.
  • Startup logs include installer output for failed package installs.

Scope and backend compatibility:

  • debian, rpm, and maven repository signing remains OpenPGP-only.
  • files backend signing can use OpenPGP or any configured Jsign-backed signer type.

13.13 Apple Codesign (rcodesign)

Athene includes an apple-codesign signer integration (CLI command group rcodesign) for Apple code-signing workflows that can optionally run notarization and stapling.

Stored key metadata includes:

  • signing certificate material (typically PKCS#12)
  • App Store Connect API issuer id
  • App Store Connect API key id
  • App Store Connect API private key (PEM)

Runtime requirements:

  1. Install rcodesign in the Athene runtime image/host.
  2. Ensure outbound access from Athene runtime to Apple notarization endpoints when --notarize is used.
  3. Keep certificate and API key material readable only by the Athene runtime user.

CLI examples:

athene rcodesign create-key --name "Apple Release" --cert-file /var/lib/athene/keys/apple-release.p12 --passphrase "changeit" --api-issuer-id "00000000-0000-0000-0000-000000000000" --api-key-id "DEADBEEF42" --api-private-key-file /var/lib/athene/keys/AuthKey_DEADBEEF42.p8
athene rcodesign import-key --name "Apple Release" --cert-file ./apple-release.p12 --passphrase "changeit" --api-issuer-id "00000000-0000-0000-0000-000000000000" --api-key-id "DEADBEEF42" --api-private-key-file ./AuthKey_DEADBEEF42.p8
athene rcodesign sign ./MyApp.pkg ./MyApp.signed.pkg --key <id> --notarize --staple --wait --max-wait-seconds 900
athene rcodesign sign ./MyApp.pkg ./MyApp.signed.pkg --key <id> --passphrase "changeit" --notarize --staple --wait --max-wait-seconds 900

Use --passphrase for PKCS#12 certificate protection in Apple signer create-key, import-key, and sign operations.

Scope and backend compatibility:

  • debian, rpm, and maven repository signing remains OpenPGP-only.
  • files backend signing can use OpenPGP, Jsign-backed signers, or apple-codesign.

Next chapter: 14 REST API.