tag-publish 0.0.0__tar.gz

tag_publish-0.0.0/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2020-2026, Camptocamp SA
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tag_publish-0.0.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: tag-publish
+Version: 0.0.0
+Summary: Tools used to publish Python packages, Docker images and Helm charts for GitHub tag and branch
+License: FreeBSD
+License-File: LICENSE
+Keywords: ci
+Author: Camptocamp
+Author-email: info@camptocamp.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: PyYAML (>=6,<7)
+Requires-Dist: applications-download (>=1,<2)
+Requires-Dist: debian-inspector (>=31,<32)
+Requires-Dist: githubkit (>=0,<1)
+Requires-Dist: id (>=1,<2)
+Requires-Dist: jsonschema-validator-new (>=0,<1)
+Requires-Dist: multi-repo-automation (>=1,<2)
+Requires-Dist: requests (>=2,<3)
+Requires-Dist: security-md (>=1,<2)
+Requires-Dist: twine (>=6,<7)
+Project-URL: Bug Tracker, https://github.com/camptocamp/tag-publish/issues
+Project-URL: Repository, https://github.com/camptocamp/tag-publish
+Description-Content-Type: text/markdown
+
+# Tag Publish
+
+## Publishing
+
+The main goals of Tag Publish offer the commands to publish the project,
+Using a tag, a stabilization branch, a feature branch or a pull request.
+
+When possible it can do a secret-less publishing (privileged in defaults), if it's not possible the login should be done before the publishing.
+
+See the [documentation](https://github.com/camptocamp/c2cciutils/wiki/Publishing).
+
+## Startup
+
+Set the permissions:
+
+```yaml
+permissions:
+  # To publish Docker images on GHCR, npm packages and Helm charts on OCI registry
+  packages: write
+  # To publish Python packages using OIDC and for cosign keyless signing
+  id-token: write
+  # To publish Helm charts (chart-releaser) and send repository dispatch notifications
+  contents: write
+```
+
+Install the package in the worklow:
+
+```yaml
+- name: Install tag-publish
+  run: pip install tag-publish
+```
+
+Do the publishing:
+
+```yaml
+- name: Publish
+  run: tag-publish
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## New version
+
+To create a new version you should create a Git tag with the version number.
+
+## New stabilization branch
+
+To create a new minor version you just should run `tag-publish-new --version=<version>`.
+
+This will create the stabilization branch and will create a new pull request to update
+the `SECURITY.md` file and the Renovate configuration.
+
+This will also create the tags for the backport.
+
+You are welcome to run `tag-publish-new --help` to see what's it's done.
+
+Note that it didn't create a tag, you should do it manually.
+
+To create a patch version you should just create tag.
+
+## Kind of publishing
+
+This tool can publish on different kind of versions:
+
+- `tag`: Related to a Git tag.
+- `default_branch`: Related to the default branch.
+- `stabilization_branch`: Related to a stabilization branch (including the default branch).
+- `feature_branch`: Related to a feature branch or a pull request.
+
+We can also publish on different kind of versions like `rebuild` by using the `--type` argument.
+
+## SECURITY.md
+
+The `SECURITY.md` file should contain the security policy of the repository, especially the end of
+support dates.
+
+For compatibility with [`security.md`](https://github.com/sbrunner/security.md/) it should contain an array
+with at least the columns `Version` and `Supported Until`. The `Version` column will contain the concerned
+version.
+The `Supported Until` will contain the date of end of support `dd/mm/yyyy`.
+It can also contain the following sentences:
+
+- `Unsupported`: no longer supported => no audit, no rebuild.
+- `Best effort`: the support is ended, it is still rebuilt and audited, but this can be stopped without any notice.
+- `To be defined`: not yet released or the date will be set related of another project release date (like for GeoMapFish).
+
+See also [GitHub Documentation](https://docs.github.com/en/github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository)
+
+## Configuration
+
+The configuration file is `.github/publish.yaml`, the schema is `https://raw.githubusercontent.com/camptocamp/tag-publish/<version>/tag_publish/schema.json`.
+
+### Dry run
+
+Dry run publish: `GITHUB_REF=... tag-publish --dry-run ...`
+
+### Python package to pypi repository
+
+Minimum configuration:
+
+```yaml
+pypi:
+  packages:
+    - {}
+```
+
+If the file `~/.pypirc` didn't exists we will do a login using OpenId Connect (OIDC), see:
+https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi.
+
+By default the package will be published only on tag, if you want to publish on stabilization branch you should add
+a `versions` key with the list of versions you want to publish, that can be:
+`rebuild` (specified with --type), `tag`, `default_branch`, `stabilization_branch`, `feature_branch`, `pull_request` (for pull request merge: number)
+
+It we have a `setup.py` file, we will be in legacy mode:
+When publishing, the version computed from arguments or `GITHUB_REF` is put in environment variable `VERSION`, thus you should use it in `setup.py`, example:
+
+```python
+VERSION = os.environ.get("VERSION", "1.0.0")
+```
+
+Also we consider that we use `poetry` with [poetry-dynamic-versioning](https://pypi.org/project/poetry-dynamic-versioning/) to manage the version, and [poetry-plugin-tweak-dependencies-version](https://pypi.org/project/poetry-plugin-tweak-dependencies-version/) to manage the dependencies versions.
+
+Example of configuration:
+
+```toml
+[tool.poetry-dynamic-versioning]
+enable = true
+vcs = "git"
+pattern = "^(?P<base>\\d+(\\.\\d+)*)"
+format-jinja = """
+{%- if env.get("VERSION_TYPE") == "default_branch" -%}
+{{serialize_pep440(bump_version(base, 1), dev=distance)}}
+{%- elif env.get("VERSION_TYPE") == "stabilization_branch" -%}
+{{serialize_pep440(bump_version(base, 2), dev=distance)}}
+{%- elif distance == 0 -%}
+{{serialize_pep440(base)}}
+{%- else -%}
+{{serialize_pep440(bump_version(base), dev=distance)}}
+{%- endif -%}
+"""
+
+```
+
+Note that we can access to the environment variables `VERSION`,`VERSION_TYPE`.
+
+Then by default:
+
+- Tag with `1.2.3` => release `1.2.3`
+- Commit on feature branch just do a validation
+- Commit on `master` branch after the tag 1.3.0 => release `1.4.0.dev1`
+- Commit on `1.3` branch after the tag 1.3.0 => release `1.3.1.dev1`
+
+#### Authentication
+
+If the file `~/.pypirc` exists we consider that we ar already logged in also
+we will do the login with the `pypi` server with OpenID Connect (OIDC).
+
+The OIDC login is recommended because it didn't needs any additional secrets,
+but it need some configuration on pypi in the package,
+see the [GitHub Documentation](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi#adding-the-identity-provider-to-pypi).
+
+The required permissions is `id-token: write`.
+
+#### Integration if the package directly in a Docker image
+
+To make it working in the `Dockerfile` you should have in the `poetry` stage:
+
+```Dockerfile
+ENV POETRY_DYNAMIC_VERSIONING_BYPASS=dev
+RUN poetry export --extras=checks --extras=publish --output=requirements.txt \
+    && poetry export --with=dev --output=requirements-dev.txt
+```
+
+And in the `run` stage
+
+```Dockerfile
+ARG VERSION=dev
+RUN --mount=type=cache,target=/root/.cache \
+    POETRY_DYNAMIC_VERSIONING_BYPASS=${VERSION} python3 -m pip install --disable-pip-version-check --no-deps --editable=.
+```
+
+And in the `Makefile`:
+
+```Makefile
+VERSION = $(strip $(shell poetry version --short))
+
+.PHONY: build
+build: ## Build the Docker images
+    docker build --build-arg=VERSION=$(VERSION) --tag=$(GITHUB_REPOSITORY) .
+```
+
+### Docker image to registry
+
+The minimal config is like this:
+
+```yaml
+docker:
+  images:
+    - name: camptocamp/tag-publish
+```
+
+If you want to use the GitHub token to be logged in on ghcr you should set `auto_login` to `True`, the
+requires the permissions are `packages: write`.
+
+With that the image initially named `camptocamp/tag-publish:latest` will be published on GitHub GHCR and on Docker hub.
+
+The full config is like this:
+
+```yaml
+docker:
+  github_oidc_login: True
+  latest: True
+  images:
+    - # The base name of the image we want to publish
+      name:
+  repository:
+    <internal_name>:
+      # The fqdn name of the server if not Docker hub
+      server:
+      # List of kinds of versions you want to publish, that can be: rebuild (specified using --type),
+      # tag, stabilization_branch, feature_branch, pull_request (for pull request merge: number)
+      version:
+      # List of tags we want to publish interpreted with `format(version=version)`
+      # e.g. if you use `{version}-lite` when you publish the version `1.2.3` the source tag
+      # (that should be built by the application build) is `latest-lite`, and it will be published
+      # with the tag `1.2.3-lite`.
+      tags:
+      # If your images are published by different jobs you can separate them in different groups
+      # and publish them with `tag-publish --group=<group>`
+      group:
+```
+
+By default, the last line of the `SECURITY.md` file will be published (`docker`) with the tag
+`latest`. Set `latest` to `False` to disable it.
+
+#### Use Renovate to trigger a new build instead of the legacy rebuild
+
+If the `ci/dpkg-versions.yaml` or `.github/dpkg-versions.yaml` file is present, the package list will be updated on publishing.
+
+The versions will be updated by [GHCI](https://github.com/camptocamp/github-app-geo-project/) application.
+
+### Node package to npm repository
+
+Minimum configuration:
+
+```yaml
+node:
+  packages:
+    - {}
+```
+
+If the repository server is `npm.pkg.github.com` we will do a login using `GITHUB_TOKEN`.
+
+To publish on `npm.pkg.github.com` you requires the permissions are `packages: write`, and the `id-token: write` for the provenance.
+
+By default the package will be published only on tag.
+
+### HELM
+
+The minimal config is like this:
+
+```yaml
+helm:
+  packages:
+    - {}
+```
+
+This will publish the `helm` charts in the current folder using [chart releaser](https://github.com/helm/chart-releaser).
+
+The artifacts will be attached to a GitHub release, and the `index.yaml` file will be updated in the `gh-pages` branch.
+
+The required permission is `contents: write`.
+
+Create the required `gh-pages` branch:
+
+```bash
+git checkout --orphan gh-pages
+git reset --hard
+git commit --allow-empty -m "Initialize gh-pages branch"
+git push origin gh-pages
+```
+
+#### OCI registry publishing
+
+By default, the Helm chart is also published to an OCI registry (`ghcr.io/<owner>/<repo>`) and signed with [cosign](https://github.com/sigstore/cosign) using keyless signing.
+
+The chart is pushed to `ghcr.io/<owner>/<repo>:<version>` automatically.
+
+The required permissions are `packages: write` (for pushing to ghcr.io) and `id-token: write` (for cosign keyless signing).
+
+To customize the OCI publishing:
+
+```yaml
+helm:
+  packages:
+    - folder: charts/my-chart
+  oci:
+    enabled: true # default: true
+    registry: ghcr.io # default: ghcr.io
+    sign: true # default: true, keyless signing via cosign
+```
+
+To disable OCI publishing:
+
+```yaml
+helm:
+  packages:
+    - {}
+  oci:
+    enabled: false
+```
+
+## Dispatch
+
+The minimal config is like this:
+
+```yaml
+dispatch:
+  - {}
+```
+
+The required permission is `contents: write`.
+
+This will create a repository dispatch of type `published` on own repository with the `content` e.g.:
+
+```json
+{
+  "version": "1.2.3",
+  "version_type": "tag",
+  "repository": "camptocamp/tag-publish",
+  "items": [
+    {
+      "type": "docker",
+      "image": "camptocamp/tag-publish",
+      "repository": "ghcr.io",
+      "tag": "1.2.3"
+    },
+    {
+      "type": "pypi",
+      "path": "."
+    },
+    {
+      "type": "helm",
+      "path": "."
+    }
+  ]
+}
+```
+
+## Contributing
+
+Install the pre-commit hooks:
+
+```bash
+pip install pre-commit
+pre-commit install --allow-missing-config
+```
+