Skip to main content
Most of our code is available on GitHub. You can find our repositories at the Trew Knowledge GitHub Org or at the WP VIP GitHub Org. In some rare occasions, we might have repositories in other places like GitLab or Bitbucket. When starting a new project there are some things we need to do before we begin working on the code. This includes creating a new repository, adjusting settings and setting up CI/CD.

Initial Commit

For WP VIP projects it is all done for us using the VIP Go Skeleton repository as a template. For non-WP VIP projects, we need to it ourselves. Visit TK’s fork of WP VIP Skeleton, click on the “Use this template” button and follow the instructions.

Build, test & deploy

We need to set up the build, test and deploy process. This is usually done using GitHub Actions, but it can also be done using other CI/CD tools like CircleCI. This process differs between WPVIP and non-WPVIP projects.

WordPress VIP Projects

For WPVIP projects we use their CircleCI account. We need to request VIP to add the project to CircleCI. The way it works is that CircleCI will do everything we want it to do and in the end it will deploy the final code to another branch suffixed by -built (i.e. main-built). We then need to update the deployment branch through the WordPress VIP dasboard for that specific environment. See more details here. You can control what goes into the -built branch by adding and modifying a .deployignore file. This file should be added to the root of the project and should contain a list of files and folders that should not be included in the final build. It works the same way as a .gitignore file. Example Scenario: You want your source code to be in the main branch and the build folder to be ignored. However, you want the build folder to be included in the -built branch and the source folder to be ignored.

Non-WP VIP Projects

For Non-WPVIP projects we use GitHub Actions. This gives us much more flexibility. We need to create at least one new workflow file in the .github/workflows/ folder. Preferrably we should have at least 2. One workflow tracks changes to plugins and deploys only those. The other tracks changes to the theme and only builds and deploys the files it needs to. If you have multiple themes you should consider one workflow for each theme. Deployment is usually done via SSH. We need to add the SSH key and some other secrets to the repository and then use it in the workflow file.

Sample Configuration Files

.circleci/config.yml
version: 2
jobs:
	build:
		docker:
			# Pick a base image which matches the version of Node you need for
			# building from https://hub.docker.com/r/circleci/node/tags/
			#
			# Note: If using a different container, make sure it contains at least
			# git 2.6.0. (Use -stretch for circleci/node containers.)
			- image: cimg/node:18.17.1

		branches:
			# Don't build from a branch with the `-built` suffix, to
			# prevent endless loops of deploy scripts.
			# REQUIRED: If you're amended an existing config, the below are two
			# of the required lines you must add
			ignore:
				- /^.*-built$/
			only:
				- main

		steps:
			- checkout

			# Configure TK Blocks plugin build steps
			- run:
					name: 'Install npm packages for TK Blocks plugin'
					command: |
						cd plugins/tk-blocks
						npm ci
			- run:
					name: 'Build'
					command: |
						cd plugins/tk-blocks
						npm run build

			# Configure build step for the TK theme
			- run:
					name: 'Install npm packages'
					command: |
						cd themes/tk
						npm ci
			- run:
					name: 'Build'
					command: |
						cd themes/tk
						npm run build

			# Test to ensure the build was good, do not deploy bad stuff!
			- run:
					name: Test the build
					command: |
						if [ -f themes/tk/build/js/main.js ] && [ -f themes/tk/build/css/main.css ]; then
							echo "Build succeeded";
						else
							echo "Build failed, file missing"; exit 1
						fi

			# Uncomment this and supply your ssh fingerprint to enable CircleCI to push the built branch to GitHub
			- add_ssh_keys:
					fingerprints:
						- "b0:b5:0d:3e:d1:7d:58:fd:08:2f:03:fc:dd:4b:86:c3"

			# Run the deploy:
			# REQUIRED: If you're amended an existing config, the below are two
			# of the required lines you must add
			# This will push the result to the {currentbranch}-built branch
			- deploy:
					name: Deploy -built branch to github
					command: bash <(curl -s "https://raw.githubusercontent.com/Automattic/vip-go-build/master/deploy.sh")
.github/workflows/main.yml
name: main

on: [push]

jobs:
	deploy:
		runs-on: [ubuntu-latest]
		if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
		steps:
			- uses: actions/checkout@v4
			- uses: actions/setup-node@v4
				with:
					node-version: 18

			- name: Install Block Plugin Packages
				working-directory: ./plugins/project-name-blocks
				run: npm ci
			
			- name: Build Blocks
				working-directory: ./plugins/project-name-blocks
				run: npm run build
			
			- name: Install Theme Packages
				working-directory: ./themes/theme-name
				run: npm ci
			
			- name: Build Theme
				working-directory: ./themes/theme-name
				run: npm run build
			
			- name: Cleaning up before deployment
				run: |
					rm -fr .git
					rm -fr .github
					
			- name: Deploy to Production
				if: github.ref == 'refs/heads/main'
				uses: trewknowledge/rsync-deploy@master
				env:
					DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
					ARGS: "-az"
					FOLDER: ""
					SERVER_PORT: 22
					SERVER_IP: ${{ secrets.SERVER_IP }}
					USERNAME: ${{ secrets.USERNAME }}
					SERVER_DESTINATION: ${{ secrets.SERVER_DESTINATION }}
			- name: Deploy to Develop
				if: github.ref == 'refs/heads/develop'
				uses: trewknowledge/rsync-deploy@master
				env:
					DEPLOY_KEY: ${{ secrets.DEPLOY_KEY_DEVELOP }}
					ARGS: "-az"
					FOLDER: ""
					SERVER_PORT: 22
					SERVER_IP: ${{ secrets.SERVER_IP_DEVELOP }}
					USERNAME: ${{ secrets.USERNAME_DEVELOP }}
					SERVER_DESTINATION: ${{ secrets.SERVER_DESTINATION_DEVELOP }}
			- name: action-slack
				uses: 8398a7/[email protected]
				with:
					status: ${{ job.status }}
					author_name: "Github Slack Action"
					only_mention_fail: "here"
				env:
					GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
					SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Sample repository secrets

In order for GitHub Actions to work, you may need to add some secrets to the repository. These secrets are used to authenticate with the server and to deploy the code.
The following are only examples. Make sure you adjust to your situation.
KeyValue
SERVER_DESTINATION~/sites/site-folder-name/wp-content
SERVER_IPenvironment.ssh.wpengine.net
SLACK_WEBHOOK_URLhttps://hooks.slack.com/services/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
USERNAMEsshusername
DEPLOY_KEYThis is your private ssh key that will be used to connect to the server

Branch Protection

All projects should set the main branch as a protected branch. This means that no one can push directly to the main branch and all changes must be made through a pull request. This is to ensure that all changes are reviewed and tested before they are merged into the main branch. Here are the common rules we follow:
  • Require a pull request before merging
  • Require approvals (at least 1).
  • Dismiss stale pull request approvals when new commits are pushed.
  • Require status checks to pass before merging.
  • Require branches to be up to date before merging.

Pull Request templates

All projects should have a pull request template. This is a file that is automatically added to the pull request when it is created. It should contain a checklist of things that need to be done before the pull request can be merged.
.github/pull_request_template.md
## Description 📝

Please provide a brief summary of the changes and their purpose.

## JIRA Ticket(s) 🎫

- JIRA Ticket Link(s)

## Type of Change 🛠️

- [ ] Bug fix
- [ ] New feature
- [ ] Enhancement
- [ ] Documentation update
- [ ] Other (please specify): ________

## Area of Impacts 🎯

Please specify the area(s) of the codebase that this pull request impacts.

- [ ] Frontend/UI
- [ ] Backend/Server
- [ ] Database
- [ ] Infrastructure/Deployment
- [ ] Performance
- [ ] Security
- [ ] Documentation
- [ ] Testing
- [ ] Other (please specify): ________

## Multisite Impact 🌐

Does this PR code changes impact any other currently live site in the multisite environment?

- [ ] Yes
- [ ] No
- If Yes, please describe the impacted site(s) and the nature of the impact:

## Testing Steps ✔️

Describe the testing performed to ensure these changes work as intended.

## Screenshots (if applicable) 🖼️

Include any relevant screenshots to visually showcase the changes.

## Checklist ✅

- [ ] I have tested these changes locally.
- [ ] I have ensured that my code follows the coding standards of WPVIP.
- [ ] I have documented any necessary changes.
- [ ] My changes do not introduce new errors or warnings.
- [ ] I have reviewed my code for potential security issues.
- [ ] I have updated the documentation (if applicable).
- [ ] I have requested code review.

Generate a new Theme

At Trew Knowledge we have some scaffolding tools to help us get started. We have 3 theme generators.
  1. A Block Theme generator ( yo trewknowledge )
  2. A Hybrid Theme generator ( yo trewknowledge:hybrid )
  3. A Classic Theme generator ( yo trewknowledge:legacy )
For the most part, we don’t use the Classic Theme generator anymore. If you are not interested in working on a Full Site Editing theme, use the hybrid option. The classic generator will be deprecated soon.

How to use the generators

  1. Make sure your copy of the TK-Quickstart repository is up to date.
  2. Run yo trewknowledge in the terminal. It will then prompt you to answer a couple of questions about the theme. After that, it will generate a block theme for you.