https://github.com/form8ion/github
form8ion plugin for projects using GitHub as host for their git repository
https://github.com/form8ion/github
Last synced: about 2 months ago
JSON representation
form8ion plugin for projects using GitHub as host for their git repository
- Host: GitHub
- URL: https://github.com/form8ion/github
- Owner: form8ion
- License: mit
- Created: 2024-07-01T19:13:26.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2026-06-02T02:02:25.000Z (about 2 months ago)
- Last Synced: 2026-06-02T04:04:42.678Z (about 2 months ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@form8ion/github
- Size: 2.75 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome - github
README
# github
form8ion plugin for projects using [GitHub](https://github.com) as host for
their git repository
[![Node CI Workflow Status][github-actions-ci-badge]][github-actions-ci-link]
[![Codecov][coverage-badge]][coverage-link]
![SLSA Level 2][slsa-badge]
## Table of Contents
* [Features](#features)
* [Creation of GitHub repository](#creation-of-github-repository)
* [Configuration of GitHub Repository Settings](#configuration-of-github-repository-settings)
* [Usage](#usage)
* [Installation](#installation)
* [Enabling actions against the GitHub API](#enabling-actions-against-the-github-api)
* [Enabling repository configuration with `repository-settings/app`](#enabling-repository-configuration-with-repository-settingsapp)
* [Account-level settings](#account-level-settings)
* [Example](#example)
* [Import](#import)
* [Execute](#execute)
* [Contributing](#contributing)
* [Dependencies](#dependencies)
* [Verification](#verification)
## Features
### Creation of GitHub repository
When [authentication is provided](#enabling-actions-against-the-github-api),
a repository will be created on GitHub, assuming one does not already exist.
### Configuration of GitHub Repository Settings
This plugin configures repository settings by generating the settings file for
use by [repository-settings/app](https://github.com/respository-settings/app).
The settings in the file will be applied, along with those in the [account-level file](#account-level-settings),
once the generated file is pushed to GitHub in the default branch, assuming you
have the [repository-settings app installed](#enabling-repository-configuration-with-repository-settingsapp)
for your account.
## Usage
[![MIT license][license-badge]][license-link]
[![npm][npm-badge]][npm-link]
[![Try @form8ion/github on RunKit][runkit-badge]][runkit-link]
![node][node-badge]
### Installation
```sh
$ npm install @form8ion/github --save-prod
```
### Enabling actions against the GitHub API
Provide an authenticated octokit instance as the `octokit` property in the
options
### Enabling repository configuration with `repository-settings/app`
* Be sure to [install](https://github.com/apps/settings) for the user or
organization account that you are scaffolding the new project for.
* Enable the settings app for all repositories in the account
#### Account-level settings
The settings file generated by this tool assumes that it is extending an
[account level config](https://github.com/probot/probot-config#recipes)
* Ensure that you have created a `.github` repository in your account
* Create an [account-level settings file](https://github.com/probot/settings#inheritance)
in the `.github` repository at the location `.github/settings.yml` within the
repository
* for an organization account, [this is a good example](https://github.com/form8ion/.github/blob/master/.github/settings.yml)
* for a user account, [this is a good example](https://github.com/travi/.github/blob/master/.github/settings.yml)
### Example
#### Import
```javascript
import any from '@travi/any';
import {Octokit} from '@octokit/core';
import {lift, promptConstants, scaffold, test} from '@form8ion/github';
```
#### Execute
```javascript
const projectRoot = process.cwd();
const octokitInstance = new Octokit();
const logger = {
info: message => console.error(message),
success: message => console.error(message),
warn: message => console.error(message),
error: message => console.error(message)
};
await scaffold(
{
projectRoot,
projectName: 'project-name',
visibility: any.fromList(['Public', 'Private']),
description: any.sentence()
},
{
prompt: async ({id, questions}) => {
const {questionNames, ids} = promptConstants;
const {
GITHUB_DETAILS: githubDetailsPromptId,
ADMIN_SETTINGS: repositorySettingsPromptId
} = ids;
switch (id) {
case githubDetailsPromptId: {
const {
ORGANIZATION: organizationQuestionName,
ACCOUNT_TYPE: accountTypeQuestionName
} = questionNames[githubDetailsPromptId];
return {
[accountTypeQuestionName]: 'organization',
[organizationQuestionName]: questions
.find(({name}) => name === organizationQuestionName)
.choices
.find(({short}) => 'organization-name' === short).value
};
}
case repositorySettingsPromptId:
return {[questionNames[repositorySettingsPromptId].SETTINGS_MANAGED_AS_CODE]: any.boolean()};
default:
throw new Error(`Unknown prompt with ID: ${id}`);
}
},
octokit: octokitInstance,
logger
}
);
if (await test({projectRoot})) {
await lift(
{
projectRoot,
vcs: {owner: 'organization-name', name: 'project-name'},
results: {
projectDetails: {homepage: any.url()},
tags: any.listOf(any.word),
nextSteps: any.listOf(() => ({summary: any.sentence(), description: any.sentence()}))
}
},
{
octokit: octokitInstance,
logger,
prompt: async ({id, questions}) => {
const {questionNames, ids} = promptConstants;
const expectedPromptId = ids.REQUIRED_CHECK_BYPASS;
if (expectedPromptId === id) {
const {CHECK_BYPASS_TEAM: checkBypassTeamQuestionName} = questionNames[expectedPromptId];
return {
[checkBypassTeamQuestionName]: questions
.find(({name}) => name === checkBypassTeamQuestionName)
.choices
.find(({short}) => 'maintainers' === short).value
};
}
throw new Error(`Unknown prompt with ID: ${id}`);
}
}
);
}
```
## Contributing
[![Commitizen friendly][commitizen-badge]][commitizen-link]
[![Conventional Commits][commit-convention-badge]][commit-convention-link]
[![semantic-release: angular][semantic-release-badge]][semantic-release-link]
[![Renovate][renovate-badge]][renovate-link]
[![PRs Welcome][PRs-badge]][PRs-link]
### Dependencies
```sh
$ nvm install
$ npm install
```
### Verification
```sh
$ npm test
```
[commitizen-link]: http://commitizen.github.io/cz-cli/
[commitizen-badge]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
[commit-convention-link]: https://conventionalcommits.org
[commit-convention-badge]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
[semantic-release-link]: https://github.com/semantic-release/semantic-release
[semantic-release-badge]: https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release
[renovate-link]: https://renovatebot.com
[renovate-badge]: https://img.shields.io/badge/renovate-enabled-brightgreen.svg?logo=renovate
[PRs-link]: https://makeapullrequest.com
[PRs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
[github-actions-ci-link]: https://github.com/form8ion/github/actions?query=workflow%3A%22Node.js+CI%22+branch%3Amaster
[github-actions-ci-badge]: https://img.shields.io/github/actions/workflow/status/form8ion/github/node-ci.yml.svg?branch=master&logo=github
[coverage-link]: https://codecov.io/github/form8ion/github
[coverage-badge]: https://img.shields.io/codecov/c/github/form8ion/github/master?logo=codecov
[slsa-badge]: https://slsa.dev/images/gh-badge-level2.svg
[license-link]: LICENSE
[license-badge]: https://img.shields.io/github/license/form8ion/github.svg?logo=opensourceinitiative
[npm-link]: https://www.npmjs.com/package/@form8ion/github
[npm-badge]: https://img.shields.io/npm/v/@form8ion/github?logo=npm
[runkit-link]: https://npm.runkit.com/@form8ion/github
[runkit-badge]: https://badge.runkitcdn.com/@form8ion/github.svg
[node-badge]: https://img.shields.io/node/v/@form8ion/github?logo=node.js