Dispatch Workflow

Create a workflow dispatch event.

Usage

var dispatch = require( '@stdlib/_tools/github/dispatch-workflow' );

dispatch( slug, id, options, clbk )

Creates a workflow dispatch event.

var opts = {
    'token': 'tkjorjk34ek3nj4!'
};

dispatch( 'stdlib-js/utils-property-symbols', 'test.yml', opts, clbk );

function clbk( error, data, info ) {
    // Check for rate limit information...
    if ( info ) {
        console.error( 'Limit: %d', info.limit );
        console.error( 'Remaining: %d', info.remaining );
        console.error( 'Reset: %s', (new Date( info.reset*1000 )).toISOString() );
    }
    if ( error ) {
        if ( error instanceof Error ) {
            throw error;
        }
        console.error( error.message );
    } else {
        console.log( JSON.stringify( data ) );
    }
}

The function accepts the following options:

• token: GitHub access token (required).
• protocol: request protocol. Default: 'https'.
• hostname: endpoint hostname. Default: 'api.github.com'.
• port: endpoint port. Default: 443 (https) or 80 (http).
• useragent: user agent string.
• ref: git reference for the workflow (branch or tag name). Default: 'main'.
• inputs: input key-value pairs overriding the defaults specified in the workflow file. The maximum number of properties is ten.

To specify a user agent, set the useragent option.

var opts = {
    'token': 'tkjorjk34ek3nj4!',
    'useragent': 'hello-github!'
};

dispatch( 'stdlib-js/utils-property-symbols', 'test.yml', opts, clbk );

function clbk( error, info ) {
    if ( info ) {
        console.error( info );
    }
    if ( error ) {
        if ( error instanceof Error ) {
            throw error;
        }
        console.error( error.message );
    } else {
        console.log( 'Success!' );
    }
}

Notes

• Rate limit information includes the following:

  • limit: maximum number of requests a consumer is permitted to make per hour.
  • remaining: number of remaining requests.
  • reset: time at which the current rate limit window resets in UTC seconds.

Examples

var dispatch = require( '@stdlib/_tools/github/dispatch-workflow' );

var opts = {
    'token': 'tkjorjk34ek3nj4!',
    'useragent': 'my-unique-agent'
};

dispatch( 'stdlib-js/utils-property-symbols', 'test.yml', opts, clbk );

function clbk( error, info ) {
    if ( info ) {
        console.error( info );
    }
    if ( error ) {
        if ( error instanceof Error ) {
            throw error;
        }
        console.error( error.message );
    } else {
        console.log( 'Success!' );
    }
}

Note: in order to run the example, you will need to obtain an access token and modify the token option accordingly.

---

CLI

Usage

Usage: ghdispatch [options] slug --id id

Options:

  -h,   --help                       Print this message.
  -V,   --version                    Print the package version.
        --protocol proto             Request protocol. Default: https.
        --hostname host              Hostname. Default: api.github.com.
  -p,   --port port                  Port. Default: 443 (https) or 80 (http).
        --token token                GitHub access token.
  --ua, --useragent ua               User agent.
        --id id                      ID or file name of the workflow.
        --ref                        git reference for the workflow.
        --inputs                     Input keys + values (key1=value,key2=...).

Notes

• In addition to the token option, the token may also be specified by a GITHUB_TOKEN environment variable. The command-line option always takes precedence.
• Requested resources are written to stdout.
• Rate limit information is written to stderr.

Examples

Setting the access token using the command-line option:

$ DEBUG=* ghdispatch 'stdlib-js/utils-property-symbols' --token <token> --id 'test.yml'

Setting the access token using an environment variable:

$ DEBUG=* GITHUB_TOKEN=<token> ghdispatch 'stdlib-js/utils-property-symbols' --id 'test.yml'