Update README.md
Diff
README.md | 58 +++++++++++++++++++++-------------------------------------
1 file changed, 21 insertions(+), 37 deletions(-)
@@ -1,28 +1,15 @@
# gitlab-cargo-shim
To use `github-cargo-shim` at the moment you will have to build Cargo with
[this patch][patch] ([MR][MR]).
Say goodbye to your Git dependencies, `gitlab-cargo-shim` is an SSH server
that serves crates just like a standard Cargo registry but from a
[GitLab package registry][gitlab-package-registry], allowing you to use
your private dependencies like any other dependency. No more `git push --force`s
breaking your builds & proper versioning in one simple little binary.
Access controls work just like they do in GitLab, builds are scoped to
users - if they don't have permission to the dependency they can't build
it, it's that simple.
Users are identified by their SSH keys when connecting to the server and
will be authenticated to the GitLab API via an [impersonation token][imp-token],
builds will insert their token as a username to the SSH server and the
shim will use that to call the GitLab API.
To publish simply run `cargo package` and push the resulting `.crate` file
to the GitLab package repository with a semver-compatible version string, to
consume the package simply configure your `.cargo/config.toml` and `Cargo.toml`
accordingly.
[Example configuration][example-configuration]
Say goodbye to your Git dependencies, `gitlab-cargo-shim` is a stateless SSH server that serves crates like a standard Cargo registry but from a [GitLab package registry][gitlab-package-registry], allowing you to use your private dependencies like any other dependency. No more `git push --force`s breaking your builds & get proper versioning in one simple little binary.
Access controls work like they do in GitLab, builds are scoped to users - if they don't have permission to the dependency they can't build it, it's that simple.
Users are identified by their SSH keys from GitLab when connecting to the server and an [impersonation token][imp-token] will be generated for that run in order to pull available versions. Builds will insert their token as a username to the SSH server and the shim will use that to call the GitLab API.
To publish run `cargo package` and push the resulting `.crate` file to the GitLab package repository with a semver-compatible version string, to consume the package configure your `.cargo/config.toml` and `Cargo.toml` accordingly.
```toml
# .cargo/config.toml
[registries]
@@ -33,8 +20,7 @@
my-crate = { version = "0.1", registry = "my-gitlab-project" }
```
In your CI build, setup a `before_script` step to replace the connection string
with one containing the CI token:
In your CI build, setup a `before_script` step to replace the connection string with one containing the CI token:
```yaml
# .gitlab-ci.yml
@@ -47,27 +33,25 @@
To release your package from CI, add a new pipeline step:
```yaml
stage:
- release-crate
release-crate:
stage: release-crate
image: rust:1.62
stage: deploy
only: # release when a tag is pushed
- tags
before_script:
- cargo install cargo-get
- export CRATE_NAME=$(cargo get name) CRATE_VERSION=$(cargo get version)
- export CRATE_FILE=$(CRATE_NAME)-$(CRATE_FILE).crate
- export CRATE_NAME=$(cargo get --name) CRATE_VERSION=$(cargo get version)
- export CRATE_FILE=${CRATE_NAME}-${CRATE_VERSION}.crate
script:
- cargo package
- cargo metadata > metadata.json
- curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file target/package/${CRATE_FILE} "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${NAME}/${VERSION}/${CRATE_FILE}"
- curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file metadata.json "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${NAME}/${VERSION}/metadata.json"
- cargo metadata --format-version 1 > metadata.json
- 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file target/package/${CRATE_FILE} "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${CRATE_NAME}/${CRATE_VERSION}/${CRATE_FILE}"'
- 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file metadata.json "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${CRATE_NAME}/${CRATE_VERSION}/metadata.json"'
```
It's that easy. Go forth and enjoy your newfound quality of life improvements,
Rustacean.
It's that easy. Go forth and enjoy your newfound quality of life improvements, Rustacean.
[gitlab-package-registry]: https://docs.gitlab.com/ee/user/packages/package_registry/index.html
[imp-token]: https://docs.gitlab.com/ee/api/index.html#impersonation-tokens
[envvar]: https://doc.rust-lang.org/cargo/reference/registries.html#using-an-alternate-registry
[patch]: https://github.com/rust-lang/cargo/pull/10484.patch
[MR]: https://github.com/rust-lang/cargo/pull/10484
[example-configuration]: https://github.com/w4/gitlab-cargo-shim/blob/main/config.toml