Developer Handbook

Welcome to the Developer Handbook, a comprehensive resource crafted to address key technical aspects involved in the development of information systems. Developed by the internal BĮIP team within the Government of Lithuania, this handbook aims to shed light on how our team approaches information system development and infrastructure management.

Our intention is to provide valuable insights to both our existing team members and newcomers, facilitating a deeper understanding of the technological landscape unique to BĮIP. By sharing our experiences and best practices, we hope to empower our team members in their roles within the engineering team.

While the primary focus is on guiding BĮIP team members, we acknowledge that this handbook may prove beneficial to other teams, particularly within the government of Lithuania. However, it’s important to note that the practices advocated by the BĮIP team may not be universally applicable to all teams.

Please be aware that this handbook is an ongoing project, a collaborative effort involving contributions from various individuals. Many sections are still under development. If you are interested in contributing to this endeavor, we welcome your assistance through pull requests on our GitHub repository: Developer Handbook Repository.

Your engagement is invaluable to the enhancement of this resource, and your feedback is highly appreciated. Thank you for joining us on this journey of continuous improvement in the realm of information system development.

Coding Standards

Prettier and ESLint

To ensure uniform code formatting across BĮIP projects, we leverage Prettier, and for identifying and fixing code issues, we rely on ESLint.

A unified configuration for both Prettier and ESLint is maintained, and detailed instructions can be found at biip-shared-configuration.

Implementation

We employ Husky to set up git hooks and lint-staged to selectively lint only the files intended for commit.

Example package.json configuration:

{
  "scripts": {
    "lint": "eslint --ext .js,.ts .",
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint"
    ],
    "*.{md,html,css}": "prettier --write"
  }
}

CodeQL

To identify vulnerabilities and errors, we utilize CodeQL as a robust static analysis tool. The default setup, complemented by the extended query suite, works seamlessly. Configuration is easily managed within the Code security and analysis settings, eliminating the need for defining custom CodeQL workflows.

CodeQL GitHub Integration

Dependabot

For streamlined management of dependency security updates, we employ Dependabot.

Dependabot alerts example

Custom Dependabot rules are provided for each repository, automating the assignment of reviewers and the initiation of pull requests exclusively for security updates.

Example Dependabot rules (.github/dependabot.yml):

version: 2
updates:
  # Maintain dependencies for npm
  - package-ecosystem: npm
    directory: /
    open-pull-requests-limit: 0
    schedule:
      interval: daily
    reviewers:
      - AplinkosMinisterija/biip-developers

  # Maintain dependencies for GitHub actions
  - package-ecosystem: github-actions
    directory: /
    open-pull-requests-limit: 0
    schedule:
      interval: daily
    reviewers:
      - AplinkosMinisterija/biip-devops

  # Maintain dependencies for Docker
  - package-ecosystem: docker
    directory: /
    open-pull-requests-limit: 0
    schedule:
      interval: daily
    reviewers:
      - AplinkosMinisterija/biip-devops

Self-hosted Runner

GitHub self-hosted runners play a crucial role in:

  • Kicking off deployment processes and accessing necessary virtual machines.
  • Executing GitHub Actions workflows, especially when GitHub-hosted runners fall short.

Authenticating Self-hosted Runners

Proper authentication is key. Avoid using personal access tokens for setting up self-hosted runners due to security risks. Instead, opt for GitHub Apps, offering a more secure alternative.

Important: Avoid Personal Access Tokens

Personal Access Tokens are linked to individual users, posing security risks if compromised. They often come with excessive privileges, leading to increased risk. Additionally, they require creating service accounts (resulting in additional license consumption) and are less secure compared to GitHub applications.

Creating a GitHub Application

  1. Go to your GitHub organization: Settings -> Developer Settings -> GitHub Apps -> New GitHub app.
  2. Enter the application name (e.g., BIIP Workflows Self-hosted Runner).
  3. Provide any homepage URL.
  4. Uncheck the “active” option for WebHooks.

Permissions

Choose between repository-scoped or organization-scoped runners. Set the following required permissions:

For Repository Runners:

  • Actions (read)
  • Administration (read/write)
  • Checks (read) (if using Webhook Driven Scaling)
  • Metadata (read)

For Organization Runners:

  • Actions (read)
  • Metadata (read)

Organization Permissions:

  • Self-hosted runners (read/write)

Private Key

Download the private key file by clicking “Generate a private key” at the bottom of the GitHub App page. This file will be used later in the installation process.

Installation

  1. Go to the “Install App” tab on the left side of the page.
  2. Install the GitHub App you created for your organization.
  3. Select the repositories where you want to install the GitHub app and use self-hosted runners.

Important: Avoid Installing Self-hosted Runners on Public Repositories

GitHub recommends using self-hosted runners exclusively with private repositories. Public repository forks could potentially execute malicious code on your self-hosted runner machine through pull requests. For more information, refer to GitHub’s documentation.

Credits