Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Everything in this repository is owned by the maintainer. Add paths above this line when someone
# else takes over an area (the last matching pattern wins).
* @jfcmartins
8 changes: 8 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
commit-message:
prefix: "chore(ci)"
63 changes: 63 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: ci

# Unit tests on the platforms the action supports, and actionlint on the workflows.

on:
push:
branches: [main]
# A draft pull request runs nothing; marking it ready for review starts the run.
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
# A new push cancels the older pull request run; a push to main always runs to the end.
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
test:
name: Tests (${{ matrix.os }})
if: github.event_name != 'pull_request' || !github.event.pull_request.draft
runs-on: ${{ matrix.os }}
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04, ubuntu-24.04-arm, macos-latest]
steps:
- name: Check out the commit
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Install Node
uses: jdx/mise-action@82a612c5ab8bcda7cc5db6b7e81a8e7584c3dc6e # v5.2.3
with:
install_args: node

- name: Run the tests
run: npm test

actionlint:
name: Workflow lint (actionlint)
if: github.event_name != 'pull_request' || !github.event.pull_request.draft
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: Check out the commit
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Install actionlint
uses: jdx/mise-action@82a612c5ab8bcda7cc5db6b7e81a8e7584c3dc6e # v5.2.3
with:
# actionlint runs shellcheck on `run:` scripts when it is installed.
install_args: actionlint shellcheck

- name: Lint the workflows
run: actionlint
46 changes: 46 additions & 0 deletions .github/workflows/smoke.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: smoke

# Runs the action itself against a published Limen release on real runners. Run it by hand before
# tagging a release of this action, and after a Limen release that changes the CLI's archive.
# It installs only: the bot login needs a Limen control plane that GitHub's runners can reach.

on:
workflow_dispatch:
inputs:
version:
description: The Limen release to install, for example v0.1.0
required: true

permissions:
contents: read

jobs:
install:
name: Install (${{ matrix.os }})
runs-on: ${{ matrix.os }}
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04, ubuntu-24.04-arm, macos-latest, macos-15-intel]
steps:
- name: Check out the action
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Install Limen
id: limen
uses: ./
with:
version: ${{ inputs.version }}

- name: The CLI runs and is the version asked for
env:
WANT: ${{ steps.limen.outputs.version }}
run: |
set -euo pipefail
got="$(limen --version)"
echo "$got"
[ "$got" = "limen ${WANT#v}" ]
test "$(command -v limen)" = "${{ steps.limen.outputs.path }}/limen"
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
node_modules/
.claude/worktrees/
17 changes: 17 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Instructions for coding agents

`setup-limen`: a GitHub Action (Node 24, no dependencies, no build step) that installs the Limen CLI and logs a job in as a bot, a thin client of `limen login --bot` ([ADR-0019](https://github.com/limen-dev/limen/blob/main/docs/adr/0019-machine-identities.md)).

## Rules
- **Work in a git worktree:** `git worktree add .claude/worktrees/<topic> -b <branch>`. Never edit the main checkout or switch its branch.
- **No dependencies, no `dist/`.** What is in `src/` is what runs.
- **Fail closed.** A missing or wrong checksum, or a failed provenance check, stops the job. Never add a way to skip both.
- **The action never reads the OIDC token or a Limen credential.** Pass arguments as a list, never through a shell.
- **The CLI is Limen's.** Flags come from `limen login --help`; don't invent options.
- **Verify before claiming.** Anything checked only against the stub `limen` or the local release server is *unverified*.
- **Pin every action** in workflows to a full commit SHA with a version comment.
- **Commits:** conventional, small, signed; stage specific files. Don't push or tag unless asked. Pull requests as drafts.

```sh
mise install && npm test && mise exec -- actionlint
```
59 changes: 59 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# setup-limen

A GitHub Action that installs the [Limen](https://github.com/limen-dev/limen) CLI and, if you ask, logs the job in as a **bot** with its own OIDC token. No SSH key, database password or Limen token is stored in your secrets. The job gets a certificate that lasts 15 minutes by default (an hour at most), and every session is audited with the repository, workflow, run and commit.

```yaml
permissions:
id-token: write # lets the job ask GitHub for its OIDC token
contents: read

jobs:
deploy:
runs-on: ubuntu-24.04
environment: staging
steps:
- uses: limen-dev/setup-limen@v0
with:
version: v0.1.0 # pin one
proxy: limen.example.com:443 # leave out to only install
- run: limen ssh web-staging-1 -- ./deploy.sh
```

## You need

- **A published Limen release.** The action downloads the CLI from [limen-dev/limen releases](https://github.com/limen-dev/limen/releases).
- **A bot in your policy** that matches the job exactly ([bots guide](https://github.com/limen-dev/limen/blob/main/docs/guides/bots.md)): `method: github_actions`, with `repository`, and `ref` or `environment`.
- **A proxy the runner can reach.** GitHub-hosted runners are on the public internet; for a private proxy use a self-hosted runner.
- **`id-token: write`** on the job, when you pass `proxy`.

## Inputs and outputs

| Input | Default | |
|---|---|---|
| `version` | `latest` | Release to install, such as `v0.1.0`. **Pin one**: `latest` is the newest stable release and changes under you. |
| `proxy` | | `host:port` of the Limen proxy. Set it to log in. |
| `bot-name` | | Which bot, if more than one could match. |
| `audience` | | Audience to ask GitHub for. Empty uses the one your control plane expects. |
| `ca-file` | | PEM file with the CA to trust, for a private CA. |
| `verify-attestation` | `true` | Also verify build provenance with `gh attestation verify`. |
| `github-token` | `github.token` | For the GitHub API only. Needs no permissions. |

Outputs: `version`, `path` (the directory with `limen`, already on `PATH`) and `logged-in`. After a login, `LIMEN_HOME` and `LIMEN_PROXY` are set for later steps.

## What it does

- **Verifies, then trusts.** The archive must match the release's `SHA256SUMS` and, by default, its provenance must verify against Limen's `release.yml`. Any failure, or a missing `gh`, stops the job. Turn provenance off only on a runner without `gh`; you then rely on the checksum alone.
- **Exposes only `limen`** on `PATH`, not the server binaries in the same archive.
- **Cleans up.** Credentials live in a private directory under `RUNNER_TEMP`; the post step runs `limen logout` and deletes it, even after a failure.
- **Never sees the OIDC token.** The CLI asks the runner for it.
- **Runs what you read.** Plain Node 24, no dependencies, no `dist/`. `version` and `proxy` are validated.

Pull request jobs (including forks) **never match a bot**: Limen refuses them, because that job runs code the author chose. Log in from a protected branch or an environment with required reviewers. To be safest, pin the action to a full commit SHA.

## Status

- **Verified:** install, checksum and provenance against the real v0.1.0-rc.1 release (served locally, as it is still a draft); unit tests with a stub `limen`.
- **Unverified:** the bot login against a real GitHub token and control plane. Run the [smoke workflow](.github/workflows/smoke.yml) and a real login before the first release.
- Linux and macOS, x64 and arm64. Limen has no Windows build.

Develop with `mise install && npm test`. Licensed under [Apache-2.0](LICENSE).
10 changes: 10 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Releasing

Tags are `vMAJOR.MINOR.PATCH`, plus a moving major tag (`v0`) for `uses:`.

1. `main` is green and the README's **Status** is true.
2. Run the [smoke workflow](.github/workflows/smoke.yml) against the newest published Limen release. Don't tag if it fails.
3. `git tag -s v0.1.0 -m v0.1.0 && git push origin v0.1.0`, then create a GitHub release from it. Tick "Publish this Action to the GitHub Marketplace" (needs the owner's account).
4. Move the major tag: `git tag -fs v0 -m v0 v0.1.0 && git push -f origin v0`. Only the major tag moves; `vX.Y.Z` tags are protected.

A change that can break a workflow needs a new major version.
5 changes: 5 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Security

Report vulnerabilities privately through [GitHub's private reporting](https://github.com/limen-dev/setup-limen/security/advisories/new), not in an issue. For Limen itself, report to [limen-dev/limen](https://github.com/limen-dev/limen/security).

This action runs code it downloads, so it verifies the archive against the release's `SHA256SUMS` and its build provenance, and stops on any failure. It never sees the job's OIDC token, keeps credentials in a private directory that the post step deletes, validates its inputs, and has no runtime dependencies.
55 changes: 55 additions & 0 deletions action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: Set up Limen
description: Install the Limen CLI, verified against the release checksums and provenance, and optionally log the job in as a bot with its GitHub OIDC token. No stored secret.
author: limen-dev
branding:
icon: lock
color: gray-dark

inputs:
version:
description: >-
The Limen release to install, for example v0.1.0. Pin one. "latest" means the newest
stable release (not a release candidate) and changes under you.
required: false
default: latest
proxy:
description: >-
The Limen proxy to log in to, as host:port, for example limen.example.com:443. Leave it
empty to only install the CLI.
required: false
default: ""
bot-name:
description: Which bot to log in as, if more than one bot rule could match this job's token.
required: false
default: ""
audience:
description: The audience to ask GitHub for. Leave it empty for the one the control plane expects.
required: false
default: ""
ca-file:
description: A PEM file with the CA to trust for the proxy, for a deployment that uses a private CA.
required: false
default: ""
verify-attestation:
description: >-
Check the release's build provenance with `gh attestation verify`, on top of the
checksum. Fails if the GitHub CLI is missing. Turn it off only on runners without gh.
required: false
default: "true"
github-token:
description: Token for the GitHub API (resolving "latest" and verifying provenance). It needs no permissions.
required: false
default: ${{ github.token }}

outputs:
version:
description: The Limen release that was installed, for example v0.1.0.
path:
description: The directory that holds the limen binary (already on PATH).
logged-in:
description: '"true" if the job logged in as a bot.'

runs:
using: node24
main: src/main.mjs
post: src/post.mjs
5 changes: 5 additions & 0 deletions mise.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Everything this repository needs. `mise install` fetches all of it.
[tools]
node = "24.22.1"
actionlint = "1.7.12"
shellcheck = "0.11.0"
12 changes: 12 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"name": "setup-limen",
"version": "0.0.0",
"private": true,
"description": "GitHub Action: install the Limen CLI and log a workflow in as a bot",
"type": "module",
"license": "Apache-2.0",
"engines": { "node": ">=24" },
"scripts": {
"test": "node --test \"test/*.test.mjs\""
}
}
34 changes: 34 additions & 0 deletions src/lib/actions.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
// The few runner features this action uses, with no dependencies: log lines, workflow commands,
// and the GITHUB_ENV / GITHUB_PATH / GITHUB_OUTPUT / GITHUB_STATE files. Every function takes the
// environment, so tests can point it at temporary files.
import { randomUUID } from "node:crypto";
import { appendFileSync } from "node:fs";
import { EOL } from "node:os";

const escapeData = (s) => String(s).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");

export const info = (message) => process.stdout.write(`${message}${EOL}`);
export const warning = (message) => process.stdout.write(`::warning::${escapeData(message)}${EOL}`);
export const failure = (message) => process.stdout.write(`::error::${escapeData(message)}${EOL}`);

// An input, as the runner passes it: INPUT_<NAME> with spaces turned into underscores.
export function input(env, name) {
return (env[`INPUT_${name.replace(/ /g, "_").toUpperCase()}`] ?? "").trim();
}

function fileCommand(env, variable, key, value) {
const path = env[variable];
if (!path) return; // not running on a runner (unit tests, a local try-out)
const delimiter = `ghadelimiter_${randomUUID()}`;
appendFileSync(path, `${key}<<${delimiter}${EOL}${value}${EOL}${delimiter}${EOL}`);
}

export const setEnv = (env, key, value) => fileCommand(env, "GITHUB_ENV", key, value);
export const setOutput = (env, key, value) => fileCommand(env, "GITHUB_OUTPUT", key, value);
export const saveState = (env, key, value) => fileCommand(env, "GITHUB_STATE", key, value);
export const state = (env, key) => env[`STATE_${key}`] ?? "";

export function addPath(env, directory) {
if (!env.GITHUB_PATH) return;
appendFileSync(env.GITHUB_PATH, `${directory}${EOL}`);
}
21 changes: 21 additions & 0 deletions src/lib/exec.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { spawn } from "node:child_process";

// Run a program with an argument list (never a shell) and collect what it prints.
// `stream` copies the output to the job log as it arrives.
export function exec(command, args, { env, stream = false } = {}) {
return new Promise((resolve, reject) => {
const child = spawn(command, args, { env, stdio: ["ignore", "pipe", "pipe"] });
let stdout = "";
let stderr = "";
child.stdout.on("data", (chunk) => {
stdout += chunk;
if (stream) process.stdout.write(chunk);
});
child.stderr.on("data", (chunk) => {
stderr += chunk;
if (stream) process.stderr.write(chunk);
});
child.on("error", reject);
child.on("close", (code) => resolve({ code, stdout, stderr }));
});
}
Loading
Loading