docs: add GitHub Actions / CI example

[DanMat]

Closes #303

Adds a "Continuous integration (GitHub Actions)" section to the README, following the minimal-auth approach you outlined in #303:

• Store only the two credentials ADP signing needs (adp_token, device_private_key) as secrets, and country_code as a plain variable.
• The workflow builds an ephemeral auth.json and config.toml on the runner via the Python snippet, so no access/refresh tokens, cookies, or account details are uploaded, and the auth files exist only for the runner's lifetime.
• It's a complete, copy-pasteable workflow whose triggers (workflow_dispatch + schedule) match your security recommendation, plus a note to avoid running it from arbitrary pull-request code.

Verified locally: the workflow YAML parses, and the documented Python snippet produces a well-formed auth.json (the two ADP keys, PEM newline-terminated) and a valid config.toml with the ci profile. Changelog entry added.

Happy to adjust the wording/placement or move it into the Sphinx docs if you'd prefer.

Written with AI assistance; I've reviewed and tested the change and will maintain it.

[mkb79]

Thanks a lot for putting this PR together.

I tested the minimal authentication setup locally with a suitably prepared auth file containing only adp_token and device_private_key, and audible library list works correctly with it.

What I have not tested yet is the GitHub Actions-specific part of the workflow itself — in particular reading the values from GitHub Secrets/Variables, preserving the multiline private key correctly, and creating the temporary auth/config files on an actual CI runner.

Would you mind testing the workflow once on your side and confirming that it runs successfully in GitHub Actions?

I can test it myself as well, but it’s already late here in UTC+02:00, so I probably won’t get to run a proper CI test until tomorrow.

Thanks again for working on this.

[DanMat]

Thanks for taking the time to test the minimal-auth setup locally, especially so late in your evening. To save you the CI round, I ran the GitHub Actions side myself, so it is ready for a re-review whenever you have a free moment.

Tested on a real runner and it works end to end. I wired the workflow into one of my own repos (earshot, the working example linked in the PR) and ran it via workflow_dispatch. The run is green: it reads AUDIBLE_ADP_TOKEN and AUDIBLE_DEVICE_PRIVATE_KEY from Secrets and AUDIBLE_COUNTRY_CODE from a Variable, preserves the multiline PEM correctly, writes the ephemeral auth.json and config.toml into the runner temp dir, and audible then pulls the library successfully.

Green run: https://github.com/DanMat/earshot/actions/runs/32303139124

One thing the CI run surfaced that local testing did not: ${{ runner.temp }} is not available in a job-level env: block (only the github, secrets, vars and inputs contexts are), so the workflow failed to parse with "Unrecognized named-value: 'runner'". I pushed a fix to the PR: set AUDIBLE_CONFIG_DIR from $RUNNER_TEMP via $GITHUB_ENV in a small step instead. That is the exact form now running green in earshot.

While I was there I also tightened the setup docs a little: a pointer to audible quickstart to produce the auth file first, and two jq one-liners to load the secrets straight from auth.json. Happy to adjust any of it. Thanks again for the review.

[mkb79]

Thanks again for testing the complete workflow on a real runner and for fixing the runner.temp issue. That gives me much more confidence in the documented approach.

From my side, the PR in its current state is mergeable.

Before merging it, though, I’d like to get your opinion on one possible follow-up idea: a dedicated setup-audible-cli GitHub Action, similar in spirit to astral-sh/setup-uv.

The idea would be to move the installation and ephemeral authentication setup behind something like:

- uses: mkb79/setup-audible-cli@v1
  with:
    adp-token: ${{ secrets.AUDIBLE_ADP_TOKEN }}
    device-private-key: ${{ secrets.AUDIBLE_DEVICE_PRIVATE_KEY }}
    country-code: ${{ vars.AUDIBLE_COUNTRY_CODE }}

After that, users could simply run normal audible-cli commands in subsequent steps, for example:

- run: audible library export

- run: audible library list

or use the more generic API command:

- run: audible api ...

The latter could also be useful for projects that depend on a specific Audible API response format, since they could test selected endpoints directly in CI and detect incompatible API changes.

So the action would not be tied specifically to library exports; it would provide a reusable authenticated audible-cli environment for arbitrary CI workflows.

Do you think such an action would be useful, or do you prefer keeping the explicit setup directly in the documentation?

If you think setup-audible-cli would be worthwhile as well, I would hold off on merging this PR for the moment, set up the action first, and then adjust this PR so the documentation can use the much smaller action-based example instead.

If not, I’m also happy to merge the current version as-is.

[DanMat]

This is a great idea and I am fully on board. A dedicated setup-audible-cli action is the right pattern. Three things make it clearly worth doing:

• It collapses the whole install and ephemeral-auth block into a few lines in every workflow.
• It puts the fragile parts (the runner.temp / GITHUB_ENV handling, the auth.json and config.toml layout) in one place, so a fix lands once instead of in everyone's copy-pasted YAML.
• Your point about decoupling it from export is the strongest one. A reusable authenticated environment lets people run audible api ... in CI to catch breaking API changes, which is genuinely useful well beyond library exports.

I would be happy to help build it. If it works for you, here is a plan:

1. You create the mkb79/setup-audible-cli repo (your namespace) and I open a PR with a first version. I would start with a composite action (action.yml, using: composite): install audible-cli, set AUDIBLE_CONFIG_DIR from $RUNNER_TEMP via $GITHUB_ENV, and write the ephemeral auth.json and config.toml from adp-token, device-private-key and country-code inputs. A composite action keeps it dependency-free and simple to maintain.
2. Once it is merged and tagged, I test it on a real runner in my own project (earshot), the same way I validated this PR.
3. Then I update this PR so the documentation uses the small action-based example.

On that note, I would suggest we hold off merging this PR for now rather than merge it as-is. If we merge the explicit version and then immediately rewrite it to use the action, we create a temporary intermediate state in the docs that we already know we are going to replace. Holding it keeps the history clean and lets the docs land in their final form the first time.

Let me know if that plan works, and whether you would like to scaffold the repo or have me propose the initial structure.

[mkb79]

@DanMat
Thanks — great offer, and I’m on board.

Crossed wires on the ordering, though: I’d already started scaffolding it before your comment came in. Sorry about that. I’ve just emailed you a first version with all the details (sent to the address on your profile). Nothing is published yet — I’d rather you look at it first.

And agreed on holding this PR rather than merging it as-is.

[DanMat]

Thanks Marcel, got your email and replied there. Agreed on holding this PR while we get the follow-up action into shape, so the docs can land in their final form the first time. More soon.