Integrating Personio, GitHub & Google Workspace

Managing and protecting employee data in a company is critical. Automating user management (processes of adding, removing, and updating users for employees) helps this run even smoother. Human resources teams manage a company’s employees, but normally they lack knowledge about how to improve this user management process. This is where Platform Engineering can lend a hand.

Personio

At Empathy.co, Personio was chosen as the tool to manage employee information and permissions. Empathy’s People Entrusting team uses Personio to take care of these areas: onboarding, offboarding, and employee data synchronisation.

GitHub

We are using GitHub as the hosting service for version control of code in the whole company. When users are onboarded, they are added to the company’s GitHub organisation. When they are offboarded, they are removed. In addition, they need to be added to the corresponding GitHub teams, with permissions to particular repositories. And, of course, there are employees who don’t need access to GitHub at all.

We are currently using the GitHub Teams plan at Empathy. This means each member of the organisation has a cost of just $4/month. User management in GitHub is essential to save costs and to avoid security issues.

Google Workspace

We are also using Google Workspace as the hosting service for the company’s email, file storage and other office tooling. When users are onboarded, they are added to the company’s Google Workspace account for the company. When they are offboarded, they are suspended, preventing their access to the company’s email and any other internal tools.

Also, new employees need to be added to the corresponding Google Workspace groups so emails can be sent to multiple users at the same time. Hence, every employee in the company needs a Google Workspace account.

Motivation

But how can we automate the process of adding, removing, and updating users in a company? How can we do this while keeping a single source of truth, avoiding three separate actions for these processes each time?

We have the solution to this problem. Personio can be your one source of truth for everything. It has a simple API and HR teams don’t even need access to GitHub or to the Google Workspace admin dashboard to manage it.

The history behind our improvements

First attempt

To start, the Platform Engineering team created the accounts in GitHub and Google Workspace by hand. The People Entrusting team also managed employees’ data in Personio manually. As the company grew more and more, we noticed this wasn’t efficient. Each action had to be replicated across three different areas: Personio, GitHub and Google Workspace.

Second attempt

So we decided to automate the process of adding, removing, and updating users in GitHub and Google Workspace using Terraform. With the help of Atlantis, every change was reviewed by another team member and applied directly within the pull request.

We created some modules in Terraform to manage GitHub resources: repositories, teams, branch protection rules, permissions to repositories, labels, etc. Modules were also created to manage Google Workspace resources: domains, users, groups, organisational units, aliases, user schemas, etc.

But we didn’t create these resources in Personio. The People Entrusting team was responsible for managing the company’s employees in Personio by themselves.

Third attempt

We decided to teach members of People Entrusting how to use Terraform to manage GitHub and Google Workspace resources independently. They were creating a pull request in a repository by copy/pasting or modifying the modules we had created.

We improved in the sense that the same person was performing all the actions, which removed friction between teams. The problem was that they needed to change the same data three times. And sometimes, of course, in one of the three places, there could be a typo or misspelling.

You may be surprised since Terraform is hard to learn and People Entrusting is not a technical team! But yes, we taught them to copy/paste Terraform modules, change the variables on the modules, and perform a GitHub pull request. Another People Entrusting team member reviewed the changes and approved the pull request, so, with the help of Atlantis, everything worked. However, this was still very manual, time-consuming work.

The solution

Building on our previous experiments, we took our approach to the next level. An easy-to-use, automated solution. We decided to implement a solution and keep Personio as a single source of truth, using Personio API, GitHub API and Google Workspace API.

Also, this solution is part of the keep it DRY principles, which stand for “Don’t Repeat Yourself”. So every piece of logic must have a single, unambiguous representation within a system.

A single team member of People Entrusting is now able to change data manually in Personio, and automatically update the data in GitHub and Google Workspace. If there is a typo or misspelling in the data, the team member can fix it. The data is automatically updated in GitHub and Google Workspace. They save time performing the actions, and they don’t need intervention from other teams.

Using GitHub Actions and Personio API, GitHub API and Google Workspace API, it’s possible to create some scripts in Node.js, for example, to create the solution.

As you can see in the following diagram, the solution is simple. We are using three different scripts to perform the actions. These scripts are being executed in the GitHub actions.

The first script (1) is pulling the data from Personio API and storing it in JSON files (active.json, onboarding.json, inactive.json) in the same repository with an autocommit process. This action is performed automatically by GitHub Actions with a cronjob, by default, within 1 hour. However, it can also be triggered manually. In this way, the cronjob pattern can be modified as you wish.
The second script (2) is updating the data in GitHub if there are any changes between Personio API and the employee data stored in this repository. The script will send a user invitation, create, modify, or delete teams and sub-teams, and delete users from the organisation.
The third script (3) is updating the data in Google Workspace if there are any changes between Personio API and the employee data stored in this repository. The script will send a welcome email to the user if it is a new user; create, modify or suspend users; add or remove user aliases; add or remove group members; update Gmail signatures to employees.

Other GitHub resources like GitHub repositories, branch protections, external contributors, and labels are still managed with Terraform.

Other Google Workspace resources such as Google Workspace domains, special users, groups, organisational units, and user schemas are still managed with Terraform as well.

You can check the instructions on how to set up this solution for your company in Empathy’s public repository. As you’ll see, you can extend and contribute with any other integration (Bitbucket, Azure Active Directory, GitLab, etc.).

GitHub permissions

At Empathy, we have just one organisation in GitHub. We organised the teams following GitHub best practices. So, we have a team that contains all the employees with GitHub access. Being a member of this team grants you push access to any repository in the organisation. Following this pattern, everyone can contribute to other repositories and can create pull requests to other teams. Of course, every team must create branch protections to all those repositories that are sensitive or delicate. This is to avoid any undesired push.

Also, we have subteams under the employee team. Something like this:

The subteams allow members to be mentioned on pull requests with the usage of CODEOWNERS files, and also to grant more permissions in the repositories, like admin or maintain access to perform more actions.

Apart from that, we are able to create other external teams using Terraform, granting access to a few private repositories in the organisation whilst preventing access to any other repositories.

References

You can check some references regarding GitHub best practices in the following links:

Customisation to Empathy

At Empathy, we also set VPN permissions based on a special user schema under Google Workspace. Therefore, we can set the VPN permissions for each employee in Personio too.

These permissions are based on which GitHub team you are part of. So, if you are part of the employee team, you can access the basic VPN subnets. If you are part of any other team, you can access the advanced VPN subnets assigned to that team.

This is very useful as some employees don’t need access to some subnets, for instance, to production subnets. In this way, we are preventing them from accessing production workloads, but they can access the development subnets in this case.

The flow of the solution at Empathy

With just one manual intervention on each action in Personio, all the changes are automatically applied in GitHub and Google Workspace.

Onboarding

A new hire is added to Personio, as they will become an employee in the near future.
People Entrusting team sets the hire date as agreed with the new employee.
On the new employee’s hire date, early in the morning, Personio will set the employee from onboarding to active status.
When the cronjob is executed, the script is executed to pull the data from the new employee.
The welcome email is sent to the new employee. The user in Google Workspace is created. If the new employee has set a GitHub username in Personio, an invitation is sent to the user. As soon as the user accepts the invitation, they will be part of the employee’s team and any other teams set in Personio.

Modifying users

An existing employee requests to modify their data in Personio.
People Entrusting team accepts the request in Personio.
The GitHub Action is executed automatically by the cronjob. All the changes are sent to GitHub and Google Workspace.

Offboarding

People Entrusting team sets the end date as agreed with the employee.
At the end of the end date, Personio will set the employee from active to inactive status.
When the cronjob is executed, the script is executed to pull the changes for the employee who is leaving.
The user is removed from the GitHub organisation if the employee has a set GitHub username in Personio. The user is suspended in Google Workspace. The user will no longer have access to GitHub or Google Workspace.

Next steps

If the employees need access to other tools like Slack, Atlassian, etc., we can implement a similar solution for those tools. Also, the users who are leaving can be removed from those tools automatically.

Another step that can be done is a backup solution for employee data in Google Workspace when they leave. In this way, you are GDPR compliant and can avoid suspending the user in Google Workspace indefinitely. This can save costs.

Coming soon

The integration we’ve explored in this article uses GitHub Actions, which can be executed with self-hosted runners instead of on-demand runners by GitHub. This lets us save some minutes on the free tier of GitHub Actions. In the next article, we will explain how to implement this self-hosted solution in Kubernetes. Save those minutes and avoid extra costs. Stay tuned!

Categories