Skip to content

Commit 1b46093

Browse files
lelialelia
committed
Update docs to cover prebuilt image usage, v2 pinning strategies, release workflow
Signed-off-by: lelia <lelia@socket.dev>
1 parent 240f04f commit 1b46093

3 files changed

Lines changed: 276 additions & 30 deletions

File tree

‎action.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ author: "Socket"
44

55
runs:
66
using: "docker"
7+
# TODO (v2.0.0 release): switch to pre-built GHCR image for faster action startup.
8+
# Follow the "Release workflow" in docs/github-action.md: publish image first,
9+
# then update this line to docker://ghcr.io/socketdev/socket-basics:2.0.0,
10+
# then create the git tag v2.0.0.
711
image: "Dockerfile"
812
env:
913
# Core GitHub variables (these are automatically available, but we explicitly pass GITHUB_TOKEN)

‎docs/github-action.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Complete guide to integrating Socket Basics into your GitHub Actions workflows f
55
## Table of Contents
66

77
- [Quick Start](#quick-start)
8+
- [Performance and Caching](#performance-and-caching)
89
- [Basic Configuration](#basic-configuration)
910
- [Enterprise Features](#enterprise-features)
1011
- [Advanced Workflows](#advanced-workflows)
@@ -52,6 +53,154 @@ jobs:
5253
5354
With just your `SOCKET_SECURITY_API_KEY`, all scanning configurations are managed through the [Socket Dashboard](https://socket.dev/dashboard) — no workflow changes needed.
5455

56+
## Performance and Caching
57+
58+
### How the action is currently built
59+
60+
When you reference `uses: SocketDev/socket-basics@1.1.3`, GitHub Actions builds the
61+
`Dockerfile` from source at the start of every workflow run. As of `1.1.3` the
62+
Dockerfile uses a **multi-stage build** with BuildKit cache mounts, which provides
63+
two categories of improvement:
64+
65+
| Improvement | Benefit |
66+
|-------------|---------|
67+
| Multi-stage stages (`trivy`, `trufflehog`, etc.) | GitHub's runner cache can reuse unchanged tool layers across runs |
68+
| `python:3.12-slim` base | ~850 MB smaller final image → faster layer pulls on cold runners |
69+
| `--mount=type=cache` for apt / uv / npm | Faster repeated builds locally and on self-hosted runners with a persistent cache |
70+
71+
**On standard GitHub-hosted runners** (ephemeral, no persistent Docker cache between
72+
jobs), the multi-stage improvement is most visible when the same runner picks up a
73+
cached layer — typically within a workflow run or when GitHub's runner image itself
74+
includes the base layers. Cold runs still download and run all tool-install steps.
75+
76+
### Pre-built image (active as of 1.1.3)
77+
78+
The action now references a pre-built GHCR image instead of building from source:
79+
80+
```yaml
81+
# action.yml
82+
runs:
83+
using: docker
84+
image: docker://ghcr.io/socketdev/socket-basics:1.1.3
85+
```
86+
87+
Users who pin to a specific version tag (e.g. `@1.1.3`) will see the action start
88+
in seconds rather than minutes — the image is pre-built, integration-tested, and
89+
published to GHCR before the release tag is ever created.
90+
91+
> **Note for `1.1.3` specifically:** the first time you use this version after this
92+
> change, the `publish-docker.yml` workflow must have run at least once (via
93+
> `workflow_dispatch` with tag `1.1.3`) to populate the GHCR image. Future releases
94+
> follow the publish-first process described in the release workflow below.
95+
96+
### Release workflow (publish → tag, never tag → publish)
97+
98+
To avoid the race condition where a git tag references an image that doesn't exist
99+
yet, follow this order for every release:
100+
101+
```
102+
1. Merge release PR to main (version bump + action.yml version update)
103+
2. workflow_dispatch → publish-docker.yml (builds, tests, pushes images to GHCR/DockerHub)
104+
3. Create git tag (e.g. 1.1.4) — image already exists, zero race condition
105+
```
106+
107+
When users then run `uses: SocketDev/socket-basics@1.1.4`, GitHub reads `action.yml`
108+
at that tag, pulls `ghcr.io/socketdev/socket-basics:1.1.4`, and starts scanning
109+
immediately.
110+
111+
### If you're running socket-basics outside of the GitHub Action
112+
113+
If you run socket-basics in other CI systems (Jenkins, GitLab, CircleCI, etc.) or
114+
as a standalone `docker run`, pull the pre-built image directly:
115+
116+
```bash
117+
docker pull ghcr.io/socketdev/socket-basics:1.1.3
118+
```
119+
120+
See [Local Docker Installation](local-install-docker.md) for usage examples.
121+
122+
### Pinning strategies
123+
124+
Starting with v2, socket-basics follows the [GitHub-recommended tag convention](https://docs.github.com/en/actions/sharing-automations/creating-actions/releasing-and-maintaining-actions):
125+
exact tags (`v2.0.0`), minor tags (`v2.0`), and a floating major tag (`v2`).
126+
Each strategy offers a different tradeoff between safety and convenience.
127+
128+
---
129+
130+
**Strategy 1 — Floating major tag: `@v2`**
131+
132+
Always runs the latest v2.x.y release. Zero maintenance overhead; you get every
133+
fix and improvement automatically.
134+
135+
```yaml
136+
- uses: SocketDev/socket-basics@v2
137+
with:
138+
socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
139+
```
140+
141+
**Best for:** teams that trust the project's stability guarantees and want no
142+
upgrade friction. **Risk:** a buggy patch release will affect you immediately
143+
with no review gate.
144+
145+
---
146+
147+
**Strategy 2 — Exact version pin: `@v2.0.0`** *(recommended)*
148+
149+
Pins to a specific immutable release. You control exactly when you upgrade.
150+
Pair with Dependabot to automate the bump PR while keeping a review gate:
151+
152+
```yaml
153+
- uses: SocketDev/socket-basics@v2.0.0
154+
with:
155+
socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
156+
```
157+
158+
Add to your repo's `.github/dependabot.yml`:
159+
160+
```yaml
161+
version: 2
162+
updates:
163+
- package-ecosystem: "github-actions"
164+
directory: "/"
165+
schedule:
166+
interval: "weekly"
167+
```
168+
169+
Dependabot opens a PR for each new release. You review, approve, and merge on
170+
your own schedule — automated upgrades with a human gate. **Best for:** most
171+
production use cases.
172+
173+
---
174+
175+
**Strategy 3 — Commit SHA pin: `@<sha>`**
176+
177+
Maximum supply-chain safety. Pins to an exact commit; even a force-pushed tag
178+
cannot change what you run. Use `@v2.0.0` to find the SHA, then pin it:
179+
180+
```yaml
181+
# Get the SHA: git rev-list -n 1 v2.0.0
182+
- uses: SocketDev/socket-basics@<sha> # v2.0.0
183+
with:
184+
socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
185+
```
186+
187+
Dependabot also manages SHA pins — it will open PRs to update the SHA when
188+
a new version is released, keeping the version comment in sync.
189+
190+
**Best for:** high-compliance environments or repos that already SHA-pin all
191+
actions. Slightly more friction to set up but the highest guarantee of
192+
reproducibility.
193+
194+
---
195+
196+
**Comparison**
197+
198+
| Strategy | Effort | Auto-updates | Review gate | Supply-chain safety |
199+
|---|---|---|---|---|
200+
| `@v2` | None | Yes (instant) | No | Low |
201+
| `@v2.0.0` + Dependabot | Low | Yes (weekly PR) | Yes | Medium |
202+
| `@<sha>` + Dependabot | Low | Yes (weekly PR) | Yes | High |
203+
55204
## Basic Configuration
56205

57206
### Required Permissions

0 commit comments

Comments
 (0)