CircleCI JS Client
A JavaScript client for CircleCI's v2 API.
Usage
Setup
First, go and get a CircleCI API Token.
Then all you need to do is import the client class and instantiate it with your token and optionally a project slug and default branch:
import CircleCI from 'circle-client';
const client = new CircleCI('2c818264d2557cd14b9fc3fa538df6ecbc6489f3', {
// this could also be "github/owner/repo"
slug: ['github', 'owner', 'repo'],
// methods that take a branch arg can override this
branch: 'main',
});
Your project slug consists of:
- The VCS provider (either
github
orbitbucket
) - The project's owner (e.g. your username or organization name)
- The repo name
Methods
Below is a summary list of available methods. Check out the main client file for fully-typed method signatures.
Paginated results: any method that begins with list
returns a Paged<T>
object, with an items
property containing the API results, and a next_page_token
property. If next_page_token
is set, you can use it to call the method again with the pageToken
argument set to that value to retrieve the next page of results.
🔗
Context -
listContexts
- List all contexts for an owner. -
createContext
- Create a new context. -
deleteContext
- Delete a context. -
listContextEnvVars
- List information about environment variables in a context, not including their values. -
createContextEnvVar
- Create or update an environment variable within a context. -
deleteContextEnvVar
- Delete an environment variable from a context.
🔗
Insights -
listWorkflowMetrics
- Get summary metrics for a project's workflows. -
listWorkflowRuns
- Get recent runs of a workflow. -
listWorkflowJobMetrics
- Get summary metrics for a project workflow's jobs. -
listWorkflowJobRuns
- Get recent runs of a job within a workflow.
🔗
User -
getMe
- Information about the user that is currently signed in. -
getCollaborations
- Provides the set of organizations of which the currently signed in user is a member or a collaborator. -
getUser
- Information about the user with the given ID.
🔗
Pipeline -
listPipelines
- Returns all pipelines for the most recently built projects you follow in an organization. -
getPipeline
- Returns a pipeline by ID. -
getPipelineConfig
- Returns a pipeline's configuration by ID. -
listPipelineWorkflows
- Returns a paginated list of workflows by pipeline ID. -
triggerProjectPipeline
- Triggers a new pipeline on the project. -
listProjectPipelines
- Returns all pipelines for this project. -
listOwnProjectPipelines
- Returns a sequence of all pipelines for this project triggered by the user. -
getProjectPipeline
- Returns a pipeline by number.
🔗
Job -
getJob
- Returns job details. -
cancelJob
- Cancel job with a given job number. -
listJobArtifacts
- Returns a job's artifacts. -
listJobTests
- Get test metadata for a build.
🔗
Workflow -
getWorkflow
- Returns summary fields of a workflow by ID. -
approveWorkflowJob
- Approves a pending approval job in a workflow. -
cancelWorkflow
- Cancels a running workflow. -
listWorkflowJobs
- Returns a sequence of jobs for a workflow. -
rerunWorkflow
- Reruns a workflow.
🔗
Project -
getProject
- Retrieves a project by project slug. -
listCheckoutKeys
- Returns a sequence of checkout keys for the project. -
createCheckoutKey
- Creates a new checkout key. -
deleteCheckoutKey
- Deletes the checkout key. -
getCheckoutKey
- Returns an individual checkout key. -
listEnvVars
- List all environment variables (masked). -
createEnvVar
- Creates a new environment variable. -
deleteEnvVar
- Deletes the environment variable named. -
getEnvVar
- Returns the masked value of an environment variable.
Other
-
downloadArtifact
- Download a job artifact and save it to disk.
Errors
In addition to Fetch errors, the following errors can occur:
- Any method that relies on a project slug will throw a
ProjectSlugError
if one is not set when the method is called. - When an API call is made, if the response status code does not equal the success code indicated for that endpoint in API documentation, an
APIError
will be thrown. The object contains amessage
(which might be generated by the client or the API),status
, and theresponse
object of the Fetch request. - A method may throw
ArgumentError
if an invalid set of arguments is provided that cannot be caught by TypeScript.
Development
Development is pretty straightforward:
- Run
yarn build
to generate a new distribution build. -
yarn lint
andyarn format
are also available and do exactly what they say.
Testing
Run tests:
-
yarn test
(optionally with--watchAll
)
Run the CircleCI test job locally:
- Download the CircleCI CLI
- If you're changing the config, validate your changes:
circleci config validate
- Generate a local config file:
circleci config process .circleci/config.yml > .circleci/local.yml
- Execute the test job:
circleci local execute -c .circleci/local.yml --job test