Collaborative custom module development workflow for a Drupal 8 9 10 composer managed site. (Pantheon) (Private Repositories)

Because managing a custom module by itself unlocks a lot of great things.

My team wanted to build custom Drupal modules in a collaborative way, with an approval workflow, an issue queue, and a git workflow with inline code comments.

Requirements for our workflow:

• Private module repository.
• Github, GitLab, or Bitbucket workflows, approval processes, and code collaboration tools.
• Ability to pull our separately maintained and tracked modules into our Quickstart 2 Drupal site via Composer on Pantheon.

Note: For all custom code, never modify the Quickstart 2 installation profile, Drupal core, or contrib modules, instead, create a new custom module.

Note: If you must modify the Quickstart 2 codebase, it is recommended that a composer patching workflow is used. Quickstart 2 has this capabilitybuilt in.

How to create a custom module for use in this workflow.

First, you need a github organization, and an individual user account within that organization.

Under your organization’s Github namespace, create a new repository with the same name as your custom module.  The name of the custom module must be unique and use underscores in the repository name.
For example: If my github organization is az-digital and my module name is az_module_name, my module's Github namespace is az-digital/az_module_name.

Files required and suggested to enable the module in your Quickstart 2 site are as follows

• az_module_name.info.yml
• composer.json
• README.md

An example module can be found here: https://github.com/az-digital/azqs_module_project

Your new module's composer.json file should look similar to this one.

• The type key should be drupal-custom-module.
• The name key should be your module's namespace on github.
• The description key should describe what your module is for.
• The require key defines composer dependencies (i.e. drupal/feeds).

Your new module's az_module_name.info.yml file should look similar to this one.

• The name key should be the human readable module name
• The description key should be a short description of what the module is for.
• The type key should be module
• The core_version_requirement key should denote which versions of Drupal your module is compatible with.
• The package key can be used to add your module to a group.

In the end you should have a directory tree like this.

az_module_name (folder)

• az_module_name.info.yml
• composer.json
• README.md

Now that you have a barebones Drupal module that doesn't do anything and is hosted in your organizations Github namespace, you can move on to integrating your Github workflow with your Pantheon workflow.

In Github

Step one: Create a machine user in Github (machine users are just regular Github users, purposefully created to not be used by humans, basically it is a shared account, and should use a shared department netid). Or use an existing machine user that has read access to your new repository.
Step two: Add the new machine user as a collaborator to your new module repo.
Step three: Create a Personal Access Token in your machine user’s account, and add the repo scope. (This only needs to be done once per machine user).
Make sure to give it a good name, and copy the token somewhere that you can access it in the next step.

In Pantheon

Step four: In your local copy of your pantheon site, or via SFTP in the root directory that contains your SITE SPECIFIC composer.json
Add a file called auth.json, that has the following in it:

{ "http-basic": { "github.com": { "username": "your-machine-user-name", "password": "ghp\_your-machine-user-token" } } }

Step five: In your pantheon site specific composer.json file:
Add the following to the REPOSITORIES section:

"repositories": [ { "type": "vcs", "url": "[email protected]:az-digital/az_module_name.git" } ],

And to the require section

"require": { "your-github-organization/az_module_name": "dev-main" },

Step six: delete the composer.lock file and add and commit all changes.
Before committing and after adding you should see this in git status

Changes to be committed: (use "git restore --staged <file>..." to unstage) new file: auth.json modified: composer.json deleted: composer.lock

Step seven: push to dev and check pantheon dashboard for any errors, or run composer install.

Congratulations, you can now use github to manage, track, and review your custom modules.

Security notes: It is important that you do not store secrets in your private github repository because, anyone with access to your pantheon codebase will have the same access to github that your machine user does.  It would be prudent to test your github machine user's access levels to ensure that it can not write to your private repo or do anything else that you don't explicitly specify.