Programmatic API

The backport package can be imported as a Node module for use in automation scripts. See the Backport GitHub Action for a real-world example.

backportRun(options, processArgs, exitCodeOnFailure)

Backport one or more commits programmatically. Commits can be selected via pullNumber or sha.

Arguments:

• options object — accepts all configuration options
• processArgs string[] — forward CLI arguments from the calling process (e.g. process.argv.slice(2))
• exitCodeOnFailure boolean — if true, sets a non-zero exit code on failure. Default: true

Example:

import { backportRun } from 'backport';

const result = await backportRun({
  options: {
    githubToken: 'ghp_very_secret',
    repoName: 'kibana',
    repoOwner: 'elastic',
    pullNumber: 121633,
    interactive: false,
  },
});

getCommits(options)

Retrieve information about commits and whether they have been backported. Useful for building dashboards or CI status checks.

Arguments:

• githubToken string (Required) — GitHub access token
• repoName string (Required) — Name of repository
• repoOwner string (Required) — Owner of repository (organisation or username)
• author string — Filter commits by GitHub username
• pullNumber number — Filter commits by pull request number
• sha string — Filter commits by commit sha
• sourceBranch string — Branch to list commits from. Defaults to the repository's default branch

Example:

import { getCommits } from 'backport';

const commits = await getCommits({
  githubToken: 'ghp_very_secret',
  repoName: 'kibana',
  repoOwner: 'elastic',
  pullNumber: 121633,
});

/*
[{
  sourceCommit: {
    committedDate: '2021-12-20T14:20:16Z',
    sha: 'd421ddcf6157150596581c7885afa3690cec6339',
    message: '[APM] Add note about synthtrace to APM docs (#121633)',
  },
  sourcePullRequest: {
    number: 121633,
    url: 'https://github.com/elastic/kibana/pull/121633',
    mergeCommit: {
      sha: 'd421ddcf6157150596581c7885afa3690cec6339',
      message: '[APM] Add note about synthtrace to APM docs (#121633)',
    }
  },
  sourceBranch: 'main',
  targetPullRequestStates: [
    {
      url: 'https://github.com/elastic/kibana/pull/121643',
      number: 121643,
      branch: '8.0',
      state: 'MERGED'
    }
  ]
}]
*/