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!
There are many areas in the project that need help. These are managed in GitHub issues. Please let us know if you are willing to work on the issue and how you can contribute.
- For new developers and contributors, please see issues labeled good first issue. These issues should require minimal background knowledge to contribute.
- For slightly more involved changes that may require some background knowledge, please see issues labeled help wanted
- For experienced developers, any of our open issues is open to contribution.
If you don't find an existing issue for your contribution feel free to create a new one.
This section covers what you need to set up a development environment, how to make changes, and how to submit them.
Before you decide to make a change, please take some time to identify an existing issue where you would like to contribute, or create a new issue. See How can I help? for more info.
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.
Some Node.js projects require Jest as a testing framework.
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)
This section will cover how to make changes and test them.
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. You can fork the slsa-github-generator repo via the Fork button.
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:
Local commands that can be used for development are defined in the
Makefile. You can list the available targets by running make.
makeWhen making changes in your fork, start by making a new branch.
git checkout -b my-feature-branchMake your changes and then commit them to your branch. Make sure to sign-off on your commits. This establishes Developer Certificate of Origin which indicates that you are the author of the changes and are able to submit it under the project LICENSE.
git commit -sYou may periodically need to merge with the main branch. Be sure to sign-off on the merges as well.
git merge --signoff mainBefore you submit your change run the unit tests and linters to ensure your changes are ready to go. See the Testing section for more info.
renovate-bot will periodically send PRs to update the package.json and package-lock.json in the Github Actions of this repo.
But, it will not also automatically recompile the packages into .js files.
We use a Workflow Update actions dist post-commit to help maintainers easily recompile the Github Actions against a PR.
Use the UI to invoke the workflow
update-actions-dist-post-commit.yml
or invoke with
gh workflow run update-actions-dist-post-commit.yml -F pr_number=<pull request number>Once your change is ready you can submit a PR via the website.
The title of your PR should include a Conventional Commits prefix label. For example, bug fixes should be prefixed with "fix:". PRs for new features should be prefixed with "feat:" etc.
Please also include as much information as your can about your change and any relevant issues in the PR description.
We prefer the use of the following programming languages:
- Go - For builders/generators.
- TypeScript - For GitHub actions.
- Bash - For scripts in GitHub actions and workflows.
We do not have a strict rule that proscribes the use of a specific language. However, any PRs that introduce a new language should include justification for adding the new language as well as a plan for adding the necessary tooling and testing infrastructure.
We will generally reject PRs that introduce the use of memory-unsafe languages or use of existing languages in memory-unsafe ways (e.g. the Go unsafe package). See the Security Policy for more info.
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-testTests for GitHub Actions created with Typescript require Jest.
make ts-testThis 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 lintThese 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.