Code Monkey home page Code Monkey logo

circle-client's Introduction

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 or bitbucket)
  • 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.

๐Ÿšง This set of endpoints are listed as Preview and may change without warning.

  • 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.

๐Ÿšง This set of endpoints are listed as Preview and may change without warning.

  • 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 a message (which might be generated by the client or the API), status, and the response 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 and yarn 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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.