S3 bucket

If your builds already land in a bucket, for example an AWS bucket that CI writes to, there are three ways to show them in Holtdroid.

Setup	Use it when
A plain S3 source	The api can have long-lived keys for the bucket
holtdroid-s3-sync, copy	The bucket needs short-lived credentials (AWS IAM Identity Center), or you want your own copies
holtdroid-s3-sync, broker	Short-lived credentials, but no copies: the api reads the bucket directly

For any of them, include rules pick the builds, e.g. /releases/* without !/releases/night/*.

holtdroid-s3-sync

holtdroid-s3-sync is a separate job (job: s3 in the chart deploy/helm/holtdroid-sync). It reads the bucket with:

• AWS IAM Identity Center (SSO);
• static keys;
• the default AWS credential chain (IRSA, instance role).

It can run in either mode, or both at once.

Signing in with AWS SSO

The job uses the OAuth device authorization flow, the same one aws sso login --use-device-code uses, so no AWS CLI or local browser is involved:

1. When the job has no usable session, it registers itself with your Identity Center and asks for a device code.
2. It sends a link with the code through shoutrrr (notify.urls: Slack, Telegram, Discord, Matrix, ntfy, email, webhooks, …), writes it to its log, and serves it on /status.
3. You open the link, check the code and approve. The job then gets role credentials for the configured account and permission set.
4. It keeps the session alive with refresh tokens. The session ends when your Identity Center’s session duration runs out, typically 8 hours to 7 days. Then the job asks again.

A code is valid for about ten minutes. If nobody approves it, the next code, and the next message, comes after notify.remind (one hour by default), so the channel doesn’t fill up.

The tokens are kept in cacheFile on a small private volume, so a restart doesn’t need a new login.

Copy mode

Matching APKs are copied into a folder or another bucket that Holtdroid lists as a read-only source. Each copy gets a sidecar with origin: "s3", the object’s time and a link to it in the AWS console, plus the launcher icon. Sidecars already in the bucket are used too. Builds that disappear from the bucket, or no longer match the rules, are removed from the copy.

With notify.builds, each copy pass that brought something new sends one message through shoutrrr, for example to a Slack channel. It lists the builds with their version and package, and adds Quick launch and Launch links into the portal. Builds older than maxAge (24 hours by default) are left out, so copying an existing bucket for the first time doesn’t flood the channel.

Copies don’t depend on the session. If nobody approves a new login, the builds that were already copied stay launchable.

# holtdroid-s3-sync
source:
  bucket: work-apks
  prefix: android/
  region: eu-west-1
  include: ["/releases/*", "!/releases/night/*"]
  auth:
    type: sso
    sso:
      startURL: https://acme.awsapps.com/start
      region: eu-west-1
      accountID: "123456789012"
      roleName: ApkReader
      cacheFile: /data/sso/tokens.json
copy:
  target:
    type: s3
    s3:
      {
        endpoint: https://s3.example.com,
        bucket: holtdroid,
        prefix: work,
        accessKey: env:S3_ACCESS_KEY,
        secretKey: env:S3_SECRET_KEY,
      }
notify:
  urls: [env:NOTIFY_URL] # e.g. slack://xoxb:<bot token>@C0123ABCD

# Holtdroid
sources:
  - name: work
    type: s3
    readOnly: true
    s3:
      {
        endpoint: https://s3.example.com,
        bucket: holtdroid,
        prefix: work,
        accessKey: env:S3_ACCESS_KEY,
        secretKey: env:S3_SECRET_KEY,
      }

Broker mode

The job serves GET /credentials with temporary keys in the ECS container credentials format, behind a token. Holtdroid’s S3 source fetches them through credentialsURL and refreshes them before they expire. Nothing is copied, and the include rules are applied by the api. While there is no session, the endpoint answers 503, and the source shows an error instead of its builds.

# holtdroid-s3-sync
broker:
  enabled: true
  token: env:BROKER_TOKEN
copy:
  enabled: false

# Holtdroid
sources:
  - name: work
    type: s3
    readOnly: true
    include: ["/releases/*", "!/releases/night/*"]
    s3:
      endpoint: https://s3.eu-west-1.amazonaws.com
      region: eu-west-1
      bucket: work-apks
      prefix: android
      credentialsURL: http://holtdroid-s3-sync:8080/credentials
      credentialsToken: env:BROKER_TOKEN

Any other service that speaks the same format can serve these credentials.

Permissions

The permission set, or the keys, needs s3:ListBucket on the bucket for the prefix and s3:GetObject on its objects. Nothing writes to the source bucket.