Create user account

How this action creates a local user account on the device, which settings it has and when the step fails.

Use this action to create a local operating-system account on the device and, if you like, add it to the administrators group. The device must be online.

Configuration fields

Field	Type	Required	Default	Description
Account name	text	Yes	—	Name of the local account. Letters, digits, dots, underscores and hyphens are allowed. It must start with a letter or digit and be at most 20 characters long. Variables `${{ … }}` are allowed. octoja checks a name with a variable only at run time, once the variable is resolved.
Password	password	Yes	—	Password for a new account. It must meet the device's own password policy. octoja stores it but never shows it again. When you edit the step later, the field is empty; leaving it empty keeps the stored password. A variable in the field is resolved at run time.
Administrator	switch	No	Off	Adds the account to Administrators (Windows), sudo or wheel (Linux), or admin (macOS).

Platform support

Platform	Supported
Windows	Yes
Linux	Yes
macOS	Yes

What the new account looks like:

Platform	New account
Windows	Local account in the built-in Users group. Neither the account nor its password expires.
Linux	Account with a home directory. With Administrator, the account goes into the `sudo` group, or into `wheel` if there is no `sudo` group.
macOS	Local account. With Administrator, also a member of `admin`.

Outputs

Output	Description
`created`	`true` when this run created the account, `false` when it already existed.
`action`	Action: `created` or `alreadyExists`.

Result behaviour

Situation	Result
Account doesn't exist yet	Succeeded, `created` = `true`.
Account already exists	Succeeded, `created` = `false`, `action` = `alreadyExists`. The password is not reset. The step only ensures group membership: the Users group on Windows, and with Administrator the administrators group.
Password rejected by the password policy, or account creation fails	Failed. The device's error appears in the step result.
Administrator on, but the Linux device has neither `sudo` nor `wheel`	Failed.
Resolved account name breaks the naming rules	Failed with The resolved account name is not a usable local account name.
Password empty or containing a variable that couldn't be resolved	Failed with The password is empty or contains a variable that could not be resolved.
Device offline when the step starts	Device offline. Depending on If device is offline, the run ends with this status or the step is skipped.

The step only ever adds group memberships. Turning Administrator off later leaves an existing account in the administrators group. The step never deletes an account.

On Linux, the account can end up created while setting the password fails. The account then stays on the device, and later runs report it as existing without setting the password. In that case, set the password on the device or remove the account before running the step again.

Was this helpful?

Still need help? Ask the team