| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). |
| `name` | string | no | The release name. |
| `tag_name` | string | yes | The tag where the release will be created from. |
| `tag_name` | string | yes | The tag where the release is created from. |
| `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). |
| `ref` | string | yes, if `tag_name` doesn't exist | If a tag specified in `tag_name` doesn't exist, the release will be created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name. |
| `ref` | string | yes, if `tag_name` doesn't exist | If a tag specified in `tag_name` doesn't exist, the release is created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name. |
| `milestones` | array of string | no | The title of each milestone the release is associated with. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. |
| `assets:links` | array of hash | no | An array of assets links. |
| `assets:links:name`| string | required by: `assets:links` | The name of the link. Link names must be unique within the release. |
| `assets:links:url` | string | required by: `assets:links` | The URL of the link. Link URLs must be unique within the release. |
| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md#permanent-links-to-release-assets).
| `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`.
| `released_at` | datetime | no | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `released_at` | datetime | no | The date when the release is/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
Example request:
...
...
@@ -493,7 +493,7 @@ Example response:
Group milestones associated with the project may be specified in the `milestones`
array for [Create a release](#create-a-release) and [Update a release](#update-a-release)
API calls. Only milestones associated with the project's group may be specified, and
adding milestones for ancestor groups will raise an error.
adding milestones for ancestor groups raises an error.
## Collect release evidence **(PREMIUM ONLY)**
...
...
@@ -537,7 +537,7 @@ PUT /projects/:id/releases/:tag_name
| `name` | string | no | The release name. |
| `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). |
| `milestones` | array of string | no | The title of each milestone to associate with the release. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. To remove all milestones from the release, specify `[]`. |
| `released_at` | datetime | no | The date when the release will be/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `released_at` | datetime | no | The date when the release is/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
Example request:
...
...
@@ -631,7 +631,7 @@ Example response:
## Delete a Release
Delete a Release. Deleting a Release will not delete the associated tag.
Delete a Release. Deleting a Release doesn't delete the associated tag.
```plaintext
DELETE /projects/:id/releases/:tag_name
...
...
@@ -717,6 +717,6 @@ Example response:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1.
A release with a `released_at` attribute set to a future date will be labeled an **Upcoming Release** in the UI:
A release with a `released_at` attribute set to a future date is labeled an **Upcoming Release** in the UI:
The [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) might not work well with this configuration, and will need to be disabled.
The [Skip outdated deployment jobs](../pipelines/settings.md#skip-outdated-deployment-jobs) might
not work well with this configuration, and must be disabled.
There is a [plan to introduce a new annotation for environments](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) to address this issue.
@@ -19,14 +19,14 @@ To learn more, read [Using external secrets in CI](../../secrets/index.md).
This tutorial assumes you are familiar with GitLab CI/CD and Vault.
To follow along, you will need:
To follow along, you must have:
- An account on GitLab.
- A running Vault server and access to it is required to configure authentication and create roles
and policies. For HashiCorp Vaults, this can be the Open Source or Enterprise version.
NOTE:
You will need to replace the `vault.example.com` URL below with the URL of your Vault server and `gitlab.example.com` with the URL of your GitLab instance.
You must replace the `vault.example.com` URL below with the URL of your Vault server, and `gitlab.example.com` with the URL of your GitLab instance.
## How it works
...
...
@@ -57,7 +57,7 @@ The JWT's payload looks like this:
}
```
The JWT is encoded by using RS256 and signed with a dedicated private key. The expire time for the token will be set to job's timeout, if specified, or 5 minutes if it is not. The key used to sign this token may change without any notice. In such case retrying the job will generate new JWT using the current signing key.
The JWT is encoded by using RS256 and signed with a dedicated private key. The expire time for the token is set to job's timeout, if specified, or 5 minutes if it is not. The key used to sign this token may change without any notice. In such case retrying the job generates new JWT using the current signing key.
You can use this JWT and your instance's JWKS endpoint (`https://gitlab.example.com/-/jwks`) to authenticate with a Vault server that is configured to allow the JWT Authentication method for authentication.
...
...
@@ -111,7 +111,7 @@ EOF
Success! Uploaded policy: myproject-production
```
You'll also need roles that will link the JWT with these policies.
You also need roles that link the JWT with these policies.
This example uses [bound_claims](https://www.vaultproject.io/api/auth/jwt#bound_claims) to specify that only a JWT with matching values for the specified claims will be allowed to authenticate.
This example uses [bound_claims](https://www.vaultproject.io/api/auth/jwt#bound_claims) to specify that only a JWT with matching values for the specified claims is allowed to authenticate.
Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets.
...
...
@@ -159,7 +159,7 @@ Combined with [protected branches](../../../user/project/protected_branches.md),
[user_claim](https://www.vaultproject.io/api/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login.
[bound_claims_type](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values will be interpreted as globs, with `*` matching any number of characters.
[bound_claims_type](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values are interpreted as globs, with `*` matching any number of characters.
For the full list of options, see Vault's [Create Role documentation](https://www.vaultproject.io/api/auth/jwt#create-role).
For the full list of available configuration options, see Vault's [API documentation](https://www.vaultproject.io/api/auth/jwt#configure).
The following job, when run for the `master` branch, will be able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
The following job, when run for the `master` branch, is able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`:
This article demonstrates how to use the [Continuous Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-deployment)
method to deploy a [Spring Boot](https://projects.spring.io/spring-boot/) application to
This guide covers the building of dependencies of a PHP project while compiling assets via an NPM script using [GitLab CI/CD](../../README.md).
While it is possible to create your own image with custom PHP and Node.js versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and Node.js installed.
While it is possible to create your own image with custom PHP and Node.js versions, for brevity we use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and Node.js installed.
```yaml
image:tetraweb/php
```
The next step is to install zip/unzip packages and make composer available. We will place these in the `before_script` section:
The next step is to install zip/unzip packages and make composer available. We place these in the `before_script` section:
```yaml
before_script:
...
...
@@ -26,7 +26,7 @@ before_script:
-php -r "unlink('composer-setup.php');"
```
This will make sure we have all requirements ready. Next, we want to run `composer install` to fetch all PHP dependencies and `npm install` to load Node.js packages, then run the `npm` script. We need to append them into `before_script` section:
This makes sure we have all requirements ready. Next, run `composer install` to fetch all PHP dependencies and `npm install` to load Node.js packages. Then run the `npm` script. We need to append them into `before_script` section:
```yaml
before_script:
...
...
@@ -43,19 +43,19 @@ In this particular case, the `npm deploy` script is a Gulp script that does the
1. Copy various assets (images, fonts) around
1. Replace some strings
All these operations will put all files into a `build` folder, which is ready to be deployed to a live server.
All these operations put all files into a `build` folder, which is ready to be deployed to a live server.
## How to transfer files to a live server
You have multiple options: rsync, SCP, SFTP, and so on. For now, we will use SCP.
You have multiple options: rsync, SCP, SFTP, and so on. For now, use SCP.
To make this work, you need to add a GitLab CI/CD Variable (accessible on `gitlab.example/your-project-name/variables`). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** SSH key of your server.
To make this work, you must add a GitLab CI/CD Variable (accessible on `gitlab.example/your-project-name/variables`). Name this variable `STAGING_PRIVATE_KEY` and set it to the**private** SSH key of your server.
### Security tip
Create a user that has access **only** to the folder that needs to be updated.
After you create that variable, you need to make sure that key will be added to the Docker container on run:
After you create that variable, make sure that key is added to the Docker container on run:
```yaml
before_script:
...
...
@@ -71,7 +71,7 @@ In order, this means that:
1. We check if the `ssh-agent` is available and we install it if it's not.
1. We create the `~/.ssh` folder.
1. We make sure we're running bash.
1. We disable host checking (we don't ask for user accept when we first connect to a server and since every job will equal a first connect, we kind of need this).
1. We disable host checking (we don't ask for user accept when we first connect to a server, and since every job equals a first connect, we need this).
And this is basically all you need in the `before_script` section.
...
...
@@ -96,14 +96,14 @@ stage_deploy:
Here's the breakdown:
1.`only:dev` means that this build will run only when something is pushed to the `dev` branch. You can remove this block completely and have everything be ran on every push (but probably this is something you don't want)
1.`ssh-add ...` we will add that private key you added on the web UI to the Docker container
1. We will connect via `ssh` and create a new `_tmp` folder
1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder
1. We will connect again via `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
1. We connect to SSH and remove the `_old` folder
1.`only:dev` means that this build runs only when something is pushed to the `dev` branch. You can remove this block completely and have everything run on every push (but probably this is something you don't want).
1.`ssh-add ...` we add that private key you added on the web UI to the Docker container.
1. We connect via `ssh` and create a new `_tmp` folder.
1. We connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder.
1. We connect again via `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
1. We connect to SSH and remove the `_old` folder.
What's the deal with the artifacts? We just tell GitLab CI/CD to keep the `build` directory (later on, you can download that as needed).
What's the deal with the artifacts? We tell GitLab CI/CD to keep the `build` directory (later on, you can download that as needed).
### Why we do it this way
...
...
@@ -114,7 +114,7 @@ If you're using this only for stage server, you could do this in two steps:
The problem is that there will be a small period of time when you won't have the app on your server.
The problem is that there's a small period of time when you don't have the app on your server.
Therefore, for a production environment we use additional steps to ensure that at any given time, a functional app is in place.
...
...
@@ -122,13 +122,13 @@ Therefore, for a production environment we use additional steps to ensure that a
Since this was a WordPress project, I gave real life code snippets. Some further ideas you can pursue:
- Having a slightly different script for `master` branch will allow you to deploy to a production server from that branch and to a stage server from any other branches.
- Having a slightly different script for `master` branch allows you to deploy to a production server from that branch and to a stage server from any other branches.
- Instead of pushing it live, you can push it to WordPress official repository (with creating a SVN commit, etc.).
- You could generate i18n text domains on the fly.
-`data-mr-url` is the URL of the GitLab instance and will be the same for all
-`data-mr-url` is the URL of the GitLab instance and is the same for all
review apps.
-`data-project-path` is the project's path, which can be found by `CI_PROJECT_PATH`.
-`data-require-auth` is optional for public projects but required for [private and internal ones](#authentication-for-visual-reviews). If this is set to `true`, the user will be required to enter their [personal access token](../../user/profile/personal_access_tokens.md) instead of their name and email.
-`data-require-auth` is optional for public projects but required for [private and internal ones](#authentication-for-visual-reviews). If this is set to `true`, the user is required to enter their [personal access token](../../user/profile/personal_access_tokens.md) instead of their name and email.
-`id` is always `review-app-toolbar-script`, you don't need to change that.
-`src` is the source of the review toolbar script, which resides in the
respective GitLab instance and will be the same for all review apps.
respective GitLab instance and is the same for all review apps.
For example, in a Ruby application with code hosted on in a project GitLab.com, you would need to have this script:
It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens.
Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers.
In this document, we'll explain how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature.
This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature.
The following assumes you already have Vault installed and running.
1.**Get the OpenID Connect client ID and secret from GitLab:**
First you'll need to create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps:
First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. To do this, sign in to GitLab and follow these steps:
1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**.
1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris),
...
...
@@ -71,7 +71,7 @@ The following assumes you already have Vault installed and running.
Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab:
This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we'll show how you can access this role through the Vault CLI.
This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI.
```shell
vault write auth/oidc/role/demo \
...
...
@@ -88,11 +88,11 @@ The following assumes you already have Vault installed and running.
1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)).
1. If the `OIDC` method is not currently selected, open the dropdown and select it.
1. Click the **Sign in With GitLab** button, which will open a modal window:
1. Click the **Sign in With GitLab** button, which opens a modal window:
1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This will redirect you back to your Vault UI as a signed-in user.
1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user.
...
...
@@ -116,12 +116,12 @@ The following assumes you already have Vault installed and running.
another port number that matches the port given to GitLab when listing
The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board.
The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board.
NOTE:
The YAML file is static. If you apply it using `kubectl apply`, you must
Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step.
After you add a new domain to Pages, the verification code prompts you. Copy the values from GitLab
and paste them in your domain's control panel as a TXT record on the next step.
...
...
@@ -91,7 +92,7 @@ add a DNS apex `CNAME` record instead of an `A` record. The main
advantage of doing so is that when GitLab Pages IP on GitLab.com
changes for whatever reason, you don't need to update your `A` record.
There may be a few exceptions, but **this method is not recommended**
as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain.
as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain.
##### For subdomains
...
...
@@ -154,12 +155,11 @@ Once you have added all the DNS records:
As soon as your domain becomes active, your website will be available
through your domain name.
As soon as your domain becomes active, your website is available through your domain name.
WARNING:
Considering GitLab instances with domain verification enabled,
if the domain cannot be verified for 7 days, it will be removed
if the domain can't be verified for 7 days, it's removed
from the GitLab project.
> **Notes:**
...
...
@@ -169,9 +169,9 @@ from the GitLab project.
to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification).
> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/),
although it's usually a matter of minutes to complete. Until it does, verification
will fail and attempts to visit your domain will respond with a 404.
fails, and attempts to visit your domain result in a 404.
> - Once your domain has been verified, leave the verification record
in place: your domain will be periodically reverified, and may be
in place. Your domain is periodically reverified, and may be
disabled if the record is removed.
##### Troubleshooting Pages domain verification
...
...
@@ -211,7 +211,7 @@ For a subdomain:
You can add more than one alias (custom domains and subdomains) to the same project.
An alias can be understood as having many doors leading to the same room.
All the aliases you've set to your site will be listed on **Setting > Pages**.
All the aliases you've set to your site are listed on **Setting > Pages**.
From that page, you can view, add, and remove them.
### Redirecting `www.domain.com` to `domain.com` with Cloudflare
@@ -81,10 +81,12 @@ becomes available automatically.
To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md)
to build your site and publish it to the GitLab Pages server. The sequence of
scripts that GitLab CI/CD runs to accomplish this task is created from a file named
`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website.
`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md).
A specific `job` called `pages` in the configuration file makes GitLab aware that you're deploying a
GitLab Pages website.
You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names),
`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll
`*.gitlab.io`, or your own domain (`example.com`). In that case, you
need administrator access to your domain's registrar (or control panel) to set it up with Pages.
The following diagrams show the workflows you might follow to get started with Pages.
...
...
@@ -94,15 +96,15 @@ The following diagrams show the workflows you might follow to get started with P
## Access to your Pages site
If you're using GitLab Pages default domain (`.gitlab.io`),
your website will be automatically secure and available under
your website is automatically secure and available under
HTTPS. If you're using your own custom domain, you can
optionally secure it with SSL/TLS certificates.
If you're using GitLab.com, your website will be publicly available to the internet.
If you're using GitLab.com, your website is publicly available to the internet.
To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md).
If you're using a self-managed instance (Core, Starter, Premium, or Ultimate),
your websites will be published on your own server, according to the
your websites are published on your own server, according to the
[Pages settings](../../../administration/pages/index.md) chosen by your sysadmin,
@@ -28,20 +28,20 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v
with GitLab Pages, depending on your project's visibility:
- If your project is private:
-**Only project members**: Only project members will be able to browse the website.
-**Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
-**Only project members**: Only project members are able to browse the website.
-**Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership.
- If your project is internal:
-**Only project members**: Only project members will be able to browse the website.
-**Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership.
-**Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
-**Only project members**: Only project members are able to browse the website.
-**Everyone with access**: Everyone logged into GitLab is able to browse the website, no matter their project membership.
-**Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership.
- If your project is public:
-**Only project members**: Only project members will be able to browse the website.
-**Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership.
-**Only project members**: Only project members are able to browse the website.
-**Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership.
1. Click **Save changes**.
The next time someone tries to access your website and the access control is
enabled, they will be presented with a page to sign into GitLab and verify they
enabled, they're presented with a page to sign into GitLab and verify they
