github-project

JavaScript SDK for GitHub's new Projects

Features

• Use the new Projects as a database of issues and pull requests with custom fields.
• Simple interaction with item fields and content (issue/pull request) properties.
• Look up items by issue/pull request node IDs.
• 100% test coverage and type definitions.

Usage

<script type="module">
import GitHubProject from "https://cdn.skypack.dev/github-project";
</script>

import GitHubProject from "github-project";

A project always belongs to an organization and has a number. For authentication you can pass a personal access token with the write:org scope. For read-only access the read:org scope is sufficient.

fields is map of internal field names to the project's column labels.

const project = new GitHubProject({
  org: "my-org",
  number: 1,
  token: "ghp_s3cR3t",
  fields: {
    priority: "Priority",
    dueAt: "Due",
  },
});

// log out all items
const items = await project.items.list();
for (const item of items) {
  // every item has a `.fields` property for the custome fields
  // and an `.content` property which is set unless the item is a draft
  console.log(
    "%s is due on %s (Priority: %d, Assignees: %j)",
    item.fields.title,
    item.fields.dueAt,
    item.fields.priority,
    item.isDraft
      ? "_draft_"
      : item.content.assignees.map(({ login }) => login).join(",")
  );
}

// add a new item using an existing issue
// You would usually retriev the issue node ID from an event payload, such as `event.issue.node_id`
const newItem = await project.items.add(issue.node_id, { priority: 1 });

// retrieve a single item using the issue node ID (passing item node ID as string works, too)
const item = await project.items.get({ contentId: issue.node_id });

// item is undefined when not found
if (item) {
  // update an item
  const updatedItem = await project.items.update(item.id, { priority: 2 });

  // remove item
  await project.items.remove(item.id);
}

API

Constructor

const project = new GitHubProject(options);

project.items.list()

const items = await project.items.list();

Returns the first 100 items of the project.

project.items.add()

const newItem = await project.items.add(contentId /*, fields*/);

Adds a new item to the project, sets the fields if any were passed, and returns the new item. If the item already exists then it's a no-op, the existing item is still updated with the passed fields if any were passed.

Note: GitHub has currently no API to add a draft issue to a project.

project.items.get()

const item = await project.items.get(itemNodeId);

Retrieve a single item based on its issue or pull request node ID. Resolves with undefined if item cannot be found.

project.items.getByContentId()

const item = await project.items.getByContentId(contentId);

Retrieve a single item based on its issue or pull request node ID. Resolves with undefined if item cannot be found.

project.items.getByContentRepositoryAndNumber()

const item = await project.items.getByContentRepositoryAndNumber(
  repositoryName,
  issueOrPullRequestNumber
);

Retrieve a single item based on its issue or pull request node ID. Resolves with undefined if item cannot be found.

project.items.update()

const updatedItem = await project.items.update(itemNodeId, fields);

Update an exist item. To unset a field, set it to null. Returns undefined if item cannot be found.

project.items.updateByContentId()

const updatedItem = await project.items.updateByContentId(contentId, fields);

Update an exist item based on the node ID of its linked issue or pull request. To unset a field, set it to null. Returns undefined if item cannot be found.

project.items.updateByContentRepositoryAndNumber()

const updatedItem = await project.items.updateByContentRepositoryAndNumber(
  repositoryName,
  issueOrPullRequestNumber
  fields
);

Update an exist item based on the node ID of its linked issue or pull request. To unset a field, set it to null. Returns undefined if item cannot be found.

project.items.remove()

await project.items.remove(itemNodeId);

Removes a single item. Resolves with undefined, no matter if item was found or not.

project.items.removeByContentId()

await project.items.removeByContentId(contentId);

Removes a single item based on the Node ID of its linked issue or pull request. Resolves with undefined, no matter if item was found or not.

project.items.removeByContentRepositoryAndNumber()

await project.items.removeByContentRepositoryAndNumber(
  repositoryName,
  issueOrPullRequestNumber
);

Removes a single item based on the Node ID of its linked issue or pull request. Resolves with undefined, no matter if item was found or not.

License

ISC