Documentation

Star Fork Download

The GitHub CMS project presents a system for enabling content management and publication capabilities on any GitHub Repository. Content is stored as GitHub Issues, managed through GitHub Projects, published by a GitHub Action to a GitHub Repository and hosted by GitHub Pages.

Introduction

A GitHub repository has all of the ingredients for serving as a content management system.

Features

Design

Glossary of Terms

Publication States

Source content can be in one of four publication states:

Publication Actions

The system supports the following actions. The general logic is described along with the action.

Architecture

There are four pieces that enable publishing:

  1. Publication process to execute publishing actions in response to content state changes
  2. Content “Source of Truth”
  3. Location to store published content
  4. Publication metadata

The architecture presented here is separated by functional role within the system (and, therefore, into separate repositories). Separate repositories are not a requirement and GitHub CMS can be completely self contained in a single repository.

Publication Process

The GitHub CMS Action represents the process that executes publication actions and manages publication state. This action is used by a Source Content Repository.

Source Content Repository

The GitHub Issues in this repository represent the “Source of Truth” for all content that is published by GitHub CMS Action. A GitHub Issue and content item are used interchangeably. They are the same from our perspective.

GitHub Projects in this repository are used to organize Issues into “Collections”. These projects also represent state machines used to move Issues between Staging, Published, Unpublished, and Archived states. State changes are observed and reacted to by GitHub CMS Action.

Target Publication Repository

This GitHub Repository hosts all content published from the Source Content Repository. GitHub CMS is configured to generate Markdown formatted text files containing Jekyll front-matter. This allows instant support for hosting published content with GitHub Pages.

Metadata Repository

This GitHub Repository stores the following information content items:

Installation

This guide will show you how to setup GitHub CMS across three separate repositories aligning to the following roles:

You must have an access token with the repo scope on the three repositories above. The easiest way to do this is to make sure all of the repositories are in your account and create a Personal Access Token with the repo scope.

See Creating a personal access token for the command line for more information.

Although separate repositories makes the components of the system very clear and flexible, it is not a requirement that you create one repository per role.

GitHub CMS can be setup in a single repository, if you wish. Simply use the same repository as you follow the setup instructions below.

Setup the Meta Repository

You can use any GitHub Repository (public or private) that you have repo access to. For this example, a repository was created at paulkoanui/meta-repo-1.

META_OWNER META_REPO
paulkoanui meta-repo-1

(in a future step, you will configure the publication workflow to use the above values)

Setup the Target Publication Repository

You can use any GitHub Repository (public or private) that you have repo access to. For this example, a repository was created at paulkoanui/target-content-repo-1.

TARGET_OWNER TARGET_REPO
paulkoanui target-content-repo-1

(in a future step, you will configure the publication workflow to use the above values)

Setup the Source Content Repository

You can use any GitHub Repository (public or private) that you have repo access to and that has Issues you wish to publish to a Target Publication Repository. For this example, a repository was created at paulkoanui/source-content-repo-1.

SRC_OWNER SRC_REPO
paulkoanui source-content-repo-1

(in a future step, you will configure the publication workflow to use the above values)

Setup GitHub CMS Publication

To complete installation and setup of publication capabilities on the Source Content Repository,

GitHub CMS Action is an open source GitHub Action that executes the publication process when Issues inside of a Project change columns (state). It can be used without downloading anything. Think of it like a GitHub Repository Plugin.

Create a Collection Project

  1. Go to Projects.
  2. Create a Project and add state columns.

For example, in the video below, we create a Project called “Posts” that will be used to publish Jekyll formatted blog posts.

Define the Publication Workflow

This is a YAML file, called github-cms.yml. It defines the publication process and how it operates. Once customized, this file will be placed in .github/workflows in the Source Content Repository.

See the Configuring a Workflow for GitHub Actions for more info.

Copy github-cms.template.yml

Configure Repository Details

In the env section of the workflow file, customize these values. Other values that you don’t have to change have been omitted for brevity.

  # This is the source system repository
  SRC_AUTH: ***
  SRC_OWNER: paulkoanui
  SRC_REPO: source-content-repo-1
  # This is the target system repository
  TARGET_AUTH: ***
  TARGET_OWNER: paulkoanui
  TARGET_REPO: target-content-repo-1
  # This is the metadata repository
  META_AUTH: ***
  META_OWNER: paulkoanui
  META_REPO: meta-repo-1

Setup to Observe Changes in the “Posts” Project

The “Posts” Project contains three state columns “Staging”, “Published”, “Archived”. GitHub CMS Action observes when Issues move to the “Published” or “Archived” columns.

  # Collections and actions mapped to project columns
  POSTS_PUBLISH_COLUMN: 8363572
  POSTS_ARCHIVE_COLUMN: 8363575

You can get the project column ID by choosing “Copy Column Link” image

Enable the Publication Workflow

To enable all of the GitHub CMS publication features, push github-cms.yml to the Source Content Repository at .github/workflows/github-cms.yml.

Try It Out: Publish a Post

With .github/workflows/github-cms.yml in place, content publication with GitHub CMS can begin!

Content Management

Stage Content

Staged content are GitHub Issues organized in the “Staging” column of a GitHub Project. Items in this state are waiting to be published or archived.

From the Source Content Repository:

“Staging” is simply an organizational state that says, “This item belongs in this collection but is not ready to be published or archived in its current form.”

Publish Content

Published content are GitHub Issues organized in the “Published” column of a GitHub Project. Items in this state are published to the Target Publication Repository.

From the Source Content Repository:

Archive Content

Archived content are GitHub Issues organized in the “Archived” column of a GitHub Project. Items in this state are archived to the Target Publication Repository.

The publication workflow, github-cms.yml, specifies the TARGET_ARCHIVE_PATH environment variable. The default value is _archive. So, if a published item exists at _pages/my-content-page.md, the archived path is, _archive/_pages/my-content-page.md.

From the Source Content Repository:

Unpublish Content

In order to unpublish content, you must remove it from the GitHub Project that manages its publication state.

From the Source Content Repository:

Updating Published or Archived Content

Content placed in the Target Publication Repository reflects Issue content at the time of the publication action. Therefore, subsequent updates to the published or archived issue are NOT automatically reflected in the target system.

To update Published content after changes:

To update Archived content after changes:

Credits

  1. PortfolYOU A Jekyll theme by Youssef Raafat.