github

form8ion plugin for projects using GitHub as host for their git repository

Table of Contents

• Features
  • Creation of GitHub repository
  • Configuration of GitHub Repository Settings
• Usage
  • Installation
  • Enabling actions against the GitHub API
  • Enabling repository configuration with repository-settings/app
    • Account-level settings
  • Example
    • Import
    • Execute
• Contributing
  • Dependencies
  • Verification

Features

Creation of GitHub repository

When authentication is provided, 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. The settings in the file will be applied, along with those in the account-level file, once the generated file is pushed to GitHub in the default branch, assuming you have the repository-settings app installed for your account.

Usage

Installation

$ 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 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

• Ensure that you have created a .github repository in your account
• Create an account-level settings file in the .github repository at the location .github/settings.yml within the repository
  • for an organization account, this is a good example
  • for a user account, this is a good example

Example

Import

import any from '@travi/any';
import {Octokit} from '@octokit/core';
import {lift, promptConstants, scaffold, test} from '@form8ion/github';

Execute

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

Dependencies

$ nvm install
$ npm install

Verification

$ npm test