Contributing to MicroShift

Contribution Flow

1. Fork the openshift/microshift repository on GitHub.
2. Create a branch from main, or from a release-X.Y branch if proposing a backport.
3. Make changes.
4. Push to your fork and open a pull request against openshift/microshift.
5. Address review feedback (repeating steps 3-5 as needed).

Reviews are managed through the OWNERS file. All PRs require approval from a listed approver.

Branches: main tracks the next minor version. release-X.Y branches receive z-stream (patch) updates. Backports should target the appropriate release branch.

Development Environment

MicroShift requires a RHEL development environment. Two setup guides are available:

• VM-based development environment
• Cloud development environment

Key prerequisites:

• Go (see go.mod for the required version)
• Red Hat Enterprise Linux
• oc CLI (latest)

Building

Command	Purpose
make all	Build microshift, etcd, and generate-config binaries
make verify	Run standard verification checks (see Testing)
make cross-build-linux-amd64	Cross-compile for x86_64
make cross-build-linux-arm64	Cross-compile for aarch64
make rpm	Build RPM packages
make rpm-podman	Build RPMs in a container
make e2e	Run end-to-end tests

For RPM packaging details, see RPM Packages. For build system internals (variants, version tracking), see architecture.

Testing

Verification Scripts

Pre-merge checks run via scripts/verify/:

Script / Target	What it checks
make verify-go	golangci-lint, gofmt (Makefile target, not a script)
verify-shell.sh	shellcheck for all bash scripts
verify-rf.sh	Robot Framework syntax (robocop)
verify-py.sh	Python linting (flake8)
make lint-ansible (verify-ansible.sh, opt-in)	Ansible playbook and role linting
verify-containers.sh	Containerfile linting (hadolint)
verify-assets.sh	Asset integrity
verify-images.sh	Image blueprint validation
verify-licenses.sh	License compliance
verify-vendor-etcd.sh	Etcd vendor integrity
verify-crds.sh	CRD schema validation
verify-config.sh	Configuration file validation

Run the standard set with make verify (runs verify-fast + verify-vendor-etcd). CI runs additional checks via make verify-ci which adds verify-images and verify-licenses.

End-to-End Tests

MicroShift uses Robot Framework for E2E testing. Tests live in test/suites/, organized by feature area (standard, backup, greenboot, upgrade, network, storage, etc.).

Tests run against a remote MicroShift host via SSH. Copy the example variables file and configure it with your target host:

cp test/variables.yaml.example test/variables.yaml
# Edit test/variables.yaml with your host, SSH user, and key

Then run:

test/run.sh [suite paths...]

Without suite arguments, it runs a default set (standard1, standard2, and selected osconfig/storage tests). The script automatically sets up a Python virtual environment with Robot Framework.

Test Harness

The CI test harness provisions VMs, installs MicroShift, and runs Robot Framework tests. It supports two deployment modes (ostree and bootc), each with its own scenarios and image blueprints.

For the full test harness documentation — scenarios, naming conventions, image blueprint layers, VM lifecycle, and kickstart templates — see Test Harness.

For CI job configuration and Prow details, see OpenShift CI for MicroShift.

Rebase

MicroShift's dependencies are kept in sync with OpenShift via automated nightly rebases. For full details:

• Rebase overview
• Rebase procedure
• Rebase guidelines

Code Standards

Go

• Must pass golangci-lint and gofmt
• Enforced by make verify-go

Shell

• Shebang: #!/usr/bin/bash
• set -euo pipefail
• Quote all variables
• Must pass shellcheck

Python

• PEP 8
• Must pass flake8

Robot Framework

• Must pass robocop (scripts/verify/verify-rf.sh)

Ansible

• Run make lint-ansible to check the playbooks and roles under ansible/
• This check remains opt-in until the staged lint cleanup is complete and CI enforcement is enabled
• Rule families listed in .ansible-lint as warnings remain visible while the staged lint cleanup is in progress; they become fatal when removed from the warning list

General

• No hardcoded credentials — use environment variables or files
• Self-documenting code over comments

Commit Conventions

Prefix commits with the Jira ticket when applicable:

USHIFT-1234: add gateway API configuration options
OCPBUGS-5678: fix etcd startup timeout handling
NO-ISSUE: update contributor documentation

Use NO-ISSUE: for changes without a Jira ticket. Rebase commits follow a fixed pattern (update buildfiles, update manifests, etc.) generated by the automation.

CI

MicroShift uses OpenShift CI with Prow for continuous integration. PR test runs take approximately 45 minutes. Scenarios run in parallel on a hypervisor, each provisioning an independent VM.

CI configuration is managed in the openshift/release repository. For details on CI setup, job types, and manual testing, see OpenShift CI for MicroShift.

Review Process

All PRs require review from an approver listed in the OWNERS file. Reviewers check:

• Code quality and correctness
• Test coverage (Go unit tests and/or Robot Framework E2E tests)
• Documentation updates where applicable
• Adherence to code standards