Manager Commands Documentation

This document describes all available manager commands that can be executed via GitHub issue or pull request comments using the @holdex bot.

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. User Add

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

Access: Manager only

Location: Issue comments only (not in pull requests)

Command:

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

Args Schema

Arguments:

(*) Required.

Example:

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

2. Repo Settings

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

Access: Manager only

Location: Issue comments only (not in pull requests)

Command:

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

Args Schema

Arguments:

(*) Required.

Example:

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

3. Agreement Attach

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: Manager only

Location: Issue comments only (not in pull requests)

Command:

@holdex agreement attach [<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:

(*) Required.

Example:

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

Replacement Value Flags (all optional):
These flags are used to replace placeholders in the Google Doc template:

• --firstName: Member first name
• --lastName: Member last name
• --roleTitle: Member role title (i.e.: Executive Assistant) - Default: "Software Developer"
• --gmailEmail: Member Gmail address
• --commencementDate: Member commencement date (YYYY-MM-DD)
• --idNumber: Member ID number
• --ratePerHour: Member rate per hour (USD)
• --regAddress: Member registered address
• --phoneNumber: Member phone number (i.e.: +852 7777 7777)
• --dateOfBirth: Member date of birth (YYYY-MM-DD)

4. Labels Sync

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

Access: Manager only

Location: Issue comments only (not in pull requests)

Command:

@holdex labels sync <repo> | --repo=<repo> [--owner=<owner>]

Args Schema

Arguments:

(*) Required.

Example:

@holdex labels sync my-repo --owner=holdex

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: Manager only

Location: Issue comments only (not in pull requests)

Command:

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

Args Schema

Arguments:

(*) Required.

Example:

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

Usage Notes

1. 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
     All commands require an organization context (they must be run in a repository that belongs to an organization).

2. 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.

3. Error Handling: If a command fails, the bot will post a comment with error details, including the specific error message to help with troubleshooting.

4. 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

5. 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.

6. 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 --.

7. 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.

8. 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)