# Chef Workstation


**Umbrella Project**: [Chef Workstation](https://github.com/chef/chef-oss-practices/blob/main/projects/chef-workstation.md)

* **[Project State](https://github.com/chef/chef-oss-practices/blob/main/repo-management/repo-states.md):** Active
* **Issues [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/main/repo-management/repo-states.md):** 14 days
* **Pull Request [Response Time Maximum](https://github.com/chef/chef-oss-practices/blob/main/repo-management/repo-states.md):** 14 days

Chef Workstation installs everything you need to get started using Chef products on Windows, Mac and Linux. It includes:

* Chef Workstation App
* Chef Infra Client
* Chef InSpec
* Chef Habitat
* Chef Command Line Tool
* Test Kitchen
* Cookstyle
* Various Test Kitchen and Knife plugins for clouds

## Getting Started

1. Download [Chef Workstation](https://www.chef.io/downloads)

2. Double-click the `.dmg` or `.msi` file to start the install process, or use the package manager for your Linux distribution.

3. Open a terminal, and try out an ad-hoc task. Here's the general usage:

    `chef-run  [flags] <Target host|IP|SSH|WinRM> <Resource> <Resource Name> [properties]`

  * Install the 'ntp' package on 'hostname' over ssh, using password from the environment:

    `chef-run username:$PASSWORD@hostname package ntp`

  * Create user 'timmy' on 'hostname' over winrm:

    `chef-run winrm://username@hostname user timmy`

  * Run the recipe 'nginx::passenger' on 'hostname' over ssh on port 2222 using a keyfile:

    `chef-run ssh://hostname:2222 -i ~/.ssh/id_rsa nginx::passenger`

4. Use `chef-run -h` for additional information about usage and available flags.

## Building Chef-Workstation Packages

We use Omnibus to describe our packaging. Please review [chef-workstation/omnibus/README.MD](https://github.com/chef/chef-workstation/tree/main/omnibus) for further details.

## Contributing

We use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages. The commit type determines how the version is bumped automatically after a merge to `main`:

| Commit prefix | Example | Effect |
|---|---|---|
| `fix:` | `fix: correct omnibus build path` | Patch bump (x.x.**N**) |
| `feat:` | `feat: add support for debian 14` | Minor bump (x.**N**.0) |
| `feat!:` or `BREAKING CHANGE:` in footer | `feat!: drop ruby 3.1 support` | Major bump (**N**.0.0) |
| `chore:`, `ci:`, `docs:`, `test:`, etc. | `chore: update dependencies` | No release |

The MR label (`version::patch`, `version::minor`, `version::major`) overrides the automatic detection if you need manual control.

## Release Process

Releases are automated via the `version-bump` CI job, which runs on every push to `main`:

1. `scripts/version-bump.sh` reads the MR labels for the merged commit and increments the `VERSION` file accordingly (patch by default).
2. The job uses the upstream GitLab pattern from [git-cliff docs](https://git-cliff.org/docs/gitlab): it runs with the `orhunp/git-cliff:latest` image and sets `GIT_STRATEGY=clone` plus `GIT_DEPTH=0` so changelog generation has full history and tags.
3. [git-cliff](https://git-cliff.org/) generates/updates `CHANGELOG.md` from conventional commit history since the last tag.
4. Both files are committed and a Git tag is pushed, which can then be used to trigger a release pipeline.

To trigger an actual package build and deployment, run the release pipeline manually from the GitLab UI (`CI/CD > Pipelines > Run pipeline`) on the version tag.

The CI variables `GITLAB_API_TOKEN` (read_api scope) and `GITLAB_PUSH_TOKEN` (write_repository scope) must be set in the project CI/CD settings for the version-bump job to function.

## Copyright and License

Code released under the [Apache license](LICENSE). Images and any trademarked content are Copyright 2018 by [Chef Software, Inc.](https://www.chef.io).
