Skip to content

docs: add release process section to README #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
probelabs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add release process section to README #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 57 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,23 @@
# Re-usable github actions

Check failure on line 1 in README.md

View check run for this annotation

probelabs / Visor: architecture

architecture Issue 

This pull request's primary goal is to add a 'Release process' section. However, it also introduces undocumented and significant side-effects by removing substantial documentation for several existing actions and workflows, such as for the 'OWASP scanner' and 'Sentinel One CNS Scans'. The PR description attributes these changes to regenerating the README file, but does not justify the removal of content. This loss of documentation is a significant regression for the repository's usability. The scope of this PR should be limited to its stated purpose, or the documentation removal must be explicitly justified and discussed.
Raw output 
Revert the changes to the README file that are unrelated to the release process documentation. If the documentation for other actions is indeed outdated and needs to be removed, this should be done in a separate pull request with a clear description of the changes and their reasoning.

Collection of shared github actions and workflows which are used in our org.

# Release process

We use a floating tag `@production` to release and distribute GitHub Actions from this repository.

All product repositories (such as `tyk`, `tyk-analytics`, etc.) must pin their GitHub Actions usage to the `@production` tag.

The `@production` tag is moved to the latest version of the `main` branch when changes need to be promoted.

The process:

1. Contributors (editing this repository is limited to the internal Tyk team) will create a Pull Request (PR) to `main`.
2. The `main` branch is protected and requires a Pull Request and review before merging.
3. When the PR is merged, changes are not yet used across all repositories; moving the tag is needed.
4. The contributor needs to ask on the Slack channel `#team-ext-non-functional` to move the `@production` tag.
5. Editing/moving this tag is limited to repository owners.

# Composite actions

## PR Checkout
Expand Down Expand Up @@ -30,11 +46,11 @@

Source: [/.github/actions/checkout-pr/action.yml](/.github/actions/checkout-pr/action.yml)

## Github to slack
## Upload Failed Job Logs

Maps github email with slack user, based on a key value map. Maps needs to be mantained manually.
On workflow job failure, fetch and send relevant logs with branch information to an external API

Source: [/.github/actions/github-to-slack/action.yaml](/.github/actions/github-to-slack/action.yaml)
Source: [/.github/actions/gh-logs-analyser/action.yaml](/.github/actions/gh-logs-analyser/action.yaml)

## Calculate tests tags

Expand All @@ -44,6 +60,12 @@

# Reusable workflows

## Branch Suggestion for PRs

Undocumented action.

Source: [/.github/workflows/branch-suggestion.yml](/.github/workflows/branch-suggestion.yml)

## CI tooling

We build a docker image from the CI pipeline in this repository that
Expand Down Expand Up @@ -107,12 +129,30 @@

Source: [/.github/workflows/ci-lint.yml](/.github/workflows/ci-lint.yml)

## CI Tests

Undocumented action.

Source: [/.github/workflows/ci-test.yml](/.github/workflows/ci-test.yml)

## Create or update a GitHub comment

Undocumented action.

Source: [/.github/workflows/create-update-comment.yaml](/.github/workflows/create-update-comment.yaml)

## Dependency Change Guard

Undocumented action.

Source: [/.github/workflows/dependency-guard.yml](/.github/workflows/dependency-guard.yml)

## Force Merge PR (Reusable)

Undocumented action.

Source: [/.github/workflows/force-merge.yaml](/.github/workflows/force-merge.yaml)

## Print Go API Changes

For a PR, the action will print the changes in `go doc` output. This
Expand Down Expand Up @@ -204,6 +244,12 @@

Source: [/.github/workflows/nancy.yaml](/.github/workflows/nancy.yaml)

## Path-Based OSV Scan

Undocumented action.

Source: [/.github/workflows/osv-path-scan.yml](/.github/workflows/osv-path-scan.yml)

## OWASP scanner

Example usage:
Expand All @@ -215,56 +261,48 @@
with:
target: http://staging-url.com
```

Source: [/.github/workflows/owasp.yaml](/.github/workflows/owasp.yaml)

## Release bot

```
name: Release bot
## Cherry-pick to Release Branch (light checkout + GitHub App, resilient)

on:
issue_comment:
types: [created]
Undocumented action.

jobs:
release_bot:
uses: TykTechnologies/github-actions/.github/workflows/release-bot.yaml@main
```
Source: [/.github/workflows/release-bot.yaml](/.github/workflows/release-bot.yaml)

## PR Agent
## SentinelOne CNS Scan

Undocumented action.

Source: [/.github/workflows/pr-agent.yaml](/.github/workflows/pr-agent.yaml)
Source: [/.github/workflows/s1-cns-scan.yml](/.github/workflows/s1-cns-scan.yml)

## SBOM - source bill of materials (dev)

Undocumented action.

Source: [/.github/workflows/sbom-dev.yaml](/.github/workflows/sbom-dev.yaml)

## SBOM - source bill of materials

Adoption: Gateway, Dashboard.

Source: [/.github/workflows/sbom.yaml](/.github/workflows/sbom.yaml)

## Semgrep

CodeQL like OSS linter

Example usage:

```yaml
jobs:
semgrep:
uses: TykTechnologies/github-actions/.github/workflows/semgrep.yaml@main
```

Usage: unknown; Status: a bit out of date.

Recent images use `semgrep/semgrep`, while this workflow still uses

Check failure on line 305 in README.md

View check run for this annotation

probelabs / Visor: quality

documentation Issue 

The regeneration of `README.md` has removed detailed documentation and usage examples for several workflows, such as 'Release bot' and 'SentinelOne CNS Scans', replacing them with 'Undocumented action'. This is a documentation regression that makes the workflows harder to use.
Raw output 
The script that generates the README (`docs/Taskfile.yml` and its `markdown` task) appears to have changed its behavior or is missing logic to include existing documentation. The script should be fixed to correctly include the documentation for all actions and workflows. After fixing the script, regenerate the `README.md` to restore the lost documentation before merging.
`returntocorp/semgrep`. Looks to be compatible at time of writing.

If you'd like to use semgrep:
Expand Down Expand Up @@ -308,40 +346,9 @@

Source: [/.github/workflows/sonarcloud.yaml](/.github/workflows/sonarcloud.yaml)

## Sentinel One CNS Scans

This runs the S1 scans and publishes the results to the S1 console.
It has three available scanners.
- Secret scanner
- IaC scanner
- Vulnerability scanner
## Visor

By default, all three are enabled, but it could be controlled by setting the flags appropriately
while calling the workflow.
Also, keep in mind that the secret scanner runs only on pull request events, as the scanner only supports
publishing results on pull requsts.

Example usage:

```yaml
name: SentinelOne CNS Scan
Undocumented action.

on:
pull_request:
types: [ opened, reopened, synchronize ]
branches: [ master ]
Source: [/.github/workflows/visor.yaml](/.github/workflows/visor.yaml)

jobs:
s1_scanner:
uses: TykTechnologies/github-actions/.github/workflows/s1-cns-scan.yml@main
with:
iac_enabled: false
tag: service:vulnscan
scope_type: ACCOUNT
secrets:
S1_API_TOKEN: ${{ secrets.S1_API_TOKEN }}
CONSOLE_URL: ${{ secrets.S1_CONSOLE_URL }}
SCOPE_ID: ${{ secrets.S1_SCOPE_ID }}
```

Source: [/.github/workflows/s1-cns-scan.yml](/.github/workflows/s1-cns-scan.yml)
2 changes: 2 additions & 0 deletions Taskfile.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,6 @@ tasks:
- echo >> README.md
- echo "Collection of shared github actions and workflows which are used in our org." >> README.md
- echo >> README.md
- cat docs/release-process.md >> README.md
- echo >> README.md
- cd docs && task markdown >> ../README.md
15 changes: 15 additions & 0 deletions docs/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Release process

We use a floating tag `@production` to release and distribute GitHub Actions from this repository.

All product repositories (such as `tyk`, `tyk-analytics`, etc.) must pin their GitHub Actions usage to the `@production` tag.

Check warning on line 5 in docs/release-process.md

View check run for this annotation

probelabs / Visor: security

security Issue 

The documented release process mandates the use of a floating tag (`@production`) for consuming GitHub Actions. This practice introduces a supply chain risk, as any new code pushed to the `main` branch and tagged as `@production` is automatically adopted by all consumers. If a malicious or faulty commit is merged, it will be immediately propagated across all workflows, potentially causing widespread disruption or security breaches. Pinning to a floating tag sacrifices the immutability and verifiability of dependencies.
Raw output 
For enhanced security and stability, consumers should pin actions to specific, immutable Git commit SHAs (e.g., `TykTechnologies/github-actions@<commit-sha>`). This ensures that workflows use a specific, vetted version of the action. If using tags is preferred, use versioned, immutable tags (e.g., `@v1.2.3`) instead of a floating tag. The release process should be updated to create versioned tags upon release, rather than moving a floating tag.

The `@production` tag is moved to the latest version of the `main` branch when changes need to be promoted.

The process:

1. Contributors (editing this repository is limited to the internal Tyk team) will create a Pull Request (PR) to `main`.
2. The `main` branch is protected and requires a Pull Request and review before merging.
3. When the PR is merged, changes are not yet used across all repositories; moving the tag is needed.
4. The contributor needs to ask on the Slack channel `#team-ext-non-functional` to move the `@production` tag.
5. Editing/moving this tag is limited to repository owners.
Loading