This guide will help you understand the overall organization of the slsa-github-generator project, and direct you to the best places to get started contributing. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged.
This document is the single source of truth for how to contribute to the code base. Feel free to browse the open issues and file new ones, all feedback is welcome!
Before submitting code, you should first complete the following prerequisites.
Before you get started, you will need to signup for a GitHub user account.
Please make sure to read and observe the Code of Conduct.
It is not required to set up a developer environment in order to contribute to slsa-github-generator but it may be required for code changes.
slsa-github-generator uses primarily Go and TypeScript programming languages. However much of the logic of the project is implemented in GitHub Actions workflows that are written in YAML and make heavy use of Bash scripts.
This project also uses several linters in order to maintain code quality. If you wish to run these linters locally, follow the instructions for each of these to install them on your development machine.
- yamllint
- golangci-lint
- shellcheck
- eslint (NOTE: eslint is installed automatically so you don't need to install it)
Since this project includes reusable workflows for use on GitHub Actions local development is limited to building and testing the binaries used by the reusable workflows. The workflows themselves must be tested in your own fork.
Local commands that can be used for development are defined in the
Makefile. You can list the available targets by running make.
make
Most workflows are actually run when pushing to GitHub so in order to test that a code change is working you may want to set up a GitHub repository for testing. This repository should have some workflows that call the actions or reusable workflows you are testing.
Some example test repos:
A number of automated tests and linters are used to maintain stability and good code quality. New PRs that include new functionality should include automated tests for that functionality.
Pre-submits run on each Pull Request and will block it from being merged if
they fail. These tests are located in the .github/workflows
directory and begin with the prefix pre-sumbit.
Unit tests are run as pre-submit tests in the
pre-submit.units.yml file. You can run
unit tests locally using make. This requires that the Go runtime be installed.
make unit-test
This project has a number of End-to-End tests that are scheduled to run daily. These tests are located in the example-package repository and include a number of testing workflows. Please read the e2e testing README.md for more information about e2e tests.
You can run all linters using make.
make lint
These linters will also run as GitHub checks for pull requests via pre-submit.lint.yml file.
Please see RELEASE.md.
This project is part of the SLSA Community working with the SLSA Tooling SIG.
The #slsa-tooling
channel in the OpenSSF Slack is used for
communication and sharing ideas.
Communication about bugs, usage, and new feature development is also done on GitHub issues.