docs: add recipe for publishing a separate image package (#118)

docs/dependencies/images.md

@@ -1,84 +1,60 @@
 ---
-title: "Publishing to the images namespace"
+title: "Publishing to the image namespace"
 sidebar_label: image packages
 ---
 
-Eik's provides an image namespace for uploading images. 
-The purpose of this namespace is three-fold. 
+The purpose of the image namespace is three-fold:
 
-1. By creating a separate namespace, files that change infrequently (images and other media) can be uploaded and versioned separately from files that change often (JavaScript and CSS)
-2. An image manipulation service such as Fastly's [image optimization](https://www.fastly.com/products/image-optimization) can be placed in front of this namespace.
-3. Your Eik server can be configured to allow larger package sizes on the image namespace and smaller package sizes on other namespaces.
+1. Files that change infrequently (images and other media) can be uploaded and versioned separately from files that change often (JavaScript and CSS).
+2. A service such as Fastly's [image optimization](https://www.fastly.com/products/image-optimization) can be placed in front of this namespace.
+3. Your Eik server can allow larger package sizes on the image namespace.
 
 In this document you'll learn how to:
 
 - publish images to your Eik server
 - how to update existing images
-- create an alias that can be updated as you publish new patch or minor versions of your images
 
 ## Preparing images for Eik
 
 The `image` namespace on Eik works the same way as for application code. You will need:
 
 - some images to upload
-- an `eik.json`
+- an Eik configuration for images separate from application code
 
-### Configure Eik
+## Configure the image package
 
-The first step is to create an `eik.json` file.
+We'll assume you [already have an `eik.json` for application code](/docs/introduction/workflow).
 
-```sh
-eik init
-```
-
-Open the newly created `eik.json` and fill out the required fields.
+The first step then is to create an `eik-image.json` file. Open `eik-image.json` and fill out the required fields.
 
 ```json
 {
 	"name": "my-images",
 	"type": "image",
 	"version": "1.0.0",
 	"server": "https://eik.store.com",
-	"files": "./path/to/images/folder"
+	"files": "./images/"
 }
 ```
 
-:::tip
-
-If your organisation doesn't have a running Eik server yet, hop on over to [the server documentation](/docs/server).
+The `files` key should be set to a directory containing image files to publish.
 
-:::
+Eik does not discriminate file types so if you wish to upload videos and other types of media, this will also work.
 
-The `files` key should be set to a directory containing image files to publish. Eik does not discriminate file types so if you wish to upload videos and other types of media, this will also work.
+## Publish the images
 
-### Publish the images
-
-Let's update the `"files"` field in `eik.json` to include an images folder in our imaginary project.
-
-```json
-{
-	"name": "my-images",
-	"type": "image",
-	"version": "1.0.0",
-	"server": "https://eik.store.com",
-	"files": "./images/"
-}
-```
+Say you've made an `eik-image.json` like above and you want to publish the images from its `files` configuration.
 
-Now you can log in to the Eik server and publish, same as when publishing an application.
+To do so, log in to the Eik server and publish. This works the same as when publishing an application, except you should pass the `--config` option.
 
 ```sh
-eik login --key YOUR_EIK_KEY
-eik publish
+eik login --key <token>
+eik publish --config eik-image.json
 ```
 
 At this point your images should be available on the path `https://eik.store.com/img/my-images/1.0.0`.
 
-:::tip
-
-You should keep `package.json`, `eik.json` and the build script in version control so you don't have to recreate this setup when there are updates.
-
-:::
+You can also [automate the publish process](/docs/guides/github-actions-images/).
 
 ## Get information about a published package
 
@@ -90,9 +66,8 @@ eik meta my-images
 
 ## Updating a published package
 
-New versions of the image package need to be published to the Eik server, either manually or with automation like Renovate or Dependabot. Whether you choose to automate or have a manual process, these are the steps to update a module.
+Whether you choose to [automate](/docs/guides/github-actions-images/) or have a manual process, these are the steps to update a module.
 
 1. Add, remove or update images in your images directory
-2. Update the version number in `eik.json`
-3. Run the build script
-4. Publish to the Eik server
+2. Update the version number in `eik-image.json`, manually or with `eik version --config eik-image.json`
+3. Publish with `eik publish --config eik-image.json`

docs/guides/github-actions-images.md

@@ -0,0 +1,92 @@
+---
+title: Publish images to Eik on GitHub Actions
+---
+
+This guide describes how to use GitHub Actions to publish an [image package](/docs/dependencies/images) to an Eik server.
+
+## Prerequisites
+
+Your repo needs to have access to an Eik login key. Store this as a [Secret you can use in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+
+In this guide we'll be using `EIK_TOKEN` as the secret name.
+
+## Workflow
+
+We automate publishing to Eik using the [Eik CLI](/docs/reference/at-eik-cli/).
+
+This variant requires you update the version number in `eik-image.json` when you add or change a file. See [this alternative workflow](#automatically-increment-the-patch-version-number) if you want full automation.
+
+```yaml
+name: Publish images to Eik
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - eik-image.json # only run when eik-image.json changes
+
+jobs:
+  publish:
+    runs-on: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      # you can also add @eik/cli to your devDependencies
+      - run: npm install --global @eik/cli@^3
+
+      - name: Publish to Eik
+        run: |
+          eik login --key ${{secrets.EIK_TOKEN}}
+          eik publish --config eik-image.json
+```
+
+### Automatically increment the patch version number
+
+This variant will run whenever the `main` branch changes.
+
+You can use the `eik version --config eik-image.json` command to increment the version number on CI.
+The version will only be updated if the CLI detects there are changes to the files.
+
+Remember to commit the updated `eik-image.json` back to your repository.
+
+```yaml
+name: Publish images to Eik
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      # you can also add @eik/cli to your devDependencies
+      - run: npm install --global @eik/cli@^3
+
+      - name: Publish to Eik
+        run: |
+          eik login --key ${{secrets.EIK_TOKEN}}
+          eik version --config eik-image.json || true
+          eik publish --config eik-image.json
+
+      - name: Commit updated eik-image.json if version changed
+        # git diff --quiet will exit with code 0 if there are no changes.
+        # if there _are_ changes (a new version), the right-hand side of || will run
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git diff --quiet || (git commit --all --message "chore: update version number in eik-image.json [skip ci]" && git push origin HEAD)
+        shell: bash
+```

sidebars.js

@@ -41,6 +41,7 @@ module.exports = {
 				"guides/postcss",
 				"guides/webpack",
 				"guides/github-actions",
+				"guides/github-actions-images",
 				"guides/travis",
 			],
 		},