Environments, deployments and releases

Forge keeps a record of every deployment your pipelines make. Administrators can protect an environment with an approval. Releases, packages and container images ship from the same place. This page is for developers who write deployment jobs and for project administrators who protect environments.

Forge runs the deployment job on your runner. It does not run your application.

Define an environment

Add an environment to a job in .gitlab-ci.yml. A review app uses a dynamic name and a stop job.

deploy_review:
  script: ./deploy.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review

stop_review:
  script: ./teardown.sh
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

Keyword	Rules
`url`	http or https, up to 512 characters, no credentials. May use `$CI_ENVIRONMENT_SLUG`, `$CI_ENVIRONMENT_NAME` and commit variables.
`deployment_tier`	Set explicitly, or inferred from the name
Dynamic name	Must start with a static segment, so a branch name can never create `production`
`action`	`start` records a deployment. `prepare`, `verify`, `access` and `stop` run as ordinary jobs and record none.
`on_stop`	Names the stop job. The configuration is refused if that job is missing or stops another environment.
`auto_stop_in`	From one minute to one year, or `never`

Runners that support it set CI_ENVIRONMENT_NAME, CI_ENVIRONMENT_SLUG, CI_ENVIRONMENT_ACTION, CI_ENVIRONMENT_URL and CI_ENVIRONMENT_TIER in the job.

History, stop and roll back

Each environment card shows its state (Available, Stopping or Stopped), its tier, an Open link while it is available, and the auto-stop time. The history is immutable and records the commit, ref, execution and person of every deployment.

Stop. Members can stop an environment. For a protected environment only administrators can. Forge plays the waiting stop job, and without one the environment stops at once. A new successful deployment makes it available again.
Re-deploy and roll back. The history offers Re-deploy on the latest successful deployment and Roll back on earlier ones. Either runs that deployment’s job again in its own pipeline, with the same approval, secret and resource checks as a retry. Viewers can do neither, and a deployment that is still finishing is refused.

Protected environments

A protected environment has an exact, literal name. A deployment to it needs an approval and a separate start.

A current project administrator other than the person who created the pipeline approves.
A current administrator then starts the deployment. The approver may start it too.

The pipeline creator stays the person the job runs as and the owner of its secrets. Approval alone does not run anything, and the job still needs a runner and current permissions. The rule is fixed at one approver, and configurable approval counts and deploy-access roles are not available.

Serialize and freeze deployments

Resource groups. A job with a static resource_group key runs one at a time within that key. The order among waiting jobs is not guaranteed.
Deploy freezes. Project administrators define freeze periods as cron start and end times in an IANA time zone. Pipelines created during a freeze get CI_DEPLOY_FREEZE=true, so rules: [{if: $CI_DEPLOY_FREEZE, when: never}] holds a deployment back. The Releases & packages tab shows when a freeze is active.

Releases

A release names a tag and has a title, notes, up to 50 http or https links and the tag’s zip and tar.gz sources. Members create and edit releases, and administrators delete them. The tag stays.

Creating a release can create the tag from a ref, under the protected-tag rules.
Each release keeps evidence: a snapshot of the tag, the commits since the previous release and the work items they mention, with its SHA-256.
A future release date marks the release Upcoming.
The release: keyword takes tag_name, tag_message, name, description, ref, released_at and assets.links. When the job succeeds, Forge creates the release as the person the pipeline runs for.

Packages and container images

Both live in the Releases & packages tab.

Registry	How it works
Generic packages	`PUT` and `GET` on `/api/v1/forge/projects/:id/packages/generic/:name/:version/:file`. Files can be up to 32 MiB and are immutable once published. An optional `X-Checksum-Sha256` is checked on upload.
Container images	`docker login`, `push` and `pull`. Images are named `<project key>/<repository slug>[/<name>]`. Layers up to 32 MiB. Project administrators delete by digest.

Package uploads accept a member’s session, an api project access token or a running job’s CI_JOB_TOKEN, and downloads need read access. The registry takes a project access token as the password (read scopes pull, write scopes push) or a CI_JOB_TOKEN. The tab lists images and tags with their docker pull commands.

CI_JOB_TOKEN works only while the job runs and only for that project’s package registry, container registry and releases. Jobs have no network by default, so use a runner configured with a job network, see Runners.