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
11 changes: 11 additions & 0 deletions .github/actionlint.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
paths:
# actionlint 1.7.12 knows actions/create-github-app-token@v3 by its older
# inputs; v3 itself takes client-id and deprecates app-id.
.github/workflows/update.yml:
ignore:
- 'missing input "app-id"'
- 'input "client-id" is not defined'
.github/workflows/merge.yml:
ignore:
- 'missing input "app-id"'
- 'input "client-id" is not defined'
8 changes: 7 additions & 1 deletion .github/config/release-please-config.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
{
"packages": {
".": {
"release-type": "simple"
"release-type": "simple",
"extra-files": [
{
"type": "generic",
"path": "devcontainer-sh"
}
]
}
}
}
92 changes: 85 additions & 7 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,94 @@ concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
contents: read

jobs:
test:
lint:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
timeout-minutes: 30
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Install Nix
uses: DeterminateSystems/nix-installer-action@v23

- name: Run ShellCheck
run: nix develop --command shellcheck --shell=bash devcontainer-sh

- name: Run actionlint
run: nix develop --command actionlint

- name: Build the Nix package
run: nix build

test:
strategy:
fail-fast: false
matrix:
# macOS runs the macOS system bash, 3.2, through /bin/bash first on PATH.
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Install Nix
uses: DeterminateSystems/nix-installer-action@v23

- name: Run Tests
run: nix develop --command bats tests/

- name: Run Tests with the system bash
if: runner.os == 'macOS'
run: |
mkdir -p "$RUNNER_TEMP/bash32"
ln -s /bin/bash "$RUNNER_TEMP/bash32/bash"
# PATH is changed inside the dev shell, so bats and the rest of its
# tools are still found; only `bash` now resolves to the system one.
# shellcheck disable=SC2016 # the inner sh expands these, on purpose
nix develop --command sh -c '
PATH="$1:$PATH"
bash --version | head -1
bats tests/
' _ "$RUNNER_TEMP/bash32"

# The action, used the way a workflow would use it, against a real container.
action:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Use the action
uses: ./

- name: Start the dev container
run: devcontainer-sh up --workspace-folder tests/fixtures/workspace

- name: Run a command in it
run: |
out="$(devcontainer-sh exec --workspace-folder tests/fixtures/workspace -- sh -c 'echo ok && id -un')"
echo "$out"
test "$(printf '%s\n' "$out" | head -1)" = ok

- name: The exit status comes through
run: |
nix develop --command bats tests/
if devcontainer-sh exec --workspace-folder tests/fixtures/workspace -- false; then
echo "expected a failure" >&2
exit 1
fi

- name: Remove the dev container
if: always()
run: devcontainer-sh down --workspace-folder tests/fixtures/workspace

release:
needs: test
needs: [lint, test, action]
if: github.event_name == 'push'
runs-on: ubuntu-latest
outputs:
Expand All @@ -54,3 +121,14 @@ jobs:
manifest-file: .github/config/release-please-manifest.json
config-file: .github/config/release-please-config.json
target-branch: main

# Callers pin the major version, e.g. @v1, so it follows every release.
- name: Move the major version tag
if: steps.release.outputs.release_created
env:
TAG: ${{ steps.release.outputs.tag_name }}
MAJOR: v${{ steps.release.outputs.major }}
run: |
git fetch --tags --quiet
git tag --force "$MAJOR" "$TAG"
git push --force origin "$MAJOR"
86 changes: 59 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,65 +1,97 @@
# devcontainer-sh

> Zsh plugin for the devcontainer CLI — one dispatcher command, workspace auto-detection, and tab completion. Stop typing `--workspace-folder`.
> A thin wrapper around the devcontainer CLI — one command, workspace auto-detection, tab completion, and a GitHub Action for CI. Stop typing `--workspace-folder`.

[![CI](https://github.com/devcontainer-env/devcontainer-sh/actions/workflows/ci.yml/badge.svg)](https://github.com/devcontainer-env/devcontainer-sh/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/devcontainer-env/devcontainer-sh)](https://github.com/devcontainer-env/devcontainer-sh/releases/latest)
[![Shell: zsh](https://img.shields.io/badge/shell-zsh-1793D1.svg)](https://www.zsh.org/)
[![Shell: bash](https://img.shields.io/badge/shell-bash-4EAA25.svg?logo=gnubash&logoColor=white)](https://www.gnu.org/software/bash/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

The upstream [`@devcontainers/cli`](https://github.com/devcontainers/cli) is powerful but verbose — nearly every invocation needs `--workspace-folder`, there's no first-class "shell into the container" verb, and rebuild-and-recreate is a stack of flags. This plugin smooths those edges without hiding the underlying CLI: unknown flags pass straight through.
The upstream [`@devcontainers/cli`](https://github.com/devcontainers/cli) is powerful but verbose — nearly every invocation needs `--workspace-folder`, there's no first-class "shell into the container" verb, and rebuild-and-recreate is a stack of flags. This tool smooths those edges without hiding the underlying CLI: unknown flags pass straight through.

It is one bash script, so the same commands work in your terminal and in CI.

## Installation

### oh-my-zsh
### GitHub Actions

```bash
git clone https://github.com/devcontainer-env/devcontainer-sh \
"${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/devcontainer-sh"
```yaml
steps:
- uses: actions/checkout@v7
- uses: devcontainer-env/devcontainer-sh@v1
- run: devcontainer-sh up
- run: devcontainer-sh exec -- make test
```

Then add `devcontainer-sh` to the `plugins=(...)` line in your `.zshrc`.
The action puts `devcontainer-sh` on `PATH` and installs the `devcontainer` CLI when it isn't already there. It doesn't start anything, so you choose when to `up`. GitHub-hosted runners are discarded after the job, so no cleanup is needed there. On self-hosted runners, add a step that always runs:

### zinit
```yaml
- run: devcontainer-sh down
if: always()
```

```zsh
zinit light devcontainer-env/devcontainer-sh
| Input | Description | Default |
| ------------- | ----------------------------------------------------- | -------- |
| `cli-version` | `@devcontainers/cli` version, if none is on `PATH` | `latest` |

### Nix

```bash
nix run github:devcontainer-env/devcontainer-sh -- up
nix profile install github:devcontainer-env/devcontainer-sh
```

### antidote
The package includes the zsh completions. It doesn't bundle the `devcontainer` CLI or Docker.

Add to your `.zsh_plugins.txt`:
### Any shell

```text
devcontainer-env/devcontainer-sh
Put the `devcontainer-sh` script on your `PATH`:

```bash
git clone https://github.com/devcontainer-env/devcontainer-sh ~/.devcontainer-sh
echo 'export PATH="$HOME/.devcontainer-sh:$PATH"' >> ~/.bashrc
```

### Manual
### zsh plugin managers

The plugin puts the script on `PATH` and registers the completions.

```bash
# oh-my-zsh
git clone https://github.com/devcontainer-env/devcontainer-sh \
"${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/devcontainer-sh"
# then add devcontainer-sh to plugins=(...) in ~/.zshrc
```

```zsh
git clone https://github.com/devcontainer-env/devcontainer-sh ~/.zsh/devcontainer-sh
echo 'source ~/.zsh/devcontainer-sh/devcontainer-sh.plugin.zsh' >> ~/.zshrc
# zinit
zinit light devcontainer-env/devcontainer-sh
```

```text
# antidote (.zsh_plugins.txt)
devcontainer-env/devcontainer-sh
```

## Requirements

- zsh 5.0+
- bash 3.2+ (the macOS system bash is enough)
- [`@devcontainers/cli`](https://github.com/devcontainers/cli) on `$PATH` (`npm i -g @devcontainers/cli`)
- Docker (for the `down` subcommand)
- Docker (for the `down` command)

## Usage

```text
Usage: devcontainer-sh <subcommand> [args...]
Usage: devcontainer-sh <command> [args...]

Subcommands:
Commands:
up Create and start the dev container for this workspace
shell, sh Open an interactive shell inside the container
exec Run a one-off command in the container
build Build the dev container image
down Stop and remove the container associated with this workspace
help Show usage
version Plugin version + upstream CLI version
version Wrapper version + upstream CLI version
```

**devcontainer-sh up** — Create and start the dev container. Auto-detects `--workspace-folder` by walking up from `$PWD` to find `.devcontainer/devcontainer.json` or `.devcontainer.json`.
Expand All @@ -79,7 +111,7 @@ devcontainer-sh shell bash # force bash
devcontainer-sh sh fish # short form
```

**devcontainer-sh exec** — Run a one-off command in the container. Everything is forwarded to `devcontainer exec`.
**devcontainer-sh exec** — Run a one-off command in the container. Everything is forwarded to `devcontainer exec`, and its exit status is passed through.

```bash
devcontainer-sh exec -- bash -lc 'pnpm test'
Expand All @@ -102,15 +134,15 @@ devcontainer-sh down

### Workspace auto-detection

All subcommands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override.
All commands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override. A `--workspace-folder` after a bare `--` belongs to the command you're running and is left alone.

### Pass-through

Unknown flags are forwarded to the upstream CLI untouched, so anything documented in `devcontainer up --help` / `exec --help` / `build --help` still works (`--log-level`, `--remote-env`, `--mount`, `--id-label`, …).
Unknown flags are forwarded to the upstream CLI untouched, so anything documented in `devcontainer up --help` / `exec --help` / `build --help` still works (`--log-level`, `--remote-env`, `--mount`, `--id-label`, `--secrets-file`, …).

### Tab completion

The plugin ships `_devcontainer-sh` (dispatcher) and `_devcontainer` (upstream binary) completion files. Both are added to `$fpath` on load — make sure `compinit` has been called in your `.zshrc` (oh-my-zsh / zinit / antidote do this for you).
Zsh completions ship for `devcontainer-sh` and for the upstream `devcontainer` binary (`completions/_devcontainer-sh` and `completions/_devcontainer`). The zsh plugin and the Nix package both put them on `$fpath`; make sure `compinit` has been called in your `.zshrc`.

## License

Expand Down
35 changes: 35 additions & 0 deletions action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: devcontainer-sh
description: >-
Put devcontainer-sh on PATH and install the devcontainer CLI, so later steps
can run devcontainer-sh up, exec and down.
author: devcontainer-env
branding:
icon: box
color: blue

inputs:
cli-version:
description: Version of @devcontainers/cli to install when none is on PATH.
required: false
default: latest

runs:
using: composite
steps:
- name: Add devcontainer-sh to PATH
shell: bash
env:
ACTION_PATH: ${{ github.action_path }}
run: echo "$ACTION_PATH" >> "$GITHUB_PATH"

- name: Install the devcontainer CLI
shell: bash
env:
CLI_VERSION: ${{ inputs.cli-version }}
run: |
if command -v devcontainer >/dev/null 2>&1; then
echo "devcontainer CLI already installed: $(devcontainer --version)"
exit 0
fi
npm install --global "@devcontainers/cli@${CLI_VERSION}"
devcontainer --version
6 changes: 3 additions & 3 deletions completions/_devcontainer
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ _devcontainer() {
typeset -A opt_args

_arguments -C \
'1: :->subcmd' \
'1: :->cmd' \
'*::arg:->args'

case "$state" in
subcmd)
cmd)
local -a subs=(
'up:Create and run dev container'
'set-up:Set up an existing container as a dev container'
Expand All @@ -22,7 +22,7 @@ _devcontainer() {
'templates:Templates commands'
'exec:Execute a command on a running dev container'
)
_describe -t commands 'devcontainer subcommand' subs
_describe -t commands 'devcontainer command' subs
;;
args)
case "$line[1]" in
Expand Down
6 changes: 3 additions & 3 deletions completions/_devcontainer-sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ _devcontainer_sh() {
typeset -A opt_args

_arguments -C \
'1: :->subcmd' \
'1: :->cmd' \
'*::arg:->args'

case "$state" in
subcmd)
cmd)
local -a subs=(
'up:Create and start the dev container'
'shell:Open an interactive shell in the container'
Expand All @@ -20,7 +20,7 @@ _devcontainer_sh() {
'help:Show usage'
'version:Show plugin and devcontainer CLI versions'
)
_describe -t subcommands 'subcommand' subs
_describe -t commands 'command' subs
;;
args)
case "$line[1]" in
Expand Down
Loading
Loading