Sparrow is a bot runs jobs on Cloud Build events. It subscribes to Cloud Build
events through the Cloud PubSub topic cloud-builds, which is available out of
the box.
Sparrow can
- send messages to slack
- rewrite container image tags in Kubernetes manifest files
Sparrow might be helpful if you
- follow Trunk Based Development https://trunkbaseddevelopment.com/
- follow GitOps https://www.weave.works/technologies/gitops/
Sparrow is an alpha project and is subject to change (though it works well on our specific use case).
Sparrow sends messages to Slack on every Cloud Build event. A slack message has links to
- Cloud Build page of the build
- GitHub page of the commit
We plan to support
- filtering (e.g., only failed builds)
- mention
- sending messages to different channels (based on rules)
Sparrow rewrites container image tags in Kubernetes manifest files on GitHub by creating pull requests or pushing to master branch.
Sparrow assumes an app
- to have code repository and source repository
- to build container images on every push to the master branch
When a commit is pushed to the code repository's master branch,
- Cloud Build builds a container image where its tag is git SHA.
- The event is published to Cloud PubSub.
- Sparrow rewrites the tag in the config repository and creates a pull request or pushes the change to the master branch.
It should be noted that if you want to bypass creating pull requests and push to the master branch directly, the branch protection rule needs to be configured correctly that allows bypassing pull requests. https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule
For now, Sparrow supports the GitHub repositories connected to the Cloud Build via GitHub App or through Cloud Source Repositories.
A commit message of tag rewriting contains
- the commit message from the source repository's commit
- the link the source repository's commit on GitHub
Sparrow has many assumptions for tag rewriting to work. We don't have a plan to support other use cases (code and config repositories are the same for example) but contributions are welcome.
The behavior of Sparrow is configured by SPARROW_CONFIG that points to a path
of a YAML file. For example SPARROW_CONFIG=/etc/sparrow.yml.
The sparrow configuration YAML supports the following keys.
# Configuration spec version, currently 0.1.
version: 0.1
# `jobs` specifies what jobs to run from Cloud PubSub subscription X of project
# Y.
jobs:
# Run `Slack` job on events streamed from `project-a`'s Cloud PubSub
# subscription `slack`. `Slack` job sends messages to slack on every event.
- class: Slack
project_id: project-a
subscription: slack
# Run `GitOps` job on events streamed from `project-b`'s Cloud PubSub
# subscription `gitops`. `GitOps` updates container image tags on kubernetes
# manifest files.
- class: GitOps
project_id: project-b
subscription: gitops
class_args:
targets:
# When an event is from repository "org/app1", Sparrow evaluates the ERB
# template at `overlays/dev/kustomization.yaml.erb` in the
# configuration repository `org/app1-conf` and writes the evaluated
# result to `overlays/dev/kustomization.yaml`.
- source_repo: org/app1
config_repo: org/app1-conf
rewrites:
- name: dev
erb_path: overlays/dev/kustomization.yaml.erb
out_path: overlays/dev/kustomization.yaml
# If set to true, changes are pushed to master branch directly. (default: false)
bypass_pull_request: true
You can deploy Sparrow using Docker. Docker image is available at https://github.com/anipos/sparrow/pkgs/container/sparrow.
Sparrow requires
SPARROW_CONFIG: The path to the sparrow.yml.SPARROW_SLACK_WEBHOOK: Slack webhook URL.GITHUB_TOKEN: GitHub personal access token with "repo" scope.
The IAM key must have
- roles/pubsub.subscriber
- roles/pubsub.viewer
TBA.