Push To Autocomplete Action

In this section we will explain some common uses of the push-to-fig-autocomplete-action, refer to its README to learn more about it.

What is Push To Autocomplete?

Push to Autocomplete is a GitHub action that allows a seamless integration between third party CLI tools repos and the official autocomplete repo. When releasing a new version of a CLI tool there are often changes to the subcommands, to the options or to the arguments and this tool allows to automatically update the Fig autocomplete spec linked to that tool.

Configuration

Inputs

Required inputs

These inputs are required both if you are using normal specs or diff-versioned ones.

• token: a GitHub personal access token with repo scope, used to:
  • Create a fork of the autocomplete repo;
  • Create a branch with the updated spec on the forked autocomplete repo;
  • Create the PR against the autocomplete repo;
• autocomplete-spec-name: the name of the target autocomplete spec. Examples:
  • For src/figcli.ts or src/figcli/ (diff-versioned), autocomplete-spec-name is figcli
  • For scoped specs like src/@withfig/autocomplete-tools.ts or src/@withfig/autocomplete-tools/ (diff-versioned), autocomplete-spec-name is @withfig/autocomplete-tools
• spec-path: the path to the generated spec in the current repo

Optional inputs

These inputs are optional but often really useful.

• integration: the name of the integration to use when merging the spec, this is useless when diff-based-versioning: true (see integrations)
• diff-based-versioning (default: false): whether to use or not diff-versioned specs
• pr-body: the body of the PR created against the autocomplete repo

NOTE: When diff-based-versioning: true the spec needs not to be in the withfig/autocomplete repo at all or to already exist in the correct diff-versioned format.

diff-versioned spec inputs

These inputs are only used when diff-based-versioning: true.

• new-spec-version (required): the new version of the spec, this has to follow semantic versioning (package used for parsing)
• use-minor-base (default: false): whether to create a new diff from zero on each new minor

Example for a normal spec

This workflow uses the push-to-autocomplete-action to update a simple .ts spec file.

The newly generated spec gets merged with the old one using the merge tool and the merged spec is a .ts file that doesn't keep the history of added/removed/updated subcommands, options and args, but retains manually added data like generators or props that cannot be automatically added through the integrations.

name: 'Publish fig-cli version'
on:
  push:
    tags:        
      - 'v*' ## Only run the action on new versions, this prevents useless runs of the action

jobs:
  push-to-fig-autocomplete:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v2
      - name: Generate the spec ## This command creates a new spec file in the repo at ./new-fig-cli-generated.ts
        run: npm ci && npm run generate-fig-spec
      - name: Create Autocomplete PR ## Create the autocomplete PR using this action
        uses: withfig/push-to-fig-autocomplete-action@v1
        with:
          token: ${{ secrets.GITHUB_PAT_HERE }}
          autocomplete-spec-name: fig-cli
          spec-path: new-fig-cli-generated.ts
          integration: commander

Example for a diff-versioned spec

diff-versioned specs are special specs stored in folders that allow multiple versions and create diffs between each version in order to provide users with the best completions possible. All of this comes for free by using the @withfig/autocomplete-tools package that exposes commands to init or to add diffs to a diff-versioned spec. Under the hood autocomplete-tools is also used in this action and can be configured in the following way just by adding a couple parameters:

name: 'Publish fig-cli version'
on:
  push:
    tags:        
      - 'v*'

jobs:
  push-to-fig-autocomplete:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v2
      - name: Get new version ## Get the tag name that triggered this workflow and set it as an output
        id: version
        run: echo ::set-output name=tag::${GITHUB_REF#refs/*/}

      - name: Generate the spec ## This command creates a new spec file in the repo at ./new-fig-cli-generated.ts
        run: npm ci && npm run generate-fig-spec

      - name: Create Autocomplete PR ## Create the autocomplete PR using this action
        uses: withfig/push-to-fig-autocomplete-action@v1
        with:
          token: ${{ secrets.GITHUB_PAT_HERE }}
          autocomplete-spec-name: fig-cli
          spec-path: new-fig-cli-generated.ts
          diff-versioned-spec: true
          new-spec-version: ${{ steps.version.outputs.tag }}