gh-actions-date-versioning

Defines date-based build versions in GitHub Actions using bash date stamps and GITHUB_OUTPUT, with optional suffixes for environment (e.g. -dev). Use when tagging artifacts, docker images, git deploy commits, or release metadata without CalVer from the repo.

---
name: gh-actions-date-versioning
description: >-
  Defines date-based build versions in GitHub Actions using bash date stamps and
  GITHUB_OUTPUT, with optional suffixes for environment (e.g. -dev). Use when
  tagging artifacts, docker images, git deploy commits, or release metadata
  without CalVer from the repo.
---

# GitHub Actions: date-based version strings

## Pattern

1. **Step** with **`id:`** (e.g. **`set_version`**) runs in **`bash`** (default on **`ubuntu-latest`**).
2. Build a string with **`date`** — common formats:
   - **`$(date +%Y%m%d-%H%M)`** → `20260414-1530`
   - **`$(date +%Y.%m.%d-%H%M)`** → `2026.04.14-1530` (often used for container tags; see **`gh-actions-aws-ecr-ecs`**)
3. Optionally append a **suffix** for **environment** or **channel** (e.g. **`-dev`**, **`-staging`**).
4. Write to **`GITHUB_OUTPUT`** so later steps read **`${{ steps.<id>.outputs.version }}`**.

```bash
ver="$(date +%Y%m%d-%H%M)-dev"
echo "version=$ver" >> $GITHUB_OUTPUT
```

Use **`$GITHUB_OUTPUT`** (not deprecated **`::set-output`**).

## Suffix rules

| Goal | Example `ver` |
|------|----------------|
| Plain date-time only | `20260414-1530` |
| Environment / channel | `20260414-1530-dev`, `20260414-1530-prod` |

Drive the suffix from a **job `env`**, **`vars`**, **`matrix`**, or **`github.ref_name`** so one step definition works across workflows.

## Consumers

Same job after the step:

- **`${{ steps.set_version.outputs.version }}`**
- Docker tags, **`dotnet pack`**, commit messages, artifact names, **`gh release`**, etc.

Other jobs need **`outputs:`** on the producing job and **`needs.<job>.outputs.*`**.

## Time zone

Runner **`date`** uses the VM default (often **UTC** on GitHub-hosted Linux). Set **`TZ`** in the step **`env`** for a specific zone.

## Windows runners

**`date`** syntax differs on **`windows-latest`**. Prefer **`shell: bash`** for this step, or PowerShell **`Get-Date -Format`**, still appending to **`GITHUB_OUTPUT`**.

## Examples

See [reference.md](reference.md).