Cargo Actions: An efficient tool for managing and creating GitHub Actions workflow templates
Tags: rust, cli, graphql, react
Published: 2024-05-31 07:04:03


In software development, continuous integration and continuous deployment (CI/CD) are crucial processes. To simplify this process, I developed Cargo Actions, a command-line tool based on the Rust language, which provides efficient workflow template management and creation functionality for GitHub Actions.

The main functions of Cargo Actions include:

1. **User authentication and login**: Securely integrate with GitHub via the OAuth 2.0 protocol, allowing users to log in to Cargo Actions using their GitHub accounts.
2. **Workflow initialization**: Support for initializing a workflow from a GitHub repository or template ID, providing a flexible way to integrate GitHub Actions workflows.
3. **Template upload and sharing**: Users can upload their own created workflow templates to the Cargo Actions platform and share them with other users.
4. **Personalized template management**: Allow users to manage their uploaded and favorite templates, facilitating the quick launch of familiar or commonly used workflow configurations.

## Installation

Run the following command in the terminal:

```bash
cargo install cargo-actions
```

## Usage

### Initialization

Create a project using the GitHub repository URL, and you can omit the https://github.com/ prefix. By default, the workflow template in https://github.com/yexiyue/cargo-actions will be used.

Using the abbreviated form, the rule (User/Repo) is:

```bash
cargo actions init yexiyue/cargo-actions
```

Using the URL form:

```bash
cargo actions init https://github.com/yexiyue/cargo-actions.git
```

Using the SSH form:

```bash
cargo actions init git@github.com:yexiyue/cargo-actions.git
```

![init command](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/init命令.gif)

You can also use the workflow on the [Cargo Actions platform](https://yexiyue.github.io/actions-workflow).

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/image.webp)

Copy the favorite workflow template to the terminal. For example:

```bash
cargo actions init 1 -i
```

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/id_init.gif)

### Upload Template

If you want to upload your own workflow to the Cargo Actions platform, please log in first.

```bash
cargo actions login
```

Then prepare a workflow template.

A standard workflow template should have the following files:

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/template-dir.webp)

- cargo-action.json: Configuration file used to prompt the user for input
- Template name.yaml.hbs: Template file
- README.md (optional)

`cargo-action.json` configuration field description

| Field Name | Type | Description |
| --------------- | -------- | --------------------------------------- |
| name | string | Template name |
| description | string | Short description of the template |
| path | string | Template file path, default `${name}.yaml.hbs` |
| prompts | Prompt[] | Defines the command-line interactive input items |
| success_message | string | Success message after template creation |

Prompt configuration instructions

There are 4 types of prompts:

1. type: "input"

| Field Name | Type | Description |
| ------- | ------ | -------------------------------- |
| field | string | Field name (corresponding to the variable name in the template) |
| prompt | string | Input prompt |
| default | string | Default value |

2. type: "confirm"

| Field Name | Type | Description |
| :------ | ------ | -------------------------------- |
| field | string | Field name (corresponding to the variable name in the template) |
| prompt | string | Input prompt |
| default | bool | Default value |

3. type: "select"

| Field Name | Type | Description |
| ------- | ------ | ---- |
| field | string | Field name (corresponding to the variable name in the template) |
| prompt | string | Input prompt |
| default | number | Index value of the default option |
| options | {value: any, label: string}[] | Option list, where label is the prompt value and value is the value used in the template at the end |

4. type: "multiselect"

| Field Name | Type | Description |
| ------- | ------ | ---- |
| field | string | Field name (corresponding to the variable name in the template) |
| prompt | string | Input prompt |
| default | number[] | Array of index values of default options |
| options | {value: any, label: string}[] | Option list, where label is the prompt value and value is the value used in the template at the end |

Example:

```json
{
  "name": "web-deploy",
  "description": "Build a web application to Github Pages",
  "prompts": [
    {
      "type": "select",
      "field": "toolchain",
      "prompt": "Please select a package management tool",
      "default": 0,
      "options": [
        {
          "label": "npm",
          "value": "npm"
        },
        {
          "label": "yarn",
          "value": "yarn"
        },
        {
          "label": "pnpm",
          "value": "pnpm"
        }
      ]
    },
    {
      "type": "confirm",
      "field": "enable_cache",
      "prompt": "Enable caching",
      "default": true
    },
    {
      "type": "input",
      "field": "node_version",
      "prompt": "Please enter the node version number",
      "default": "node"
    },
    {
      "type": "input",
      "field": "folder",
      "prompt": "Web project path",
      "default": "."
    },
    {
      "type": "input",
      "prompt": "Build artifact directory (relative to the web project path)",
      "field": "target_dir",
      "default": "dist"
    },
    {
      "type": "confirm",
      "prompt": "Copy index.html to 404.html to support spa",
      "field": "copy_index",
      "default": false
    }
  ]
}
```

The template file is rendered using [handlebars](https://docs.rs/handlebars/latest/handlebars/), and the template syntax can be referred to [Handlebars (handlebarsjs.com)](https://handlebarsjs.com/guide/).

Template file example:

```handlebars
name: web on: push: branches: - "master" workflow_dispatch: jobs: deploy:
runs-on: ubuntu-latest permissions: contents: write concurrency: group:
{{#raw}}$\{{ github.workflow }}-$\{{ github.ref }}{{/raw}}
steps: - name: Checkout repository uses: actions/checkout@v4
{{#if (eq toolchain "pnpm")}}
  - name: Install pnpm run: npm install -g pnpm
{{/if}}
- name: Sync node version and setup cache uses: actions/setup-node@v4 with:
node-version: "{{node_version}}"
{{#if enable_cache}}
  {{#if (eq toolchain "pnpm")}}
    cache: "{{folder}}/pnpm-lock.yaml"
  {{/if}}
  {{#if (eq toolchain "npm")}}
    cache: "{{folder}}/package-lock.json"
  {{/if}}
  {{#if (eq toolchain "yarn")}}
    cache: "{{folder}}/yarn.lock"
  {{/if}}
{{/if}}
- name: Install dependencies run: | cd
{{folder}}
{{toolchain}}
install - name: Build run: | cd
{{folder}}
{{toolchain}}
build
{{#if copy_index}}
  cp
  {{target_dir}}/index.html
  {{target_dir}}/404.html
{{/if}}
- name: Deploy uses: peaceiris/actions-gh-pages@v4 with:
{{#raw}}github_token: $\{{ secrets.GITHUB_TOKEN }}{{/raw}}
publish_dir:
{{folder}}/{{target_dir}}
```

Note:

Expressions in `{{{{raw}}}} {{{{/raw}}}}` will not be escaped.

Before uploading, you can use the `check` command to verify if the workflow template is working properly.

```bash
cargo actions check
```

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/check.gif)

Then use the `upload` command to upload the workflow template.

```bash
cargo actions upload
```

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/upload.webp)

### Using the created template

You can quickly use your own created workflow template with the following command, note that you need to log in.

```bash
cargo actions mine
```

You can also view the workflow template you created in the Cargo Actions platform [Personal Center](https://yexiyue.github.io/actions-workflow/user-center/mine).

![](https://yexiyue.github.io/picx-images-hosting/cargo-actions-readme/mine.webp)

### Using the favorite template

```bash
cargo actions favorite
```

This command is similar to the `mine` command, and allows you to select a workflow from the templates you favorited on the Cargo Actions platform for initialization.

### View more usage with the following command

```bash
cargo actions --help
```

## Conclusion

**If you are interested in Cargo Actions, welcome to visit [my GitHub repository](https://github.com/yexiyue/actions-workflow) for more information.**

**At the same time, if you find this tool helpful, don't forget to give it a like! Your support is the driving force for me to continuously update and improve.**