Restricted Commands Documentation

This document describes all available restricted commands that require specific permissions to execute. These commands can be executed via GitHub issue or pull request comments using the @holdex bot.

Permission Requirements

Each command below specifies the required permission level. Permissions are checked based on:

Organization role: Requires the user to have a specific role (Administrator or Member) in the organization. The organization used for validation is either the organization explicitly specified in the command (for example, via an org argument) or, if not provided, the organization where the command is executed.
Repository permission: Requires the user to have a specific permission level (admin, maintain, write, triage, or read) in the repository. The repository used for validation is the repository provided in the command (for example, via a repository or owner/repo argument).

Permissions are automatically checked by the bot based on the GitHub user's actual role and permissions in the resolved organization or repository.

Command Format

All commands follow the pattern:

@holdex <object> <action> [arguments...]

Arguments can be provided as:

Flags: --key=value or --key="value with spaces"
Positional arguments: Some commands accept positional arguments (values without flags)

Available Commands

1. Org Add User

Adds a user to a GitHub organization with a specified role.

Access: Organization admin role required

Location: Issue and pull request comments

Command:

@holdex org add-user <username> | --username=<username> --role=<role> [--org=<org>]

Args Schema

Arguments:

Property	Type
`org`	`string`
`username` (*)	`string` (min length: 1)
`role` (*)	`'admin' \| 'member'`

(*) Required.

Example:

@holdex org add-user johndoe --org=holdex --role=member

2. Repo Apply Settings

Applies repository settings including visibility, branch protection, and merge settings.

Access: Repository admin permission required

Location: Issue and pull request comments

Command:

@holdex repo apply-settings <repo> | --repo=<repo> --visibility=<visibility> --deleteBranchOnMerge=<deleteBranchOnMerge> --allowUpdateBranch=<allowUpdateBranch>

Args Schema

Arguments:

Property	Type	Default
`repo` (*)	`string` (min length: 1)
`visibility` (*)	`'private' \| 'public'`
`deleteBranchOnMerge`	`string`	`'true'`
`allowUpdateBranch`	`string`	`'true'`

(*) Required.

Example:

@holdex repo apply-settings holdex/my-repo --visibility=private --deleteBranchOnMerge=true --allowUpdateBranch=true

3. Repo Sync Labels

Synchronizes issue types and labels for a repository according to the ledger configuration.

Access: Repository write permission required (also available with: admin, maintain)

Location: Issue and pull request comments

Command:

@holdex repo sync-labels <repo> | --repo=<repo>

Args Schema

Arguments:

Property	Type
`repo` (*)	`string` (min length: 1)

(*) Required.

Example:

@holdex repo sync-labels holdex/my-repo

4. Issue Attach Agreement

Attaches a Google Doc agreement to a GitHub issue. Duplicates a template document, performs text replacements, creates a Didit verification session, and updates the issue with links.

Access: Organization admin role required (validated in organization holdex)

Location: Issue and pull request comments

Command:

@holdex issue attach-agreement [<issueUrl> | --issueUrl=<issueUrl>] --firstName=<firstName> --lastName=<lastName> [--roleTitle=<roleTitle>] [--gmailEmail=<gmailEmail>] [--commencementDate=<commencementDate>] [--idNumber=<idNumber>] [--ratePerHour=<ratePerHour>] [--regAddress=<regAddress>] [--phoneNumber=<phoneNumber>] [--dateOfBirth=<dateOfBirth>] [--assigneeUsername=<assigneeUsername>]

Args Schema

Arguments:

Property	Type
`issueUrl`	`string`
`firstName` (*)	`string` (min length: 1)
`lastName` (*)	`string` (min length: 1)
`roleTitle`	`string`
`gmailEmail`	`string`
`commencementDate`	`string`
`idNumber`	`string`
`ratePerHour`	`string`
`regAddress`	`string`
`phoneNumber`	`string`
`dateOfBirth`	`string`
`assigneeUsername`	`string`

(*) Required.

Example:

@holdex issue attach-agreement https://github.com/org/repo/issues/123 --firstName=John --lastName=Doe --assigneeUsername=johndoe

5. Member Onboard

Onboards a new employee to the GitHub HR system. Creates a repository, README, invites the user, syncs labels, and creates HR-related issues.

Access: Organization admin role required (validated in organization holdex)

Location: Issue and pull request comments

Command:

@holdex member onboard --firstname=<firstname> --lastname=<lastname> --githubUsername=<githubUsername>

Args Schema

Arguments:

Property	Type
`firstname` (*)	`string` (min length: 1)
`lastname` (*)	`string` (min length: 1)
`githubUsername` (*)	`string` (min length: 1)

(*) Required.

Example:

@holdex member onboard --firstname=John --lastname=Doe --githubUsername=johndoe

Usage Notes

Command Execution Location: Each command has specific location restrictions (see individual command documentation above). Commands can be restricted to:
- Issue comments only: Cannot be executed in pull request comments
- Goal issue comments only: Must be executed in a goal issue (not a regular issue or pull request)
- Pull request comments only: Can only be executed in pull request comments
- Issue and pull request comments: Can be executed in both issue and pull request comments
  All commands require an organization context (they must be run in a repository that belongs to an organization).
Command Pattern: Commands must follow the exact pattern @holdex <object> <action> [arguments...]. The object and action are case-insensitive and will be normalized to lowercase.
Error Handling: If a command fails, the bot will post a comment with error details, including the specific error message to help with troubleshooting.
Success Indication: Successful commands will add a reaction to your comment:
- 👀 (eyes) reaction indicates the command was successfully parsed and triggered
- 🚀 (rocket) reaction indicates the command task completed successfully
Asynchronous Execution: Commands are executed asynchronously. After parsing and validation, the command is triggered and runs in the background. The initial reaction (👀) indicates the command was accepted, while the final reaction (🚀) indicates completion.
Positional Arguments: Some commands support positional arguments as a convenience - they can be used instead of flags for common parameters. Positional arguments are captured for arguments that don't start with --.
Default Values: Some optional parameters have default values. Check individual command documentation above for details. If a parameter is not provided and has no default, it will be omitted.
Value Formatting:
- Use quotes for values with spaces: --key="value with spaces" or --key='value with spaces'
- Values without spaces don't need quotes: --key=value
- Single or double quotes are supported
- Values are parsed exactly as provided (case-sensitive for values)