BitOps CLI

BitOps is a CLI tool for interacting with Bitbucket. It provides various commands to manage projects, repositories, and users within Bitbucket workspaces.

Table of Contents

1. Installation
2. Configuration

• Environment Variables

3. Usage

• Login
• Create a New Project
• Create a New Repository
• Add a User to a Repository
• Update Branch Restrictions
• Create a New Resource

4. Components

• Commands

5. Project Command
6. CI/CD
7. Development
8. License

Installation

To install BitOps, you need to have Node.js and npm installed on your machine. Then, you can install BitOps globally using npm:

npm install -g @prandogabriel/bitops

Configuration

Before using BitOps, you need to create a configuration file with your Bitbucket credentials. The configuration file should be located at ~/.bitops/config.json and should contain the following information:

{
  "username": "your-bitbucket-username",
  "appPass": "your-bitbucket-app-password"
}

Environment Variables

BITBUCKET_CLIENT_ID

You can configure the BITBUCKET_CLIENT_ID environment variable to your OAuth client ID. This is necessary for authenticating with Bitbucket using OAuth. To set this environment variable, you can use the following command in your terminal:

export BITBUCKET_CLIENT_ID=your-oauth-client-id

Make sure to replace your-oauth-client-id with your actual OAuth client ID.

Usage

After installing and configuring BitOps, you can use the following commands:

Login

To login using Bitbucket:

bitops login

Note: This login is via OAuth and will generate a credentials file with the token. However, due to limitations with OAuth for certain endpoints (e.g., adding users to a repository and editing permissions), we had to switch to using app passwords. The OAuth authentication resulted in errors like:

error: {
  type: 'error',
  error: {
    message: 'This API is only accessible with the following authentication types: apppassword, session, api_token'
  }
},
status: 403

Create a New Project

To create a new project:

bitops project new -n <project-name> -d <description> -w <workspace>

Command Options

Usage: bitops project new|n [options]

Create a new project (project)

Options:
  -n, --name <name>                Create a new project
  -d, --description <description>  Description of the resource
  -w, --workspace <workspace>      Workspace to create the resource
  -h, --help                       Display help for command

Create a New Repository

To create a new repository:

bitops repo new -n <repository-name> -p <project-key> -w <workspace> [--description <description>]

Command Options

Usage: bitops repo new|n [options]

Create a new repository

Options:
  -n, --name <name>                Specifies the name of the new repository
  -p, --project <project-key>      Specifies the project key under which the repository will be created
  -d, --description <description>  (Optional) Provides a description for the new repository
  -h, --help                       Display help for command

Add a User to a Repository

To add a user to a repository:

bitops repo add-user -u <user-account-id> --repository <repository-slug> [--role <role>]

Command Options

Usage: bitops repo add-user|au [options]

Add a user to a repository

Options:
  -r, --repo <repo>              Repo slug
  -u, --user-id <user_id>        User account id to add
  -w, --workspace <workspace>    Workspace to add the user to
  -P, --permission <permission>  Permission level for the user
  -h, --help                     Display help for command

Update Branch Restrictions

To update branch restrictions for a repository:

bitops repo update-branch-restriction --repository <repository-slug> --branch <branch-name> --restriction <restriction-type>

Command Options

Usage: bitops repo update-branch-restriction|ubr [options]

Update branch restrictions for a repository

Options:
  -r, --repo <repo>              Repo slug
  -b, --branch <branch>          Branch name
  -t, --restriction <type>       Restriction type
  -h, --help                     Display help for command

Create a New Resource

To create a new resource (project or repository):

bitops new|n [options]

Options:

• -p, --project <name>: Create a new project
• -r, --repo <name>: Create a new repository
• -d, --description <description>: Description of the resource
• -w, --workspace <workspace>: Workspace to create the resource
• -h, --help: Display help for command

Components

Commands

• login: Handles user authentication with Bitbucket.
• project: Manages project-related commands.
  • new: Creates a new project.
  • add-user: Adds a user to a project.
• repo: Manages repository-related commands.
  • new: Creates a new repository.
  • add-user: Adds a user to a repository.
  • update-branch-restriction: Updates branch restrictions for a repository.
• new|n: Creates a new resource (project or repository).

Project Command

Usage: bitops project|p [options] [command]

Project related commands

Options:
  -h, --help             display help for command

Commands:
  add-user|au [options]  Add a user to a project
  new|n [options]        Create a new project (project)
  help [command]         display help for command

CI/CD

We have workflows set up to publish the CLI to npm. Additionally, we use automated tests with Vitest, linting with Biome, and Commander for building the CLI in Node.js.

Development

To build the project, run:

npm run build

To run the project in development mode, use:

npm run build && node ./dist/index.js <command>

To run tests, use:

npm test

To lint and format the code, use:

npm run lint
npm run format

License

This project is licensed under the MIT License.