The other day I was talking to a GovCMS site editor about how to change a webform. I explained that he could change the form, but when there was a deployment, it would get overridden.
We talked about the fact that that he could not run the docker locally at work (yet) so it wasn't possible for him to make this change, even though he was otherwise a good candidate to execute the change.
As an exercise I looked into how he might be able to issue a config merge request (MR) to his department's site, that could then be reviewed by another developer, and merged.
This example applies to a lot of configuration changes. A future article will show a much simpler option if you just want to update a single webform or view.
Before you start
Each project on GovCMS has a name. You can ask your GovCMS representative for it, but it will likely be your agency's three or four letter acronym (
dfat, etc). In this article I'll refer to it as FOOBAR, and you'll see it used in many URLs.
So, for this tutorial you'll need the following:
- Your FOOBAR name (it will be lowercase).
- Access to the Lagoon platform at
- Therefore access to the Git repository
- The ability to run the Git application locally somehow
- An available Lagoon dev environment (there's a limit of 5).
- A suitable site-builder role on the site (experience may vary). The key admin page you need to access is
Clone the repository
There are a couple of ways to run Git, and it's out of scope of this article. I'm assuming you have Git For Windows or Git running in a the Linux sub-system in Windows. Thankfully it's not the most difficult thing to get installed in a government department, as it will only require firewall/port access to the GovCMS platform.
From a command line, create a directory, and inside that directory run:
# The actual Git url is available at https://dashboard.govcms.gov.au/projects/FOOBAR git clone [email protected]:FOOBAR/FOOBAR.git # Enter the cloned repository. cd FOOBAR # Show what branch you are on - it should say "master". git branch
Create your sandbox
When you create a new branch with the right name, and push that branch. Lagoon will generate a non-production environment for you. When you visit https://dashboard.govcms.gov.au/projects/FOOBAR, you want there to be less than 5 already. Consult with developers who may currently be working on the site as well.
DEVELOPMENT ENVIRONMENTS IN USE
2 of 5
To create a new environment, run these steps.
# Create a new feature branch. Never do this unless you *need* an environment. git checkout -b feature/config20190511 # Push the new branch to the GovCMS repo. git push --set-upstream origin feature/config20190511
Now, it will take a while (up to 60 minutes it seems?) for the environment to be created. But it will be available at:
You may need to visit
https://dashboard.govcms.gov.au/projects/FOOBAR/FOOBAR-feature-config20190511/deployments and click "Deploy" to trigger.
Log in and change stuff
The new environment at
https://nginx-FOOBAR-feature-dev20190507.govcms.amazee.io/ is essentially a clone of the production site. You can log in with the same credentials and use it to test content changes and so on. Now you can change the site's contact form (
webform) or you want to add a new filter option to the
/admin/content page (a
view) or pretty much any config.
It's tricky to explain what is content and what is config, so it's out of the scope of this article, but to get started, these are config:
- block layout
- defining and changing fields on anything
And these are *not* config:
- url redirects
- url aliases
- block content.
Export the config to your local clone
Once you've finished updating the webform or admin view, or whatever you need to do, time to export the config. You'll need to be able to access the directory where the Git repo is on your local machine, and copy some downloaded files into it. Try these steps.
- Delete all files out of
./config/default/in your repo
- Go to
/admin/config/development/configuration/full/exportin the remote site.
- Click Export (download begins)
- Unzip the downloaded file
- Copy the downloaded files into the empty
Commit and push
Back to git now. You want to see the changes and then "commit" them, which is a local action. After that you will "push" them to the remote repository.
# This command will show you what has changed. git diff # Commit all the files locally. # Your message may refer to an issue number, but should at least be clear. git add config/default git commit -m"issue-123: Updating the contact us form." # Push to the GovCMS repository. git push
Whenever you push to a branch, a bunch of tests will run, and the environment will be rebuilt. That can take a while but you don't need to wait for it.
Create a Merge Request
https://projects.govcms.gov.au/FOOBAR/FOOBAR/tree/feature/config20190511 you should see a message saying you were the last one to push changes to this branch.
Hit "Create Merge Request", and complete the form. Give details about why you are making the change. You should be able to click the changes tab to see your changes. This is what other developers will look at when they review your merge request.
That's it, you're done! Send the merge request link to another developer for approval.
Psotscript: Things to consider
None of this is at all dangerous to do. You're going to create an MR (merge request) and it won't get approved if you did anything silly. Also, there are tests that run to make sure that your config can be imported (that you didn't seriously break stuff) and Drupal will not import configuration that would cause content to be lost.
Maybe some things to be aware of when you're working with multiple environments:
- Make sure "shield" is turned on in the non-production site at
- Always be mindful of which site you're working on.
- Remember that if you need a content change, this should be done in production before making the developer site (you can't copy the database over later)
- Delete your environment when you're done (good citizen)
Postscipt: The future looks brighter
Actually this is a pretty convoluted procedure compared to what I predict with be possible within the next six months. The addition of a "config merge" task in Lagoon will allow the following workflow that does not require any local development:
- Create a new feature branch directly in GitLab
- Deploy the environment
- Log in and change stuff
- Execute a "create a config MR" task in Lagoon
There are no architectural limitions in Drupal or Lagoon to provide this feature, and we built for Dept of Justice Vic four years ago, so it's perfectly achievable.