GitHub Actions
aux4 ships an official GitHub Action, aux4/action@v1, that lints, tests, and publishes aux4 packages straight from your CI pipeline. A single action handles all three stages of the package lifecycle — you pick the stage with the command input.
1- uses: aux4/action@v1
2 with:
3 command: lint # or: test, publishThe action installs aux4 and pkger for you, so the only prerequisite is checking out your repository first with actions/checkout.
Setup
Linting and testing need no configuration. Publishing to the aux4 Hub authenticates with a durable publishing token — a client id/secret pair you create once, then use to mint a fresh, short-lived hub token on every run. Pasting a plain access token into a secret would break CI as soon as it expires; the client id/secret does not expire, and each run mints its own token from it.
- Create a publishing token. On user.aux4.io, go to your account → Scopes → open your scope → Tokens → Create token, choose Publish to Hub, and copy the Client ID and Client Secret from the one-time dialog (the secret is shown only once). This requires a paid Hub plan and ownership of the scope.
- Store both as repository secrets — e.g. AUX4_CLIENT_ID and AUX4_CLIENT_SECRET — under your repository's Settings → Secrets and variables → Actions. For a whole organization, add them once as organization secrets.
- GITHUB_TOKEN — provided automatically by GitHub Actions. Grant it write access so the action can push the version bump, create the tag, and publish the release:
1permissions:
2 contents: writeThe publish job mints a fresh hub token from the client id/secret and passes it to the action as aux4_token — see Publish and the Full Workflow Example.
Lint
Validates your .aux4 files for structural correctness, naming conventions, reference integrity, and best practices using aux4/lint.
1- uses: aux4/action@v1
2 with:
3 command: lint
4 strict: 'true'
5 resolve: 'true'| Input | Description | Default |
|---|---|---|
| strict | Treats -local versions as errors | false |
| resolve | Validates aux4 command calls against installed packages | false |
| format | Output format (text or json) | text |
When using resolve, list any packages your commands call via the packages input so they are installed before linting:
1- uses: aux4/action@v1
2 with:
3 command: lint
4 resolve: 'true'
5 packages: aux4/config aux4/apiTest
Runs your .test.md suite with the aux4/test framework. The action packages your project, installs it, and runs the tests against the installed package — the same way an end user would run it.
1- uses: aux4/action@v1
2 with:
3 command: test
4 build_command: npm run build
5 coverage_threshold: '80'| Input | Description | Default |
|---|---|---|
| test_directory | Directory containing test files | test |
| build_command | Build command to run before testing (e.g. npm run build, aux4 builder linux) | |
| coverage_threshold | Minimum step coverage % (0–100). Fails if below. 0 disables. | 0 |
When coverage_threshold is greater than 0, a coverage check runs after the tests pass and fails the job if coverage is below the threshold:
1Coverage 50% is below threshold 80%For Go packages, set build_command to the platform builder (aux4 builder linux, aux4 builder darwin) and run the job on the matching runner. For JS packages, use build_command: npm run build.
Publish
Bumps the version, builds the package, publishes it to hub.aux4.io, then commits the bump, tags the release, and creates a GitHub Release.
Mint a fresh hub token from your AUX4_CLIENT_ID / AUX4_CLIENT_SECRET secrets in a step just before the action, then pass it in as aux4_token:
1- name: Mint hub token
2 id: mint
3 env:
4 CLIENT_ID: ${{ secrets.AUX4_CLIENT_ID }}
5 CLIENT_SECRET: ${{ secrets.AUX4_CLIENT_SECRET }}
6 run: |
7 TOK=$(curl -sf -u "$CLIENT_ID:$CLIENT_SECRET" \
8 -d grant_type=client_credentials https://sso.aux4.io/token | jq -r '.access_token // empty')
9 if [ -z "$TOK" ]; then echo "::error::failed to mint hub token"; exit 1; fi
10 echo "::add-mask::$TOK"
11 echo "token=$TOK" >> "$GITHUB_OUTPUT"
12
13- uses: aux4/action@v1
14 with:
15 command: publish
16 level: patch
17 aux4_token: ${{ steps.mint.outputs.token }}
18 github_token: ${{ secrets.GITHUB_TOKEN }}| Input | Description | Default |
|---|---|---|
| level | Release level (patch, minor, major) | patch |
| aux4_token | Freshly minted hub token (from the mint step), not a stored access token | required |
| github_token | GitHub token for creating releases | required |
| aux4_image | Docker image used to build and publish | aux4/aux4:latest |
The version in your package/.aux4 is incremented automatically according to level — do not bump it by hand. The publish step pushes the bumped .aux4 and a v<version> tag back to your branch.
Outputs
| Output | Description |
|---|---|
| version | The new package version |
| scope | The package scope |
| name | The package name |
Common Inputs
These inputs apply to every command:
| Input | Description | Default |
|---|---|---|
| command | Command to run: lint, test, or publish | required |
| working_directory | Working directory containing the repository | . |
| package_directory | Directory containing the .aux4 file | package |
| system_packages | Space-separated system packages to install (apt/brew) | |
| npm_packages | Space-separated npm packages to install globally | |
| packages | Space-separated aux4 packages to install | |
| build_command | Build command to run before the action |
Recommended Pipeline
Run lint first, tests in parallel across platforms once lint passes, and publish only after every check succeeds:
1lint → test-linux ─┐
2 ├→ publish
3lint → test-darwin ─┘Full Workflow Example
A complete .github/workflows/publish.yml that lints, tests on Linux and macOS, and publishes on push to main — with a manual workflow_dispatch for choosing the release level:
1name: Publish Package
2
3on:
4 push:
5 branches:
6 - main
7 paths:
8 - '**'
9 - '!.github/**'
10 - '!README.md'
11 - '!LICENSE'
12 - '!.gitignore'
13
14 workflow_dispatch:
15 inputs:
16 level:
17 description: 'Release level (patch, minor, major)'
18 required: true
19 default: 'patch'
20 type: choice
21 options:
22 - patch
23 - minor
24 - major
25
26concurrency:
27 group: publish-package
28 cancel-in-progress: false
29
30permissions:
31 contents: write
32
33jobs:
34 lint:
35 runs-on: ubuntu-latest
36 steps:
37 - uses: actions/checkout@v6
38
39 - name: Set up Node.js
40 uses: actions/setup-node@v4
41 with:
42 node-version: '22'
43
44 - name: Install dependencies
45 run: npm install
46
47 - name: Build
48 run: npm run build
49
50 - uses: aux4/action@v1
51 with:
52 command: lint
53 strict: 'true'
54
55 test-linux:
56 needs: [lint]
57 runs-on: ubuntu-latest
58 steps:
59 - uses: actions/checkout@v6
60
61 - name: Set up Node.js
62 uses: actions/setup-node@v4
63 with:
64 node-version: '22'
65
66 - name: Install dependencies
67 run: npm install
68
69 - uses: aux4/action@v1
70 with:
71 command: test
72 build_command: npm run build
73
74 test-darwin:
75 needs: [lint]
76 runs-on: macos-latest
77 steps:
78 - uses: actions/checkout@v6
79
80 - name: Set up Node.js
81 uses: actions/setup-node@v4
82 with:
83 node-version: '22'
84
85 - name: Install dependencies
86 run: npm install
87
88 - uses: aux4/action@v1
89 with:
90 command: test
91 build_command: npm run build
92
93 publish:
94 needs: [test-linux, test-darwin]
95 runs-on: ubuntu-latest
96 steps:
97 - uses: actions/checkout@v6
98 with:
99 fetch-depth: 0
100
101 - name: Set up Node.js
102 uses: actions/setup-node@v4
103 with:
104 node-version: '22'
105
106 - name: Install dependencies
107 run: npm install
108
109 - name: Build
110 run: npm run build
111
112 - name: Mint hub token
113 id: mint
114 env:
115 CLIENT_ID: ${{ secrets.AUX4_CLIENT_ID }}
116 CLIENT_SECRET: ${{ secrets.AUX4_CLIENT_SECRET }}
117 run: |
118 TOK=$(curl -sf -u "$CLIENT_ID:$CLIENT_SECRET" \
119 -d grant_type=client_credentials https://sso.aux4.io/token | jq -r '.access_token // empty')
120 if [ -z "$TOK" ]; then echo "::error::failed to mint hub token"; exit 1; fi
121 echo "::add-mask::$TOK"
122 echo "token=$TOK" >> "$GITHUB_OUTPUT"
123
124 - uses: aux4/action@v1
125 with:
126 command: publish
127 level: ${{ inputs.level || 'patch' }}
128 aux4_token: ${{ steps.mint.outputs.token }}
129 github_token: ${{ secrets.GITHUB_TOKEN }}The publish job needs fetch-depth: 0 so the action can read the full history and push tags. Keep concurrency set so two pushes never race to publish the same version.
Continuous Integration Only
For branches and pull requests where you want the checks without publishing, run just lint and test in a separate ci.yml:
1name: CI
2
3on:
4 pull_request:
5 push:
6 branches-ignore:
7 - main
8
9jobs:
10 lint:
11 runs-on: ubuntu-latest
12 steps:
13 - uses: actions/checkout@v6
14 - uses: aux4/action@v1
15 with:
16 command: lint
17 strict: 'true'
18
19 test:
20 runs-on: ubuntu-latest
21 steps:
22 - uses: actions/checkout@v6
23 - uses: aux4/action@v1
24 with:
25 command: test
26 build_command: npm run buildStandalone Actions
aux4/action@v1 is the recommended entry point, but each stage is also available as a focused action if you prefer to compose them yourself:
- aux4/lint-package-action@v1 — lint only
- aux4/test-package-action@v1 — test only
- aux4/publish-package-action@v1 — build, publish, and release only
They accept the same stage-specific inputs described above.