declastruct-github
v1.1.1
Published
declarative control of GitHub constructs via declastruct - manage repos, branches, and protection rules
Downloads
1,282
Maintainers
Readme
declastruct-github
Declarative control of Github resource constructs, via declastruct.
Declare the structures you want. Plan to see the changes required. Apply to make it so 🪄
install
npm install -s declastruct-githubuse via cli
example.1
wish ✨
declare the resources you wish to have - and what state you wish them to be in
import { UnexpectedCodePathError } from 'helpful-errors';
import { getDeclastructGithubProvider, DeclaredGithubRepo, DeclaredGithubRepoConfig } from 'declastruct-github';
export const getProviders = async (): Promise<DeclastructProvider[]> => [
getDeclastructGithubProvider(
{
credentials: {
token:
process.env.GITHUB_TOKEN ??
UnexpectedCodePathError.throw('github token not supplied'),
},
},
{
log: console,
},
),
];
export const getResources = async (): Promise<DomainEntity<any>[]> => {
// declare the repo
const repo = DeclaredGithubRepo.as({
owner: 'ehmpathy',
name: 'declastruct-github',
description: 'declarative control of Github resource constructs, via declastruct',
visibility: 'public',
});
// declare config for the repo
const repoConfig = DeclaredGithubRepoConfig.as({
repo,
// explicitly set the main branch
defaultBranch: 'main',
// we only use issues; the rest is noise today
hasIssues: true,
hasProjects: false,
hasWiki: false,
hasDownloads: false,
isTemplate: false,
// only squash merges are allowed
allowSquashMerge: true,
allowMergeCommit: false, // but especially not merge merges. never merge merges
allowRebaseMerge: false,
// always cleanup after yourself
deleteBranchOnMerge: true,
});
// and return the full set
return [repo, repoConfig];
};plan 🔮
plan how to achieve the wish of resources you've declared
this will emit a plan that declares the changes required in order to fulfill the wish
npx declastruct plan --wish provision/github/resources.ts --output provision/github/.temp/plan.jsonapply 🪄
apply the plan to fulfill the wish
this will apply only the changes declared in the plan - and only if this plan is still applicable
npx declastruct apply --plan provision/github/.temp/plan.jsonexample.2
export const getProviders = async (): Promise<DeclastructProvider[]> => [
getDeclastructGithubProvider(
{
credentials: {
token:
process.env.GITHUB_TOKEN ??
UnexpectedCodePathError.throw('github token not supplied'),
},
},
{
log: {
info: () => {},
debug: () => {},
warn: console.warn,
error: console.error,
},
},
),
];
export const getResources = async (): Promise<DomainEntity<any>[]> => {
// declare the repo
const repo = DeclaredGithubRepo.as({
owner: 'ehmpathy',
name: 'declastruct-github',
description: 'declarative control of Github resource constructs, via declastruct',
visibility: 'public',
});
// ref the main branch
const branchMain = RefByUnique.as<typeof DeclaredGithubBranch>({
name: 'main',
repo,
});
// declare config for the repo
const repoConfig = DeclaredGithubRepoConfig.as({
repo,
// explicitly set the main branch
defaultBranch: branchMain.name,
// we only use issues; the rest is noise today
hasIssues: true,
hasProjects: false,
hasWiki: false,
hasDownloads: false,
isTemplate: false,
// only squash merges are allowed
allowSquashMerge: true,
allowMergeCommit: false, // but especially not merge merges. never merge merges
allowRebaseMerge: false,
// always cleanup after yourself
deleteBranchOnMerge: true,
});
// declare protection for that branch, too
const branchMainProtection = DeclaredGithubBranchProtection.as({
branch: branchMain,
enforceAdmins: true, // yes, even admins need to follow this (note: they can still take the time to go and change the settings temporarily for the exceptions)
allowsDeletions: false, // dont allow the `main` branch to be deleted
allowsForcePushes: false, // dont allow `main` branch to be force pushed to
requireLinearHistory: false, // # no ugly merge commits, woo! 🎉
requiredStatusChecks: {
strict: true, // branch must be up to date. otherwise, we dont know if it will really pass once it is merged
contexts: [
'suite / install / npm',
'suite / test-commits',
'suite / test-types',
'suite / test-format',
'suite / test-lint',
'suite / test-unit',
'suite / test-integration',
'suite / test-acceptance-locally',
'pullreq-title', // "review / pullreq-title",
],
},
});
// and return the full set
return [repo, branchMain, repoConfig, branchMainProtection];
};