<!-- https://doc.forgeit.fr/docs/administration/access-control/change-or-delete-a-role.md -->

# Change or delete a role

## 🔍 Open a role

1. In the left sidebar, click **Administration**, then, under **SECURITY**, **Access Control**.

2. In the list, click the line of the role.

The page shows the description, the identifier, and two tabs: **Members** and **Rights**.

## 👥 Add people to a role

1. Click the tab **Members**, then **Add**. The window **Add members** opens.

2. Click the field **Groups and people**, type a name, click the group or the person in the list.
   Repeat for each one.

3. Click **Add**.

The message **Members added to the role Acme readers.** appears and they are in the table. The
change applies at once.

## 🚪 Remove a person from a role

1. In the tab **Members**, on the line of the person, click the icon **Remove** (column
   **Actions**). The window **Remove this member?** opens.

2. Click **Remove**.

The message says the person is removed from the role. A role keeps at least one member: the icon of
the last one is greyed out.

## ✏️ Change the rights of a role

1. Click the tab **Rights**, then **Edit rights**.

2. Tick or untick the boxes. A box stands for all the permissions of the plugin for this action.
   A box with a dash inside is half ticked: the role holds only some of them.

3. Click **Save**, or **Cancel** to leave everything as it was. Nothing is written before you save.

The message **Rights saved.** appears.

The column **Advanced** lists what the boxes do not cover (other actions, refusals, rules under
conditions, tagged **Conditional rule**). It is shown as it is and does not change when you save.

## 🗑️ Delete a role

1. At the top right of the page of the role, click the icon **More actions**.

2. Click **Delete the role**. The window **Delete this role?** says the role and the rights it
   gives are removed, and that its members keep their other roles.

3. Click **Delete the role**.

The list opens and says **Role Acme readers deleted.**

:::note
A role that comes from the configuration file says **This role comes from the configuration file, it
cannot be changed here.** It has no button to add, edit or delete.
:::

✅ That's it!

Next: [Access Control FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/check-what-a-role-gives.md -->

# Check what a role gives

You created a role. Sign in as one of the people in it and see, screen by screen, what they can now
do.

## Before you start

A role with a group in it, for example `acme-builders` for the group `frontend-team`, with these
rights ([Create a role](create-a-role.md)):

| Plugin | Boxes to tick (tab **Rights**, **Edit rights**) |
| --- | --- |
| **orion-dashboard** | **Create**, **Update**, **Delete** |
| **scaffolder** | **Read**, **Create** |

## 🔍 Check it

1. Click your avatar, at the top right, then **Logout**.

2. Sign in with a person of the group, for example a member of `frontend-team`.

3. In the left sidebar, click **The Foundry**. Each template card now has a **Choose** button.

4. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want. **Add a card** and **Arrange** are active.

The new rights apply as soon as the person signs in.

## What each permission changes

| Permission | What the person can do |
| --- | --- |
| `scaffolder.task.create` | Click **Choose** on a template, and **Create** at the end of its form |
| `scaffolder.task.read` | Open the **Tasks** tab of The Foundry |
| `dashboard.update` | Click **Arrange**, or rename, reorder and delete the dashboards on **My Dashboards** |

## ➖ Take the rights away

1. As an administrator, delete the role: see [Change or delete a role](change-or-delete-a-role.md).

2. Sign in again as the same person. The **Choose** buttons are gone, and **Arrange** shows a padlock. Hover it: **Your role can't edit dashboards. Ask an administrator.** The cards already on the dashboard stay.

✅ That's it!

Next: [Access Control FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/create-a-role.md -->

# Create a role

A role says what a group of people may do in Astrolabe. You choose who holds it, then which actions
it gives on each plugin.

You do it as an administrator.

## 🔧 Create the role

1. In the left sidebar, click **Administration**.

2. Under **SECURITY**, click **Access Control**. The page **Access control** lists the roles.

3. Top right, click **Create a role**. The window **Create a role** opens.

4. Fill in the window:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | The name of the role. The line under it shows the identifier made from it, for example `Identifier: role:default/acme-readers`. | `Acme readers` |
   | **Description** | Optional: what the role is for | `Can read the catalog` |
   | **Members** | Click the field, type a name, click the group or the person in the list. Repeat for each one. At least one is required. | `Astrolabe administrators` |

5. Click **Create**.

The page of the new role opens, with the message **Role Acme readers created. Give it rights in the
Rights tab.**

## 🔑 Give it rights

1. On the page of the role, click the tab **Rights**. It says **This role gives no right.**

2. Click **Edit rights**.

3. On the line of a plugin, tick the actions to give: **Read**, **Create**, **Update**, **Delete**.
   A dash means the plugin has no such action.

4. Click **Save**. The message **Rights saved.** appears.

✅ That's it!

Next: [Change or delete a role](change-or-delete-a-role.md).

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/faq.md -->

# Access Control FAQ

## Which roles exist at first?

Three: `role:default/developer`, `role:default/astrolabe-administrator` and
`role:default/astrolabe-member`.

## Why can't I change a role?

A role tagged **File** comes from the configuration file of the instance: its page has no button
to add, edit or delete. To make a person an administrator, see [Give administrator rights to
someone](give-administrator-rights.md).

## Why is a button locked, with a padlock?

Your role does not allow it. Hover the button: the tooltip says which right is missing. Ask an
administrator to give it to you.

## Which plugins can a role act on?

The tab **Rights**, after **Edit rights**, shows one line per plugin: **catalog**, **scaffolder**,
**compass**, **orion-dashboard**, **announcements**, **administration**, **licensing**,
**cost-insights** and the others Astrolabe has.

## Which actions can I give?

**Read**, **Create**, **Update**, **Delete**, for each plugin. A box gives the action on all the
permissions of the plugin. What the boxes do not cover (other actions, refusals, rules under
conditions) shows in the column **Advanced** and does not change when you save.

## How do I see what a person can do?

Open each role: the tab **Members** lists its users and groups, the tab **Rights** what it gives. See
[See the roles and what they give](see-the-roles.md).

## How do I check that a role works?

Sign in with a person of the role and open the screens it should change: see
[Check what a role gives](check-what-a-role-gives.md).

## Do new rights apply at once?

They apply when the person signs in.

## What does a person with no administration right see?

The left sidebar shows **Search**, **My Dashboards**, **Catalog**, **Documentation**, **The Foundry**
and, when it is on, **Tech Atlas**. There is no **Administration**. The person reads the catalog,
the announcements, the Compass scores, the radar and their notifications, registers a component,
and watches components. The role `role:default/developer` gives no more.

## What if that person opens a link to Administration?

The page **Off the Charts** says **Your Astrolabe couldn't locate these coordinates**. The buttons
**Return to Home Port** and **Previous Coordinates** lead out.

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/give-administrator-rights.md -->

# Give administrator rights to someone

Being an administrator means being a member of the group **Astrolabe administrators**. You do it as
an administrator.

## ➕ Add a person

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **SECURITY**, click **Groups**.

3. On the row **astrolabe-administrators**, click the pencil (**Edit group
   astrolabe-administrators**). The window **Edit group** opens. It says **Members of this group
   are administrators of Astrolabe: they get the administrator role.**

4. Click the field **Members**, type the name of the person, for example `Marie Dupont`, and click
   the line `Marie Dupont (user:default/marie.dupont)`.

5. Click **Save**. The page says **Group updated.**

The person reloads the page: **Administration** appears in the left sidebar.

## ➖ Take a person out

1. On the row **astrolabe-administrators**, click the pencil.

2. In **Members**, click the cross on the chip of the person.

3. Click **Save**. The page says **Group updated.**

The person loses **Administration** when they reload the page.

## 🛟 The account `administrator`

The account `administrator` holds the administrator role on its own, whatever the group contains.

✅ That's it!

Next: [Create a role](create-a-role.md).

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/see-the-roles.md -->

# See the roles and what they give

You are an administrator. The page **Access control** shows every role on one screen: nothing is
changed from it.

## 🔍 Open the list

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **SECURITY**, click **Access Control**. The page **Access control** lists the roles.

Each line shows:

| Column | What it says |
| --- | --- |
| **Role** | The name of the role, and under it its identifier, for example `role:default/astrolabe-administrator` |
| **Members** | Who holds it, for example **2 groups + 1 person** |
| **Access** | The first plugins the role reaches, then **+8** for the others |
| **Origin** | **File** (with a padlock) for a role of the configuration file, **Editable** for a role made in Astrolabe |

3. To find a role, type its name in **Search a role**. The list **Origin** keeps **All**, **Editable**
   or **File** roles.

## 👥 See who holds a role

1. Click the line of the role, for example **Administrator**.

2. The tab **Members** lists the groups and the people of the role. **People in the group** says how
   many people a group holds.

## 🔑 See what a role gives

1. On the page of the role, click the tab **Rights**.

2. Read one line per plugin. A green tick under **Read**, **Create**, **Update** or **Delete** means the
   role gives it, a dash means it does not.

3. On a line with **Advanced (2)**, click it: the list shows the other permissions of the plugin, each
   one **allowed**, **refused** or **under conditions**.

A role that gives nothing says **This role gives no right.**

## 🔒 A role of the file

On a role tagged **File**, a notice says **This role comes from the configuration file, it cannot be
changed here.** For **Administrator**, it adds **To manage the administrators, add or remove a person
in the group Astrolabe administrators.** and a button **Open the group**. Click it to reach
**Groups**.

✅ That's it!

Next: [Give administrator rights to someone](give-administrator-rights.md).

---

<!-- https://doc.forgeit.fr/docs/administration/access-control/troubleshooting.md -->

# Common problems with Access Control

| What you see | What to do |
| --- | --- |
| **Create** is greyed out in the window **Create a role** | Write a **Name** with a letter or a digit, and add at least one **Member**. |
| Under **Name** you read **A role already has the identifier role:default/…** | Choose another name. |
| The icon **Remove** of a member is greyed out | A role keeps at least one member. Add another one first. |
| **Save** is greyed out after **Edit rights** | Tick or untick a box first. |
| A role has no button to add, edit or delete | It is tagged **File**: it comes from the configuration file and cannot be changed here. To make a person an administrator, see [Give administrator rights to someone](give-administrator-rights.md). |
| A button has a padlock | Your role does not allow it. Hover it to read the right that is missing, and ask an administrator. |
| A message says **You may not change the access rules (status 403)** | Ask an administrator to give you a role that allows it. |
| A message says **Someone changed this role meanwhile, or a role already uses this identifier.** | Reload the page and do it again. |
| A message says **The permissions service does not answer, so nothing was changed.** | Try again. If it lasts, open **Administration > Problems**. |
| The page **Access control** says **The roles could not be read: the permissions service answered 500. Reload the page; if it lasts, check Administration > Problems.** | Click **Retry**. If it lasts, open **Administration** > **Problems** to see what is down. |
| The page **Access control** says **The roles could not be read: the permissions service does not answer. Reload the page; if it lasts, check Administration > Problems.** | Click **Retry**. If it lasts, open **Administration** > **Problems**. |
| The window **Edit group** says **You are removing your own administrator rights.** | You took your own name out of **Members**. Click **Cancel** to keep your rights, or **Save** to give them up. |
| **Save** is greyed out in the window **Edit group** of **astrolabe-administrators**, with **The administrators group must keep at least one member.** | Keep at least one person in **Members**. |
| The bin of the row **astrolabe-administrators** is greyed out | This group gives the administrator role: it cannot be deleted. Hover the bin: **This group gives the administrator role: it cannot be deleted.** |
| A person you added to **astrolabe-administrators** does not see **Administration** | Ask them to reload the page. Check that their name is in **Members** on the row of the group. |
| A person says **Choose** is missing on the cards of The Foundry | Give their role **Scaffolder** `scaffolder.task.create`: see [Check what a role gives](check-what-a-role-gives.md). |
| A person says **Add a card** shows a padlock, with the tooltip **Your role can't add cards to dashboards. Ask an administrator.** | Give their role the **Orion-dashboard** permissions of [Check what a role gives](check-what-a-role-gives.md). |
| A person says **Arrange** shows a padlock on **My Dashboards**, with the tooltip **Your role can't edit dashboards. Ask an administrator.** | Give their role **Orion-dashboard** `dashboard.update`. |
| The tab **Tasks** of The Foundry says `Error: Request failed with 403 Forbidden` | Give the role **Scaffolder** `scaffolder.task.read`. |
| A person opens a link to Administration and reads **Off the Charts** | This person has no role for Administration. Give their role the **Administration** permissions. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the role and what the screen says.
:::

---

<!-- https://doc.forgeit.fr/docs/administration/catalog/choose-what-the-catalog-imports.md -->

# Choose what the catalog imports

The catalog fills itself from your providers: GitLab, GitHub, Azure DevOps, Bitbucket, Microsoft
Graph. In **Administration › Catalog** you choose which providers run, and what each one reads.

You do it as an administrator.

## Before you start

A provider reads your tool with the connection you added in **Company connections**. Add it first:
without it, the card of the provider says **Configure the github integration first: without it, this
provider cannot read anything.** (with the name of its tool) and its switch stays off.

## 🔧 Turn a provider on

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens, with one card per provider.

3. On the card of your provider, click **Configure**.

4. Fill in the form. Each **?** next to a field explains it.

5. Click **Install**.

6. The window **Reloading configuration** says **Please wait while the instance is reloading...**
   Wait until the page comes back.

The fields depend on the provider: follow the page of yours.

| Provider | Page |
| --- | --- |
| GitLab | [Import your GitLab projects](../../getting-started/Configuration/Catalogue/gitlab/import-projects.md) |
| GitHub | [Import your GitHub repositories](../../getting-started/Configuration/Catalogue/github/import-repositories.md) |
| Azure DevOps | [Azure DevOps](../../getting-started/Configuration/Catalogue/azure-devops/import-repositories.md) |
| Bitbucket Server | [Import your Bitbucket Server repositories](../../getting-started/Configuration/Catalogue/bitbucket-server/import-repositories.md) |
| Bitbucket Cloud | [Import your Bitbucket Cloud repositories](../../getting-started/Configuration/Catalogue/bitbucket-cloud/import-repositories.md) |
| Microsoft Graph | [Entra ID](../../getting-started/Configuration/Catalogue/microsoft-entra-id/import-users-and-groups.md) |

## 🔍 Narrow what a provider imports

On the **Configure** form of GitLab, these fields keep the catalog from filling with everything:

| Field | What it does |
| --- | --- |
| **Group** | Only this group and its subgroups. |
| **Only projects I am a member of** | Only the projects of the token's user. |
| **Project Regex** | Only the projects whose name matches, for example `^api-.*`. |
| **Skip Forked Repositories** | Leaves out forked projects. |
| **Branches** | The branches to read. |
| **Catalog File** | The file to read at the root of each project. Default: `catalog-info.yaml`. |

To change them later, click **Configure** on the card again, edit, and click **Update Configuration**.
Astrolabe reloads the same way.

## 📋 See how the collections went

Once a provider is installed, the **Providers** tab shows the **Catalog collection** table above the
cards:

| Column | What it says |
| --- | --- |
| **Provider** | The provider. |
| **State** | **Done**, **Running**, **Failed** or **Unknown**. |
| **Last run** / **Next run** | When it last ran, when it runs next. |
| **Detail** | What happened, in a sentence. |
| **Actions** | The play button of the row, for example **Run the GitLab projects collection now**. |

To collect right now, click the play button on the row of the provider: see [Run a catalog collection now](run-a-collection.md).

## ⛔ Turn a provider off

1. On the card of the provider, click **Configure**.

2. Click **Uninstall**.

✅ That's it!

Next: [Run a catalog collection now](run-a-collection.md).

Then: [Register an existing component](../../core-features/catalog/register-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/administration/catalog/faq.md -->

# Catalog FAQ

## How do I import only some of my projects?

Narrow the provider: see [Narrow what a provider imports](choose-what-the-catalog-imports.md).

## How often does a provider read my tool?

The **Catalog collection** table shows the time of the **Next run** for each provider. To read right
now, click the run button on its line.

## Why is the switch of a provider off and greyed out?

The connection of this tool is not added yet. The card says **Configure the github integration first:
without it, this provider cannot read anything.** Add it in **Administration › Company connections**.

## The collection says "Done" but the catalog stays empty

Read **Detail**. **Nothing found: no catalog-info.yaml on the branch read, or the token is not a member
of the projects.** means Astrolabe found no `catalog-info.yaml` file to read. Check the **Group**, the
**Project Regex** and the **Branches**, then run the collection again.

## Can I add one component without a provider?

Yes: [Register an existing component](../../core-features/catalog/register-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/administration/catalog/run-a-collection.md -->

# Run a catalog collection now

A provider collects your catalog by itself on a schedule (every 30 minutes for GitLab). You don't want to
wait? Start its collection yourself, and follow it on the same screen.

You do it as an administrator.

## ▶️ Start one collection

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens. Above the cards, the table
   **Catalog collection** has one row per collection:

   | Column | What it says |
   | --- | --- |
   | **Provider** | The provider. GitLab has two rows once you import groups: **GitLab** (the projects) and **GitLab (groups and users)**. |
   | **State** | **Done**, **Running**, **Failed** or **Unknown**. |
   | **Last run** / **Next run** | When it last ran, when it runs next. |
   | **Detail** | What happened, in a sentence. |
   | **Actions** | The play button of the row. |

3. On the row you want, in the **Actions** column, click the play button. For the projects of GitLab, its
   name is **Run the GitLab projects collection now**. For the groups and the users, it is **Run the GitLab
   groups and users collection now**.

Only the collection of that row starts. The other row stays as it was: the play of **GitLab** does not
start **GitLab (groups and users)**, and the other way round.

## 👀 Follow it

You don't reload the page.

1. The **State** of the row you started turns to **Running** at once, and its **Detail** shows a dash
   (**—**).

2. After a few seconds, the **State** turns to **Done**. **Last run** shows the time of this run, **Next
   run** the next one, and **Detail** says what came in, for example **3 catalog files found**. For the
   row of the groups, for example **3 groups and 1 user imported**.

The entities of the collection are now in **Catalog**.

✅ That's it!

Next: [Frequently asked questions](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/catalog/troubleshooting.md -->

# Common problems with the catalog

| What you see | What to do |
| --- | --- |
| **Failed** with `The collection failed for a reason Astrolabe could not identify. Run it again; if it fails again, tell your company's Astrolabe administrator.` | Click the run button of the provider. If it fails again, check the **Group** in **Configure**: a group that does not exist gives this. |
| **Done** with `Nothing found: no catalog-info.yaml on the branch read, or the token is not a member of the projects.` | Check the **Group**, the **Project Regex** and the **Branches** in **Configure**, then run the collection again. |
| **Unknown** with `Ran before Astrolabe restarted: its outcome is not known. Run it now to see it.` | Click the run button of the provider. |
| `Configure the github integration first: without it, this provider cannot read anything.` | Add the connection in **Administration › Company connections**. |
| `NotFoundError: Unable to read url, no matching files found for https://…` when you register a component | The address does not lead to a file Astrolabe can read. Open it in your browser, then paste the address of the file itself. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the sentence of the **Detail** column.
:::

---

<!-- https://doc.forgeit.fr/docs/administration/demo-access/manage-demo-access.md -->

# Manage access to the demo

On the ForgeIT administration instance, the **Backoffice** keeps the list of the people who may enter the
public demo. You approve a request, revoke an address, add a prospect by hand, and see what a visitor
did. Visitors follow [Ask for access to the demo](../../getting-started/request-demo-access.md).

## 🔧 Open the list

1. Sign in to the administration instance with an administrator account.

2. In the left sidebar, click **Backoffice**.

3. In the menu of the Backoffice, under **SALES**, click **Demo access**.

The page **Demo access** lists every address, the newest first, with the columns **Person**, **Email**,
**Company**, **State**, **Asked on**, **Decided by** and **Actions**. **State** is **Requested**,
**Approved** or **Revoked**.

## ✅ Approve a request

1. On the line whose **State** is **Requested**, click **Approve** (the button is named after the address).

The snack says **Access approved for** the address, **State** becomes **Approved**, **Decided by** shows your
username, and the person receives the e-mail **Your access to the Astrolabe demo is open** with the button
**Enter the demo**.

## ⛔ Revoke an access

1. On the line of the address, click **Revoke**.

2. In **Revoke this access?**, click **Revoke access**.

The snack says **Access revoked for** the address and **State** becomes **Revoked**. The person can no
longer enter the demo, and a session already open ends when its token expires.

To give the access back, click **Approve** on the same line.

## ➕ Add an address by hand

For a prospect who did not ask by themselves.

1. At the top of the page, click **Add an address**.

2. Fill in **Email**, **First name** and **Last name**. **Company (optional)** can stay empty.

3. Click **Add and notify**.

The snack says **Access granted to** the address, a line **Approved** appears, and the person receives the
same e-mail as for an approval.

## 🔍 See what a visitor did

1. On the line of the address, click **Activity**.

The window **Activity of** the address shows the first and the last visit, the pages most seen, the actions
most used, and the list of events with **When**, **What**, **Detail** and **Page**.

2. Click **Close** to leave. **Erase this activity** deletes the record of this visitor.

## ❓ Frequently asked questions

### Does an approval need the person to do anything?

No. The e-mail carries a button that signs the person in, once, for 7 days. After that the person types
the address on the demo and receives a code.

### Is the same address listed twice if it asks twice?

No. One address gives one line.

## 🛠️ Troubleshooting

| What you see | What to do |
| --- | --- |
| **Backoffice** is not in the left sidebar | You are not on the ForgeIT administration instance, or your account lacks the right. Ask an administrator. |
| The snack says **… but it could not be emailed: check the mail server and the demo address in the settings.** | The approval stands, only the e-mail did not leave. Check the mail server and the demo address in the Backoffice settings (not verified on a live instance), then tell the person to enter from the demo. |
| A visitor says the demo **cannot check accesses right now** | The demo cannot reach this instance. Check that this instance is running, then ask the visitor to try again. |

---

<!-- https://doc.forgeit.fr/docs/administration/general/faq.md -->

# General FAQ

## What are the tabs of Administration › General?

| Tab | What it holds |
| --- | --- |
| **Company** | The name of your organization. |
| **Application** | The two keys of the sign-in challenge and the Umami usage measurement: [set them](set-the-application-settings.md). |
| **Configuration** | The saved versions of your settings: [go back to an earlier one](go-back-to-an-earlier-configuration.md). |
| **Mail server** | The server Astrolabe sends e-mails from: [set it](set-the-mail-server.md). |
| **Support** | Where a support request goes: [set it](set-the-support-address.md). |
| **Push notifications** | The push services your users' browsers may use, besides Google, Mozilla, Apple and Microsoft. |
| **About** | The version of Astrolabe and of Backstage, and a **Contact Support** button. |

## A field is greyed out and says "Defined by the config file … — edit it there"

The value comes from a configuration file of your installation. It cannot be changed on this screen.
Ask the person who installed your Astrolabe.

## What is the banner "The configuration has changed."?

Settings were saved. Click **Reload** to work on the new ones.

## Which version of Astrolabe do I run?

Open **Administration › General › About**. **App Version** is the version of Astrolabe.

---

<!-- https://doc.forgeit.fr/docs/administration/general/go-back-to-an-earlier-configuration.md -->

# Go back to an earlier configuration

Every time you save settings in Administration, Astrolabe keeps a version. If a change was a mistake,
you restore an earlier version.

## 🔧 See the versions

1. In the left sidebar, at the bottom, click **Administration**.

2. At the top of the page, click the **Configuration** tab.

The page **Configuration Versions** lists the versions, the newest first. The newest says **Current
Version**. Each one has its number and its date.

## 🔍 See what a version holds

On the line of a version, click **View Changes**. The line shows what going back to this version
would remove, as a block of settings. Click **Hide Changes** to close it.

## ⏪ Restore a version

1. On the line of the version you want, click **Rollback**.

2. A window **Confirm Configuration Rollback** asks **Are you sure you want to proceed with rolling
   back to this version?** It says **The instance will restart after confirmation.**

3. Click **Rollback**.

4. The window **Reloading configuration** says **Please wait while the instance is reloading...** Wait
   until Astrolabe comes back.

The restored settings become a new version at the top of the list, and it is the **Current Version**.

✅ That's it!

Next: [General FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/general/set-the-application-settings.md -->

# Set the sign-in challenge and usage measurement

The **Application** tab holds two things: the two keys of the sign-in challenge (Cloudflare
Turnstile), and the two values that let Astrolabe measure how it is used with Umami. Leave a field
empty to switch the matching feature off.

You do it as an administrator.

## 🔧 Fill in the tab

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **SETTINGS**, click **General**, then, at the top of the page, the **Application** tab.

3. Fill in the fields you need.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Site key** | The public key of the sign-in challenge. Without it, the challenge is not shown. | `0x4AAAAAAAexample` |
   | **Secret key** | The secret key Cloudflare gives with the site key. Fill it in with the **Site key**: the screen does not save one without the other. | `0x4AAAAAAAexample-secret` |
   | **Script URL** | The address of your Umami script, scheme included. | `https://umami.exemple.com/script.js` |
   | **Website ID** | The identifier of the site, as Umami gives it. | `00000000-0000-0000-0000-000000000000` |

4. Click **Save**. The message **Settings saved.** appears at the bottom left.

✅ That's it!

Once saved, the **Secret key** is never shown again: the field is locked. To change it, click
**Replace** next to it, type the new one, then **Save**.

## 🛟 Troubleshooting

**Problems shows « The sign-in challenge is not checked: its secret key is missing, so the sign-in page
does not show it. Enter the secret key in General › Application. »**
The **Site key** is saved, its **Secret key** is not. Click **Fix it**, fill in **Secret key**, then
**Save**. Until then, the sign-in page has no challenge.

**Problems shows « The sign-in challenge is not shown: its site key is missing, so nothing is checked.
Enter the site key in General › Application. »**
The **Secret key** is saved, its **Site key** is not. Click **Fix it**, fill in **Site key**, then
**Save**.

Each save is kept as a version: see [Go back to an earlier configuration](go-back-to-an-earlier-configuration.md).

Next: [Set the support address](set-the-support-address.md).

---

<!-- https://doc.forgeit.fr/docs/administration/general/set-the-documentation-address.md -->

# Set the documentation address

Next to the name of each plugin, integration, catalog source and dashboard card, a **?** opens its
page of this documentation, in a new tab, in the language of the interface. By default, it leads to
ForgeIT's documentation site. Change it only if your company publishes the documentation at another
address.

You do it as an administrator.

## 🔗 Set the address

1. In the left sidebar, at the bottom, click **Administration**. The **General** page opens.

2. At the top of the page, click the **Documentation** tab.

3. In **Base URL**, enter the address of the documentation site, without a path.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Base URL** | The address of the site, starting with `https://`. Empty: ForgeIT's site. | `https://docs.example.com` |

4. Click **Save**. The message **Settings saved.** appears at the bottom left of the screen and goes
   away by itself.

Every **?** now leads to your site. For example, the **?** of **Compass** in **Administration ›
Plugins** opens `https://docs.example.com/docs/core-features/compass/turn-on-compass`.

✅ That's it!

To go back to ForgeIT's site, empty **Base URL**, then click **Save**.

Next: [Go back to an earlier configuration](go-back-to-an-earlier-configuration.md).

---

<!-- https://doc.forgeit.fr/docs/administration/general/set-the-mail-server.md -->

# Set the mail server

Astrolabe sends some messages by e-mail. Give it the mail server to use.

You do it once, as an administrator.

## Before you start

Ask your mail provider for the host, the port, an account and its password. The server must offer a secure connection (STARTTLS): port `587` usually does.

## 🔧 Fill in the mail server

1. In the left sidebar, at the bottom, click **Administration**. The **General** page opens.

2. At the top of the page, click the **Mail server** tab.

3. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Host** | The address of the mail server | `smtp.acme.example` |
   | **Port** | The port of the mail server, usually 587 | `587` |
   | **User** | The account used to sign in to the mail server | `astrolabe@acme.example` |
   | **Password** | The password of that account | |
   | **From** | The address the messages are sent from | `astrolabe@acme.example` |

4. Click **Save**.

5. In the banner **The configuration has changed.**, click **Reload**.

✅ That's it!

To see the settings at work, [reset the administrator password](../../getting-started/Configuration/Authentication/astrolabe-account/reset-the-password.md): the code arrives in the administrator mailbox.

Next: [Set the documentation address](set-the-documentation-address.md).

---

<!-- https://doc.forgeit.fr/docs/administration/general/set-the-support-address.md -->

# Set the support address

Your users can ask for help from Astrolabe. The support address says where the request goes.

You do it once, as an administrator.

## 🔧 Set the address

1. In the left sidebar, at the bottom, click **Administration**. The **General** page opens.

2. At the top of the page, click the **Support** tab.

3. In **Email**, enter the address.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Email** | Where a support request goes | `help@acme.example` |

4. Click **Save**. The message **Settings saved.** appears at the bottom left of the screen and goes
   away by itself.

✅ That's it!

Each save is kept as a version: see [Go back to an earlier configuration](go-back-to-an-earlier-configuration.md).

Next: [Set the mail server](set-the-mail-server.md).

---

<!-- https://doc.forgeit.fr/docs/administration/general/troubleshooting.md -->

# Common problems with General settings

| What you see | What to do |
| --- | --- |
| A field is greyed out, with **Defined by the config file … — edit it there** | The value comes from a configuration file. Ask the person who installed your Astrolabe. |
| The banner **The configuration has changed.** | Click **Reload**. |
| **The mail server does not offer an encrypted connection** when you ask for a password reset | The mail server must offer a secure connection (STARTTLS), usually on port `587`. On the **Mail server** tab, check **Host** and **Port**, then click **Save**. See [Common problems with sign-in](../../getting-started/Configuration/Authentication/troubleshooting.md). |

:::tip Still stuck?
Write to **support@forgeit.fr**, with the name of the tab and what the screen says.
:::

---

<!-- https://doc.forgeit.fr/docs/administration/licensing/add-your-license.md -->

# Add your license

Without a license, Astrolabe still works, but the licensed features are limited. You add the key you
received from ForgeIT once, and again when you renew.

You do it as an administrator.

## Before you start

Have your license key at hand: ForgeIT sent it to you.

## 🔧 Add the key

1. In the left sidebar, at the bottom, click **Administration**, then, under **SECURITY**, **Licensing**.

2. The **Overview** tab opens. Click **Add New License**.

3. In the window **Add New License Key**, paste the key in **License Key**.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **License Key** | The key from ForgeIT, copied whole | |

4. Click **Update License Key**. It stays greyed out until you paste something.

If you already had a key, the window warns **This will replace your existing license key. Make sure
you have the correct new license key before proceeding.**

✅ That's it!

What the page shows once a valid key is in place was not checked on a live instance.

Next: [Licensing FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/licensing/faq.md -->

# Licensing FAQ

## What does the line "No license configured." mean?

Astrolabe has no valid license key. The line at the top of every page names what is limited: **Without
one, Grafana, Polaris, LaunchDarkly cannot be switched on, and only the Astrolabe account can sign
in.** Click **Configure the license**: see [What a license unlocks](what-a-license-unlocks.md), then
[Add your license](add-your-license.md).

## Can I use a plugin without a license?

Yes, unless its card in **Administration** › **Plugins** shows **Requires the Premium license**. The
list is in [What a license unlocks](what-a-license-unlocks.md).

## What are the tabs of Administration › Licensing?

**Overview**, **Users** and **Access Requests**. Without a license, **Overview** says **No valid
license has been configured for this application.**

## How do I renew?

Add the new key the same way: **Add New License**. It replaces the old one.

## Where do I get a key?

From ForgeIT: write to **support@forgeit.fr**.

---

<!-- https://doc.forgeit.fr/docs/administration/licensing/troubleshooting.md -->

# Common problems with the license

| What you see | What to do |
| --- | --- |
| **Update License Key** is greyed out | Paste the key in **License Key** first. |
| The switch of a plugin is grey, and its card shows **Requires the Premium license** | Your license does not cover it. [Add a license](add-your-license.md) that does, then switch it on. |
| A plugin's card shows **Not licensed**, and **Problems** shows **Switched on, but the license does not cover it.** | The license no longer covers the plugin, and it is not switched off yet. Click **Fix it** in **Problems**, [add your new license](add-your-license.md), then check the card of the plugin in **Plugins**. |
| A plugin's card shows **Switched off: the license no longer covers it** | The license lapsed or changed. [Add your new license](add-your-license.md), then switch the plugin back on in **Plugins**. |
| **Problems** shows **Switched off: the license no longer covers it. Renew the license, then switch it back on in Plugins.** | Same as above: click **Fix it**, add the license, then switch the plugin back on. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the exact message of the page.
:::

---

<!-- https://doc.forgeit.fr/docs/administration/licensing/what-a-license-unlocks.md -->

# What a license unlocks

Some plugins need a license, and so does signing in with an outside provider. Administration ›
Licensing lists them for your instance.

You do it as an administrator.

## 🔎 See what a license unlocks

1. In the left sidebar, at the bottom, click **Administration**, then, under **SECURITY**, **Licensing**.

2. The **Overview** tab opens. Under the state of your license, the card **What a license unlocks**
   lists each plugin with the license it needs, for example:

   | Plugin | License it needs |
   | --- | --- |
   | **Grafana** | Premium license |
   | **Polaris** | Premium license |
   | **LaunchDarkly** | Premium license |

   Its last line is about signing in: **Sign-in with an external provider (GitHub, GitLab, Microsoft,
   Okta…): any license. Without one, only the Astrolabe account can sign in.**

:::tip
Without a license, the line at the top of every page says the same: **No license configured.**,
followed by the plugins that cannot be switched on. Its link **Configure the license** opens this
card.
:::

## 🔌 A plugin your license does not cover

In **Administration** › **Plugins**, its switch is grey and its card shows **Requires the Premium
license**. Click that line: it opens **Licensing**, where you [add your license](add-your-license.md).
Then switch the plugin on: see [Turn on a plugin](../plugins/turn-on-a-plugin.md).

## ⏳ When a license stops covering a plugin

A plugin that was on, and that the license no longer covers, is switched off within ten minutes:

- its card in **Plugins** shows **Switched off: the license no longer covers it**;
- **Problems** shows a line **Plugin**, with its name and **Switched off: the license no longer covers
  it. Renew the license, then switch it back on in Plugins.**

Until it is switched off, the card in **Plugins** says **Not licensed**, and **Problems** shows a line
**Plugin**, with the name of the plugin and **Switched on, but the license does not cover it.** Click
**Fix it** to open the license screen.

It does not come back on by itself:

1. [Add your new license](add-your-license.md).
2. In **Administration** › **Plugins**, switch the plugin back on.

Switching it back on once the license is renewed, and the switched-off state itself, were not checked
on a live instance.

## 📊 What Grafana does without a covering license

Grafana is part of the Premium license. Without a license that covers it:

- the **Monitoring** tab is not on the components;
- the **Alerts in trouble** card says **Your license does not cover Grafana.**;
- **Add a card** does not offer Grafana as a source;
- the alerts that Grafana sends by webhook are dropped.

See [Common problems with Grafana](../../getting-started/Configuration/Integration/grafana/troubleshooting.md).

✅ That's it!

Next: [Licensing FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/plugins/turn-off-a-plugin.md -->

# Turn off a plugin

A plugin you turn off disappears from Astrolabe: its entry in the left sidebar and its page. Its settings
are kept.

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. Click the switch at the top right of the plugin's card. The switch turns off and **Configure**
   turns grey.

✅ That's it!

To turn it on again: [Turn on a plugin](turn-on-a-plugin.md).

---

<!-- https://doc.forgeit.fr/docs/administration/plugins/turn-on-a-plugin.md -->

# Turn on a plugin

A plugin adds a page, a tab on components or a dashboard card to Astrolabe. Turn on only the ones
your teams use.

You do it as an administrator.

## 🔌 Turn on a plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. Find the plugin in the list. Each card says what the plugin shows.

4. Click the switch at the top right of its card. The switch turns on and **Configure** becomes
   clickable.

A plugin with a page of its own appears at once in the left sidebar. For example, **Tech Atlas**
appears under **Documentation**.

✅ That's it!

## ⚙️ Open the settings of a plugin

1. On the card of the plugin, click **Configure**.

2. The settings of the plugin open. Fill them in, then click **Save**.

The settings of each plugin are described on its own page.

:::tip
Once a plugin is on, its settings are also under **Administration**, in the left menu of the
administration.
:::

## 🔗 A plugin that needs an integration

Some plugins read an outside tool: Argo CD, Azure, Codacy, GitHub, GitLab, Grafana, Jira, SonarQube,
Terraform. Their switch stays grey, and their card shows **Configure the … integration first**.

1. On the card, click **Configure the … integration first**.

2. The integration of the tool opens in **Company connections**. Add it: see the page of the tool
   under [Integrations](../../getting-started/Configuration/Integration/integration.md).

3. Fill in the connection and click **Add**. A window **Reloading configuration** says
   **Please wait while the instance is reloading...**. Wait until it closes.

4. The list of the connection shows the new token. Back in **Plugins**, the switch of the plugin is on.

You have nothing to turn on: the plugin turns on by itself when you save the integration from the link
of its card. An integration added another way leaves the plugin off.

## 🔑 A plugin that needs a license

Some plugins need a license: Grafana, Polaris and LaunchDarkly need the Premium license. Without it,
their switch stays grey and their card shows **Requires the Premium license**.

1. On the card, click **Requires the Premium license**. **Licensing** opens.

2. [Add your license](../licensing/add-your-license.md).

3. Back in **Plugins**, switch the plugin on.

See [What a license unlocks](../licensing/what-a-license-unlocks.md).

Next: [Turn off a plugin](turn-off-a-plugin.md).

---

<!-- https://doc.forgeit.fr/docs/administration/problems/faq.md -->

# Problems FAQ

## What does the page list?

- A **Company connection** that cannot connect: wrong address, refused token. See
  [Company connections](../../getting-started/Configuration/Integration/gitlab/add-the-integration.md).
- A **Catalog collection** that failed: see [Choose what the catalog imports](../catalog/choose-what-the-catalog-imports.md).

- A **Catalog** block: components that name an owner the catalog does not hold. See
  [Fix a component whose owner is not found](fix-a-missing-owner.md).

## How often is it checked?

Every few minutes. Click **Check again** to check right now.

## Does an empty page prove everything works?

It says every connection that is set up connects, and every collection that is set up runs. A
connection you never set up is not listed.

---

<!-- https://doc.forgeit.fr/docs/administration/problems/find-and-fix-a-problem.md -->

# Find and fix a problem

The **Problems** page lists what does not work on your Astrolabe right now: a connection that is
refused, a catalog collection that failed, a component whose owner is not in the catalog. Each line says
where to fix it.

## 🔍 Open the page

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **STATUS**, click **Problems**.

When all is well, the page says **Nothing is broken: every integration connects and every collection
runs.**

When something is wrong, a number appears next to **Administration** in the left sidebar and next to
**Problems** in the menu of Administration: for one problem, **1 problem**.

## 🔧 Fix a problem

Each problem is a block:

- the kind of problem, for example **Company connection** or **Catalog collection**,
- the name of the source, for example **Jenkins** or **gitlab**,
- what is wrong, in a sentence.

1. Read the sentence. Example: **No server answers to the name jenkins.acme.example. Check its
   spelling against the address you open in your browser.**

2. Click **Fix it**. Astrolabe opens the screen where you correct it (here, the Jenkins connection).

3. Correct it, for example the address of the server.

4. Come back to **Problems** and click **Check again**.

The page is checked again by itself every few minutes. When the problem is solved, the block goes away.

✅ That's it!

Next: [Fix a component whose owner is not found](fix-a-missing-owner.md).

---

<!-- https://doc.forgeit.fr/docs/administration/problems/fix-a-missing-owner.md -->

# Fix a component whose owner is not found

A component names its owner in its `catalog-info.yaml`. When the catalog does not hold that owner,
nobody owns the component and it counts for no team. **Problems** lists it, so that you do not have to
open the components one by one.

## 🔍 Find the components

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **STATUS**, click **Problems**.

3. Find the block marked **Catalog**. Its title is the name the catalog does not find, for example
   `group:gitlab/does-not-exist`.

The sentence under it counts the components, for example:

`2 components name an owner missing from the catalog: group:gitlab/does-not-exist.`

Under the sentence, each component is a link. Several components that name the same missing owner are
one block.

## ✏️ Correct the owner

1. Click a component of the block. On its page, in **About**, **OWNER** shows the name it writes.

2. In GitLab, correct `spec.owner` in the `catalog-info.yaml` of the component. To build the right
   name, follow [Give a component its GitLab owner](../../getting-started/Configuration/Catalogue/gitlab/give-an-owner.md).

3. In **Administration › Catalog**, in the **Catalog collection** table, click **Run the GitLab projects collection now** (or **Run the GitLab collection now** when GitLab groups are not imported).

4. Back on **Problems**, click **Check again**.

The block goes away when no component names the missing owner any more.

✅ That's it!

Next: [Problems FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/problems/troubleshooting.md -->

# Common problems with the Problems page

| What you see | What to do |
| --- | --- |
| `No server answers to the name jenkins.acme.example. Check its spelling against the address you open in your browser.` | Click **Fix it** and correct the address of the server: the one you open in your browser, without `https://`. |
| `The last collection failed (404). Run it again from the Catalog screen.` | Click **Fix it**. On **Administration › Catalog**, check the **Group** of the provider, then run the collection again. |
| `The collection failed for a reason Astrolabe could not identify. Run it again; if it fails again, tell your company's Astrolabe administrator.` | In **Administration › Catalog**, click the run button of the provider (**Run the GitLab collection now** for GitLab). |
| `2 components name an owner missing from the catalog: group:gitlab/does-not-exist.` | The owner written in their `catalog-info.yaml` is not in the catalog. Follow [Fix a component whose owner is not found](fix-a-missing-owner.md). |

:::tip Still stuck?
Write to **support@forgeit.fr** with the sentence of the page.
:::

---

<!-- https://doc.forgeit.fr/docs/administration/webhooks/check-that-calls-arrive.md -->

# Check that GitLab reaches Astrolabe

The **GitLab** card of the **Webhooks** tab tells you what happened to the calls.

## 🔍 Read the card

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**, then the **Webhooks** tab.

3. Read the **GitLab** card:

   | The card says | It means |
   | --- | --- |
   | **No call received since Astrolabe started.** | GitLab has not called yet. |
   | **Last call accepted** followed by a date | GitLab called with the right secret. |
   | **Refused (1), last at** a date, then **the source signs with another secret than Astrolabe's: set the same one on both sides.** | GitLab called with another secret. |

✅ That's it!

Next: [Webhooks FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/administration/webhooks/faq.md -->

# Webhooks FAQ

## Do I need a webhook?

No. Without one, Astrolabe reads your tools every few minutes. A webhook makes it right away.

## Which tools have a webhook?

The **Webhooks** tab shows **GitLab**.

## Where do I find the address to give to the tool?

On the card of the source, click **Configure**, or **Manage** if a secret is already saved. The window
shows it under **Webhook URL**; **Copy address** copies it.

## I changed the secret. What now?

Click **Manage**, then **Replace**, type the new secret and click **Save Secret**. Then click
**Reload** in the banner, and put the same secret in GitLab.

## Where do I read what Astrolabe received?

On the **GitLab** card: [Check that GitLab reaches Astrolabe](check-that-calls-arrive.md).

## Who is told about what GitLab says?

See [Choose your notifications](../../developer-dashboard/notifications/choose-your-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/administration/webhooks/set-the-webhook-secret.md -->

# Set the GitLab webhook secret

A webhook lets GitLab tell Astrolabe right away when something happens, for example a pipeline that
failed, instead of Astrolabe finding out a few minutes later. Astrolabe only trusts a call signed
with a secret you both know.

You do it once, as an administrator.

## Before you start

Choose a secret: a long random text. You enter the same one in GitLab.

## 🔧 Save the secret in Astrolabe

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. Click the **Webhooks** tab.

4. On the **GitLab** card, click **Configure**.

5. In the window **Configure GitLab Secret**, next to **Webhook URL**, click **Copy address**. The button
   says **Copied**. Keep that address: you paste it in GitLab below.

6. Fill in the field:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Webhook URL** | Nothing to type: the address GitLab calls, copied in the previous step | `https://astrolabe.acme.example/api/orion-events/gitlab` |
   | **Webhook Secret** | The secret, which verifies the webhook requests | `a-long-random-text` |

7. Click **Save Secret**.

8. In the banner **The configuration has changed.**, click **Reload**.

The card now says **No call received since Astrolabe started.** and offers **Manage**.

:::tip Change or remove the secret
Click **Manage**. **Replace** lets you type a new secret, **Delete** removes it. The window shows the
address again each time.
:::

In your GitLab project, add a webhook: the address you copied is its URL, and the secret is its token. This
step was not checked on a live instance.

✅ That's it!

Next: [Check that GitLab reaches Astrolabe](check-that-calls-arrive.md).

---

<!-- https://doc.forgeit.fr/docs/administration/webhooks/troubleshooting.md -->

# Common problems with webhooks

| What you see | What to do |
| --- | --- |
| **Refused (1), last at …: the source signs with another secret than Astrolabe's: set the same one on both sides.** | Click **Manage**, **Replace**, type the secret that GitLab uses and click **Save Secret**. |
| On the **Grafana** card, **1 events reached nobody: the license does not cover this source, so its events are dropped. See Administration › Licensing.** | Grafana called with the right secret, and Astrolabe dropped the alert because the license does not cover Grafana. [Add a license](../licensing/add-your-license.md) that covers it. |
| **No call received since Astrolabe started.** | GitLab has not called yet. Check the webhook in GitLab. |
| **Save Secret** is greyed out | Type the secret in **Webhook Secret** first. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what the **GitLab** card says.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/administration.md -->

# Manage AI resources

As an administrator, you see which repositories Astrolabe reads, what each reading found or why it failed,
and every AI resource of the catalog in one table.

## Before you start

AI resources is on: see [Turn on AI resources](turn-on-ai-resources.md).

## 📋 See the repositories read

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **INTELLIGENCE**, click **AI resources**. The tab **Repositories** opens.

3. Under **Annotated repositories**, read one row per repository: **Repository**, **State**,
   **Last reading**, **Commit**, **Resources** (for example **2 skills · 1 agent**) and **Problem**.

   | State | Meaning |
   | --- | --- |
   | **Read** | The repository was read and nothing is wrong. |
   | **Read, with problems** | The repository was read; the problems are written in the column **Problem**, up to three, then **+ 1 more problem on the repository tab.** |
   | **Reading failed** | Astrolabe could not read the repository. The column **Problem** gives the cause. |

4. Click the name of a repository, or **Open the repository**, to open its tab **AI resources**. On a
   row whose reading failed because of the connection, click **Fix the connection**.

## ▶️ Read the repositories now

1. On the tab **Repositories**, click **Run now**. The message **Scan started.** appears at the bottom of
   the screen and the button says **Reading…**.

2. Wait for the end. The message says **Scan over: 3 repositories read.**, or, when some failed,
   **Scan over: 2 of 4 repositories could not be read.** It stays on the screen until you close it.

The table updates by itself.

## 📚 List every AI resource

Under the table of repositories, the table **AI resources** lists every resource of the catalog:
**Name**, **Type**, **Owner**, **Repository**, **Score** and **Could run**. Click **Type** or **Owner** and
pick a value to filter.

## ⚙️ Set the readings

1. On the tab **Repositories**, click **Scan settings**. The tab **Settings** opens, under
   **Administration › Plugins › AI resources**. The line **This plugin is configured.** appears at the top.

2. The switch **Read on a schedule** is on, with **Default value** under it: Astrolabe reads the
   repositories on its own. Set **Minutes between two readings** (30, and 5 at least).

3. Set the limits of one reading:

   | Field | What it limits | Value shown |
   | --- | --- | --- |
   | **Repositories read at most** | Annotated repositories read in one pass | 200 |
   | **Files per repository** | Files read in one repository | 2000 |
   | **AI resources per repository** | AI resources kept from one repository | 300 |
   | **File size (KB)** | Size of one file | 256 |
   | **Repository size (MB)** | Size of one repository archive | 50 |

4. Click **Save**.

*Not verified on an instance yet: saving the settings.*

## 🚨 See a failing repository from every page

1. In the left sidebar, click **Administration**. The tab **Problems** opens.

2. Find the block **AI resources**. It names the repositories Astrolabe could not read and the cause, for
   example **github.com answers something unexpected. Check the host and the API URL.**

3. Click **Fix it**. The connection that holds the cause opens.

✅ That's it!

Next: [Troubleshooting](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/faq.md -->

# AI resources FAQ

## Does Astrolabe run my skills, agents or scripts?

No. Astrolabe reads the files of the repositories you declare, indexes them and displays them. It does not
run them and does not check them: the page of each resource says so. The scripts, hooks and MCP servers it
finds are listed under **What it could run**, so you can read them before you install.

## Why is there no version number on a resource?

A resource is identified by its repository and its path, and Astrolabe shows the **Commit** it read. The
command of **Install** is pinned to that commit: you install exactly the version you read.

## Why does a runbook have no score?

No public good practice exists for runbooks, so Astrolabe does not invent checks. Skills, agents and rules
are scored: see [The quality score of AI resources](quality-score.md).

## How often are the repositories read?

On the schedule an administrator sets, and each time someone clicks **Read the repository again** or
**Run now**: see [Manage AI resources](administration.md).

## Where does the owner of a resource come from?

From the `spec.owner` of the repository's `catalog-info.yaml`. A repository without owner publishes
nothing, and says so on its tab **AI resources**: see [Troubleshooting](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/find-and-install.md -->

# Find and install an AI resource

You look for a skill, an agent or a rule on one page, read it, then copy one command that puts it in your
project.

## Before you start

AI resources is on ([Turn on AI resources](turn-on-ai-resources.md)) and at least one repository is
published ([Publish your AI resources](show-on-a-component.md)).

## 🔎 Find a resource

1. In the left sidebar, click **AI resources**. Each resource is a card with its name, its kind (**skill**,
   **agent**, **instructions file** or **runbook**), its description, the tools that read its format
   (**Format read by Claude Code, Cursor**), its owner, its repository and its score. Above the cards,
   **9 resources** counts them.

2. In **Search AI resources**, type a word of a name, a description or a tag, for example `review`. The
   cards narrow while you type.

3. To narrow further, click one of the filters and pick a value: **Type**, **Tool**, **Owner**,
   **Repository**, **Tag**. Pick **All** to remove one. For example, **Tool** › **Codex** keeps the
   resources Codex reads.

:::tip
A runbook says **Read by no AI tool: a guide for people**. It is a procedure to read, not a file to install.
:::

## 📖 Read a resource before you use it

1. Click the name of a resource. Its page opens on the tab **Overview**.

2. In **About this AI resource**, read the **Type**, the **Owner**, the **Repository**, the **Path** of the
   file, the **Commit** Astrolabe read, and **Read on**, the date of that reading.

3. Read **What it could run**. It lists the scripts, hooks, MCP servers and shell access found in the
   resource, or says **No script, hook, MCP server nor shell found.** For a skill with a script it says, for
   example, **contains 1 script (scripts/run.sh) · allows Bash**.

4. Click the tab **Content** to read the files of the resource.

:::caution
Astrolabe indexes and displays this content; it neither runs nor checks it. Read it before you install it.
:::

## 📥 Install a resource

1. On the page of the resource, click **Install**. The window **Install** opens, with a line **Made for:**
   that names the tools that read this resource.

2. Under **Your tool**, click your tool: **Claude Code**, **Cursor**, **Codex** or **GitHub Copilot**. The
   command and the folder it installs into change with the tool, for example
   **Installs into .claude/agents** for Claude Code and **.cursor/agents** for Cursor.

3. Click **Copy**. The message **Command copied** appears at the bottom of the screen.

4. Open a terminal at the root of your project and paste the command.

The command downloads only this resource, with your own Git access to the repository, and copies it into
your project. It is pinned to the commit Astrolabe read (**Pinned to commit 7ea3509**): you get that
version, not later ones. Come back to this window to update it. A resource with the same name already in
the folder is replaced.

✅ That's it!

## 🧭 When Astrolabe gives no command

| What you see in the window | Why |
| --- | --- |
| **Codex does not read this resource: it is made for Claude Code, Cursor.** | The format of the resource is not the one your tool reads. Click a tool it is made for, or ask its owner for a version for your tool. |
| **This file holds the instructions of a whole project.** | An `AGENTS.md` or `CLAUDE.md` would overwrite yours. Read it in the tab **Content** and copy what you need. |
| **No AI tool reads this resource: it is a guide for people, read it in the Content tab.** | It is a runbook. |

Next: [The quality score of AI resources](quality-score.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/quality-score.md -->

# The quality score of AI resources

Each skill, agent and rule gets a score out of 100, calculated from public good practices. You see which
checks pass, which fail, and what to change in the repository.

## Before you start

Compass is on and AI resources is on. Astrolabe creates three compasses for you: **AI skills**,
**AI agents** and **AI rules**. A runbook has no score.

## 🧭 Read the score

1. In the left sidebar, click **AI resources**. A card shows **Score: 100/100**, or **Score: 40/100**.

2. Click the name of a resource, then click the tab **Compass**. A gauge shows the score, and under
   **Assessments** each check has a green check (passes) or a red cross (fails).

3. Click a check to open it. It shows **Result** (**Passed** or **Failed**), what Astrolabe **Read**
   in the file (a field in quotes, `(empty)` when it is missing, or a count of lines, characters or
   bytes), what it **Expected** when the check has a limit (for example `at most 200 lines`), what to
   change when it fails, **Fix it in the source** to open the file, the **Source** to read, and its
   **weight**. For the agent `helper`, **Model declared** says:

   - **Result:** Failed
   - **Read in model:** (empty)
   - **Fix it in the source**
   - **To do:** Set model (sonnet, opus, haiku or inherit), so its cost and behaviour are known.
   - **Astrolabe's choice, inspired by the source — The page recommends it; Astrolabe makes it a check.**
   - **weight: 25 %**

4. Click **Source** to open the page the check comes from.

The checks that concern the file share the score equally: a Claude Code agent has four checks of 25 % each.

## 🏷️ Written by the source, or Astrolabe's choice

Under each check, one of these labels says where it comes from, followed by what it means:

| Label | Meaning |
| --- | --- |
| **Written by the source** | The page behind **Source** states the rule. |
| **Astrolabe's choice, inspired by the source** | The page does not require it; Astrolabe asks for it because it helps people find and trust a resource. |
| **Company rule** | Your company wrote it in Astrolabe. **Company page** opens the page your company gave for it. |

## ✅ The checks of a skill

| Check | What to do when it fails | Label |
| --- | --- | --- |
| **Name follows the standard** | Set `name` in `SKILL.md`: 1 to 64 lowercase letters, digits and hyphens (`pdf-processing`). | Written by the source |
| **Name matches the folder** | Set `name` in `SKILL.md` to the name of its folder. | Written by the source |
| **Has a description** | Write a `description` in `SKILL.md`, 1,024 characters at most. | Written by the source |
| **No XML tags** | Remove the tags from the name and the description. | Written by the source |
| **Under 500 lines** | Move details out of `SKILL.md` into the files it links to: keep it under 500 lines. | Written by the source |
| **Says when to use it** | Say in the description when to use the skill (« Use when… »). | Written by the source |
| **Specific name** | Rename the skill: `helper`, `utils`, `tools`, `documents`, `data` or `files` say nothing of what it does. | Written by the source |
| **Forward-slash paths** | Write the paths of the skill with `/`, never `\`. | Written by the source |
| **License declared** | Set `license` in `SKILL.md`, so people know whether they may reuse it. | Astrolabe's choice |
| **Tagged** | Add tags to the front matter, or to the repository in the catalog, so people find it in the store. | Astrolabe's choice |

Sources: the [Agent Skills specification](https://agentskills.io/specification), the
[best practices of Anthropic](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices),
the [skills of Claude Code](https://code.claude.com/docs/en/skills) and the
[guide for companies of Anthropic](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise).

## ✅ The checks of an agent

| Check | What to do when it fails | Label |
| --- | --- | --- |
| **Has a name and a description** | Set `name` and `description` in the front matter of the agent. | Written by the source |
| **Says when to use it** | Say in the description when to use the agent (« Use proactively after… »). | Written by the source |
| **Tools restricted** | List the tools the agent needs in `tools:`: without it, it gets all of them. | Written by the source |
| **Model declared** | Set `model` (`sonnet`, `opus`, `haiku` or `inherit`), so its cost and behaviour are known. | Astrolabe's choice |
| **Within Copilot's limit** | Shorten the prompt of the agent: Copilot reads 30,000 characters at most. | Written by the source |

Sources: the [sub-agents of Claude Code](https://code.claude.com/docs/en/sub-agents) and the
[custom agents of GitHub Copilot](https://docs.github.com/en/copilot/reference/custom-agents-configuration).

## ✅ The checks of a rule

| Check | What to do when it fails | Label |
| --- | --- | --- |
| **CLAUDE.md under 200 lines** | Split `CLAUDE.md` into `.claude/rules` files: keep it under 200 lines. | Written by the source |
| **Cursor rule under 500 lines** | Split the rule: keep it under 500 lines. | Written by the source |
| **Cursor rule scoped** | Set `alwaysApply`, a `description` or `globs`, so Cursor knows when to apply the rule. | Astrolabe's choice |
| **applyTo set** | Set `applyTo` with the files the instructions apply to. | Written by the source |
| **AGENTS.md under 32 KiB** | Shorten `AGENTS.md`: Codex reads 32 KiB of it at most. | Written by the source |
| **Copilot instructions under 4,000 characters** | Shorten the instructions, or put the review rules first: Copilot code review reads the first 4,000 characters. | Written by the source |

A check that does not concern the file is left out of its score: a Cursor rule is scored on the two
Cursor checks only. The tab **Compass** names them above the list, for example **1 assessment does not
concern this file: Within Copilot's limit.**

No check concerns a `GEMINI.md` nor a rule in `.claude/rules/`. Their card says **Score: no check for this
kind of file**, and their tab **Compass** says **No check of this compass is about this kind of file:
there is nothing to score.**

Sources: [memory of Claude Code](https://code.claude.com/docs/en/memory),
[rules of Cursor](https://cursor.com/docs/context/rules),
[instructions of GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions),
[code review of GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review)
and [AGENTS.md of Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

## 🏢 Add the rules of your company

Your company has its own rules: a description in French, a tag on every resource, no password in a
file. Write each one in Astrolabe, and every resource it concerns is scored on it.

You need the right to create and change Compass assessments.

### Write the rule

1. In the left sidebar, click **Administration**, then **Compass**, then the tab **Assessments**.

2. Click **Create Assessment**. A window opens.

3. In **Name**, write the name of the rule, for example `Description in French`.

4. In **Description**, write what to do when it fails, for example
   `Write the description of the agent in French.` People read it under the failed check.

5. In **Datapoint**, choose the kind of rule, for example **Company rule: frontmatter field matches**.

6. In **Passes when the check is**, choose **True**.

7. Fill in the settings under **Parameters**. For a description in French:

   - **Frontmatter field:** `description`
   - **Regular expression:** `[àâçéèêëîïôûù]`
   - **Only for these formats (optional):** `claude-code/agent`

8. In **Link to the company's page (optional)**, paste the address of your internal page about this
   rule, for example `https://intranet.example.com/ai-rules`.

9. Click **Save**. The rule appears in the list, in the block **AI resources**, and a message says
   **Assessment created. It counts in a score once added to a compass: tab Compasses, Edit, Add
   Assessment.**

### Add it to a compass

1. Click the tab **Compasses**. On the card **AI agents**, click **Edit**.

2. Under **Assessments**, click **Add Assessment**. Tick your rule, then click
   **Save Selected Assessments**.

3. Click **Save**.

✅ That's it! The next time a resource is read, its tab **Compass** shows your rule. When it fails, it
shows what it read, what it **Expected** (for example `description matching “[àâçéèêëîïôûù]”`), **Fix it
in the source**, your description after **To do:**, and **Company rule**, with **Company page**.

### The kinds of rule

| Datapoint | Settings | Passes when |
| --- | --- | --- |
| **Company rule: frontmatter field set** | **Frontmatter field** | The front matter has this field. |
| **Company rule: frontmatter field equals** | **Frontmatter field**, **Value** | The field has exactly this value. |
| **Company rule: frontmatter field matches** | **Frontmatter field**, **Regular expression** | The field matches the expression. |
| **Company rule: tag required** | **Tag** | The resource has this tag. |
| **Company rule: at most N lines** | **Maximum lines** | The file has at most this many lines. |
| **Company rule: at most N bytes** | **Maximum bytes** | The file weighs at most this many bytes. |
| **Company rule: format allowed** | **Allowed formats** | The file is in one of these formats. |
| **Company rule: file contains** | **Regular expression** | A line of the file matches the expression. |
| **Company rule: file does not contain** | **Regular expression** | No line of the file matches the expression. |

**Frontmatter field** of the two rules that read a value lists the fields Astrolabe keeps: `name`,
`description`, `model`, `tools`, `license`, `applyTo`, `globs`, `alwaysApply`.

Every rule also takes **Only for these formats (optional)**: a list separated by commas, for example
`agent-skills/SKILL.md, claude-md`. On a file of another format, the rule is left out of the score.

| Format | Files |
| --- | --- |
| `agent-skills/SKILL.md` | a skill (`SKILL.md`) |
| `claude-code/agent` | a Claude Code agent |
| `copilot/agent` | a GitHub Copilot agent (`*.agent.md`) |
| `claude-md` | `CLAUDE.md` |
| `agents-md` | `AGENTS.md` |
| `gemini-md` | `GEMINI.md` |
| `copilot/instructions` | `.github/copilot-instructions.md` |
| `copilot/path-instructions` | `*.instructions.md` |
| `cursor/rule` | a Cursor rule (`.mdc`) |
| `claude-code/rule` | a rule in `.claude/rules/` |

:::tip
A regular expression follows the RE2 syntax. `(?i)` at the start ignores the case:
`(?i)confidential`.
:::

### Problems you may meet

| What the window says under a field | What to do |
| --- | --- |
| **Not a regular expression Astrolabe can run (RE2: no look-around, no back-reference, 500 characters at most).** | Remove `(?=…)`, `(?!…)` and `\1` from the expression, or shorten it. |
| **Maximum lines must be a whole number, 0 or more.** | Write a number without sign nor decimal, for example `300`. |
| **Unknown format: …** | Write the formats exactly as in the table above. |
| **The link must start with https:// or http://.** | Paste the whole address of the page. |

## 🔄 See the score go up

1. Correct the file in Git and push it to the default branch.

2. In the left sidebar, click **Catalog**, click the component of the repository, then click the tab
   **AI resources**.

3. Click **Read the repository again**. When it is done, the message **Repository read again, score
   updated.** appears at the bottom of the screen.

4. Open the resource, then its tab **Compass**: the check you corrected has a green check.

✅ That's it!

:::tip
Without **Read the repository again**, Compass scores the AI resources every 6 hours.
:::

If you see **Score: not measured** or **Not scored yet** instead of a number, see
[Troubleshooting](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/show-on-a-component.md -->

# Publish your AI resources

Your team keeps skills, agents, rules and runbooks in a Git repository. You declare the folders in the
`catalog-info.yaml` of that repository, and Astrolabe lists each resource on the **AI resources** page and
on a tab of the repository.

The plugin must be on first: see [Turn on AI resources](turn-on-ai-resources.md).

## 📚 The four kinds of resource

| Kind | What it is | Annotation | What Astrolabe recognizes under the path |
| --- | --- | --- | --- |
| **Skill** | A folder of instructions an AI tool loads when it needs it | `astrolabe.forgeit.tech/ai-skills-path` | Each folder that contains a `SKILL.md` |
| **Agent** | A sub-agent or persona | `astrolabe.forgeit.tech/ai-agents-path` | Each `*.md` file that starts with a `name` and a `description` (front matter), and each `*.agent.md` file |
| **Rule** | The instructions given to every session | `astrolabe.forgeit.tech/ai-rules-path` | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `*.mdc`, `*.instructions.md` and the `*.md` of `.claude/rules` |
| **Runbook** | A procedure to follow, for a person or an assistant | `astrolabe.forgeit.tech/ai-runbooks-path` | Each `*.md` file |

## 🗂️ Where to put the files in the repository

A value is a path from the root of the repository: a folder or a file. Put several paths on one line,
separated by commas.

```text
acme-ai-kit/
├── catalog-info.yaml
├── AGENTS.md
├── skills/
│   └── code-review/
│       └── SKILL.md
├── .claude/
│   └── agents/
│       └── test-writer.md
├── .cursor/
│   └── rules/
│       └── typescript.mdc
└── runbooks/
    └── rotate-a-token.md
```

## 🚀 Declare the repository

1. Open the `catalog-info.yaml` at the root of the repository.

2. Add the annotations of the kinds you publish, under `metadata.annotations`. Keep only the lines you use.

   ```yaml
   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: acme-ai-kit
     description: Skills, agents and rules shared by the platform team
     tags: [ai, platform]
     annotations:
       astrolabe.forgeit.tech/ai-skills-path: skills, .claude/skills
       astrolabe.forgeit.tech/ai-agents-path: .claude/agents
       astrolabe.forgeit.tech/ai-rules-path: AGENTS.md, .cursor/rules
       astrolabe.forgeit.tech/ai-runbooks-path: runbooks
   spec:
     type: library
     lifecycle: production
     owner: group:default/platform-team
   ```

   | Field | What to enter | Example |
   | --- | --- | --- |
   | `metadata.name` | The name of the repository's component | `acme-ai-kit` |
   | `metadata.tags` | Words people search for. Every resource gets them | `[ai, platform]` |
   | `spec.owner` | The group that owns the repository. Every resource gets this owner | `group:default/platform-team` |
   | `spec.lifecycle` | `experimental`, `production` or `deprecated`. Every resource gets it | `production` |

3. Commit the file and push it to the default branch.

4. If the repository is not in the catalog yet, register it: see
   [Register a component](../catalog/register-a-component.md).

:::tip
A component without any `astrolabe.forgeit.tech/ai-…` annotation is never read.
:::

## ✨ Start from the template instead

The template creates a repository with one example of each kind and the annotations already written.

1. In the left sidebar, click **The Foundry**.

2. On the card **AI resources repository**, click **Choose**.

3. In the step **The repository**, fill in:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Name** | Lowercase letters, digits and hyphens. It names the repository and the component | `acme-ai-kit` |
   | **Description** | What the resources of this repository are for | `Skills and agents of the platform team` |
   | **Owner** | The team that answers for these resources. Click the field and pick one | `platform-team` |
   | **Kinds of resources** | Tick **Skills**, **Agents**, **Rules (AGENTS.md)**, **Runbooks**: one folder and one example for each kind you tick | all four |

4. Click **Next**.

5. In the step **Where to create it**, pick the **Host**, then fill in **Owner** (the organization or user
   of the new repository) and **Repository** (its name).

6. Click **Review**, check your answers, then click **Create**.

*Not verified on an instance yet: the creation itself, which needs a GitHub host the instance can write to.*

## ✅ Check that it worked

1. In the left sidebar, click **Catalog**, then click the component of the repository.

2. Click the tab **AI resources**. It shows the state of the reading (**Read**), the commit, and the
   resources found, for example **2 skills** and **1 agent**.

3. Click **Read the repository again**. The message **Reading of the repository started.** appears at the
   bottom of the screen, then **Repository read again: 3 resources.**

4. In the left sidebar, click **AI resources**: each resource is a card, with the owner of the repository.

✅ That's it!

Next: [Find and install an AI resource](find-and-install.md).

## ❓ Frequently asked questions

**Can I put several kinds in the same folder?** Each path belongs to one kind. A `SKILL.md` found under
`ai-rules-path` is not published as a rule: Astrolabe tells you to add its folder to `ai-skills-path`.

**Where do the owner and the lifecycle of a resource come from?** From the repository's `catalog-info.yaml`
(`spec.owner`, `spec.lifecycle`), never from the file of the resource.

**Does Astrolabe run my scripts?** No. See the [FAQ](faq.md).

**How do I remove a resource?** Delete it from the repository, or remove the annotation. It disappears at
the next reading.

**Where do I see what is wrong with my repository?** On the tab **AI resources** of the component, under
**Problems**: see [Troubleshooting](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/troubleshooting.md -->

# Troubleshooting

## The page and the plugin

| What you see | What to do |
| --- | --- |
| **AI resources is turned off by your administrator** | The plugin is off. An administrator turns it on in **Administration** › **Plugins**: see [Turn on AI resources](turn-on-ai-resources.md). |
| **No AI resources yet** | No repository is published yet, or none was read yet. Add the annotations: see [Publish your AI resources](show-on-a-component.md). On this page, **Copy the example** copies a `catalog-info.yaml` to start from. |
| **No result among 9 resources (1 active criterion).** | The search or a filter keeps nothing. Click **Clear filters**. |
| **The search did not answer.** | Click **Retry**. If it stays, tell your administrator. |
| **The values of this filter could not be loaded.** | Reload the page in a moment. |
| **50 of 120 resources shown: narrow the search or the filters.** | The page shows the first 50 resources. Type a word in **Search AI resources** or pick a filter. |
| **AI resource not found.** | The resource is not in the catalog (anymore). Go back to **AI resources** and search again. |

## The tab AI resources of a repository

Each message below appears under **Problems** on the tab **AI resources** of the component, and on the
tab **Repositories** of **Administration** › **AI resources**.

| What you see | What to do |
| --- | --- |
| **Unknown annotation `astrolabe.forgeit.tech/ai-skill-path`. Did you mean `astrolabe.forgeit.tech/ai-skills-path`?** | The name of the annotation is misspelled. Use the name it suggests. |
| **Unknown annotation `astrolabe.forgeit.tech/ai-tools-path`: Astrolabe reads ai-skills-path, ai-agents-path, ai-rules-path, ai-runbooks-path.** | Use one of the four names. |
| **The folder `playbooks` (annotation `astrolabe.forgeit.tech/ai-runbooks-path`) does not exist on the default branch.** | The path is wrong, or the folder is not pushed to the default branch yet. Fix the value of the annotation, or push the folder. |
| **0 skill recognized in `skills`: a skill is a folder that contains a `SKILL.md`.** | The path holds no skill. Check the path and that each skill folder holds a `SKILL.md`. |
| **0 agent recognized in `agents`: an agent is a Markdown file with a `name` and a `description`.** | Add `name` and `description` to the front matter of each agent file. |
| **0 instructions file recognized in `rules`: recognized are AGENTS.md, CLAUDE.md, GEMINI.md, \*.mdc, \*.instructions.md, copilot-instructions.md and .claude/rules/\*.md.** | Point `ai-rules-path` at one of these files or at the folder that holds them. |
| **0 runbook recognized in `runbooks`: a runbook is a Markdown file.** | Put a `.md` file in the folder, or fix the path. |
| **`rules/pdf/SKILL.md` is a skill: add its folder `rules/pdf` to `astrolabe.forgeit.tech/ai-skills-path`.** | A file found under another kind. Do what the message says. The same message exists for an agent or a rule: add it to the annotation named in the message. |
| **`agents/broken.md` has an invalid frontmatter at line 3: the YAML block between the two `---` lines at the top of the file cannot be read. Look at that line: an unclosed bracket or quote is the usual cause.** | Open the file, go to the line named, and close the bracket or the quote. |
| **This repository has no owner (`spec.owner`): nothing is published.** | Add `spec.owner` to the `catalog-info.yaml`, for example `group:default/platform-team`. |
| **This repository has no `backstage.io/source-location`: Astrolabe cannot read it.** | Register the repository from its URL: see [Register a component](../catalog/register-a-component.md). |
| **Only `url:` source locations can be read.** | The location of the component is not a `url:` one. Register it again from its URL. |
| **The `backstage.io/source-location` of this repository points outside the repository it was registered from: Astrolabe only reads a component in its own repository.** | Fix the annotation so it points to the repository that holds the `catalog-info.yaml`. |
| **2500 files, limit 2000: the repository is skipped, its published resources are kept.** | The repository is too big. Ask your administrator to raise **Files per repository** in **Settings**, or declare a smaller folder. |
| **350 resources, limit 300: only the first 300 are published.** | Ask your administrator to raise **AI resources per repository**, or split the repository. |
| **`skills/big/SKILL.md` weighs 300000 bytes, limit 262144: the file is skipped.** | Shorten the file, or ask your administrator to raise **File size**. |
| **60000000 bytes to read, limit 52428800: the repository is skipped, its published resources are kept.** | Ask your administrator to raise **Repository size**. |
| **250 annotated repositories, limit 200: this one is not read.** | Ask your administrator to raise **Repositories read at most**. |
| **Not read again since 10/25/2026: the resources below are those of that reading.** | The last reading failed. The cause is on the same tab. |
| **This repository has never been read successfully.** | The cause of the failure is on the same tab. |
| **Not read yet: the next reading publishes its resources.** | Click **Read the repository again**. |
| **You are not allowed to refresh this component.** | Your role does not let you read the repository again. Ask an administrator, or wait for the next reading. |
| **A reading is already running: try again in a moment.** | Wait, then click again. |
| **The repository was not read again within 2 minutes: reload the page in a moment.** | Reload the page. |

## When the reading fails

The state is **Reading failed**. The message starts with the host Astrolabe tried to reach, for example
`gitlab.exemple.com`.

| What you see | What to do |
| --- | --- |
| **gitlab.exemple.com refuses the credentials (401): the token of the connection may be wrong or expired.** | In **Administration** › **Company connections**, replace the token. |
| **github.com refuses the credentials: the token of the connection may be wrong or expired.** (no status) | Astrolabe could not even use the credentials: on GitHub, it is most often a **GitHub App** whose private key is not the content of the `.pem` file. In **Administration** › **Company connections** › **GitHub Apps**, paste the whole `.pem` file again, from `-----BEGIN` to `-----END`. |
| **gitlab.exemple.com accepts the token but refuses access (403): give the token read access to this repository.** | Give the token the right to read the repository. |
| **gitlab.exemple.com answers « not found » (404): the repository moved, or the token cannot see it.** | Check the address of the repository, and that the token sees it. |
| **No server answers to the name gitlab.exemple.com: check the host of the connection.** | Fix the host in **Company connections**. |
| **gitlab.exemple.com does not answer in time: check its name and port.** | Fix the name and the port of the connection. |
| **gitlab.exemple.com refuses the connection: check the port, and that the server runs.** | Check the port, and start the server. |
| **Astrolabe does not trust the certificate of gitlab.exemple.com (often an internal one).** | Tell the administrator of Astrolabe: the certificate must be trusted. |
| **gitlab.exemple.com is too busy to answer (429): the next reading tries again.** | Wait for the next reading, or click **Run now** later. |
| **gitlab.exemple.com answers something unexpected.** | Check the host and the API URL of the connection in **Company connections**. |
| **Astrolabe could not read this repository on gitlab.exemple.com.** | Read the other messages of the tab. |

Click **Fix the connection** on the row to open the connection. Above its tokens, the page says which one
reads the host, for example **Astrolabe reads gitlab.exemple.com with the token « GitLab ».** If it says
**No token of this connection is for gitlab.exemple.com: add one with « Add Token ».**, add a token for that host.
The **Host** column gives the host of each token.

## When a reading runs

| What you see | What to do |
| --- | --- |
| **A scan is already running: Astrolabe follows it.** | Wait for the end: the table updates. |
| **The scan stopped before reading the repositories: the catalog did not answer. Try again in a moment.** | Click **Run now** again in a moment. |
| **The scan did not finish within 2 minutes: the table updates when it does.** | Wait: the table updates when the scan is over. |
| **The state of the repositories could not be read.** | Reload the page. |
| **The catalog did not answer: the AI resources cannot be listed now.** | Reload the page in a moment. |

## The file of a resource

| What you see | What to do |
| --- | --- |
| **The file could not be read: reload the page in a moment.** | Reload the page. |
| **This file cannot be shown: its name holds characters Astrolabe does not read (a space, an accent…).** | Rename the file in the repository without space or accent. |
| **Shown in part: the file is longer than what Astrolabe reads.** | Read the end of the file in the repository. |

## The window Install

| What you see | What to do |
| --- | --- |
| **Codex does not read this resource: it is made for Claude Code, Cursor.** | Pick a tool it is made for. |
| **This file holds the instructions of a whole project.** | Read it in the tab **Content** and copy what you need. |
| **Astrolabe cannot compute an install command for gitlab.exemple.com yet.** | Copy the files from the repository by hand. |
| **Astrolabe gives no command for this resource: its path or address cannot be put safely in a command.** | Copy the files from the repository by hand. |
| **Astrolabe gives no command for this resource: its server answers over http and Astrolabe could not read the commit, so nothing proves the files would be the ones it read.** | Copy the files from the repository by hand, or read the repository again. |
| **Not pinned: Astrolabe could not read the commit. The command installs the current state of the default branch.** | Read the repository again to pin the command to a commit. |
| **Could not copy: select the text.** | Select the command with the mouse and copy it. |

## The score

| What you see | What to do |
| --- | --- |
| **Not scored yet** | Compass has not scored the resource yet. Click **Read the repository again** on the tab **AI resources** of the repository: it scores at once. |
| **Score: not measured** or **Not measured** | Compass could not measure the checks. Open the tab **Compass** of the resource and read the reason under **Not measured**. |
| **Score unavailable: Compass did not answer.** | Reload the page in a moment. If it stays, tell your administrator: the Compass plugin must run. |
| **Astrolabe has not read this AI resource yet: read its repository again from the AI resources tab of the repository.** | Do what it says. |
| **The repository was read again, but Compass could not update the score: try again in a moment.** | Click **Read the repository again** in a moment. |
| **Some checks could not be measured: they count neither for nor against the score.** | Read the reason under each **Not measured** check. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/ai-resources/turn-on-ai-resources.md -->

# Turn on AI resources

AI resources gathers the skills, agents, rules and runbooks your teams keep in their repositories, on one
page of Astrolabe. Each user finds them there and reads them before installing them in their AI tool.

You turn it on once, as an administrator. It is off on a new instance.

## 🔌 Turn on the plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. On the **AI resources** card, click the switch **Enable AI resources**. The page reloads and the message
   **AI resources is on** appears at the bottom of the screen.

4. In the left sidebar, click **AI resources**. The page says **No AI resources yet** until a repository
   publishes some (see [Publish your AI resources](show-on-a-component.md)).

✅ That's it!

Next: [Publish your AI resources](show-on-a-component.md), to fill the page.

## ❓ Frequently asked questions

**Who can turn it on?** Only an administrator.

**Is there anything to configure?** No. The plugin reads the repositories your catalog already reads.

**How does a resource get on the page?** A team declares the folders of its repository in its
`catalog-info.yaml`: see [Publish your AI resources](show-on-a-component.md).

## 🛠️ Troubleshooting

**The page says "AI resources is turned off by your administrator".** The plugin is off on this instance.
An administrator turns it on in **Administration** › **Plugins** (steps above).

**There is no AI resources entry in the left sidebar.** Same cause: the plugin is off.

---

<!-- https://doc.forgeit.fr/docs/core-features/announcements/faq.md -->

# Announcements FAQ

## Who sees an announcement?

The users of the groups chosen in **Select Groups**. With **All Groups**, everyone.

## Can I publish an announcement?

Only administrators can: **Manage Announcements** is in **Administration**. Everyone else reads
them with the megaphone ([Read the announcements](read-announcements.md)).

## Does a draft show in the megaphone?

No. A **Draft** announcement is saved in **Manage Announcements**, and nobody else sees it.

## Can I change an announcement I published?

Yes: in **Manage Announcements**, click its title, change it and click **Save**. The users who were
already notified are not notified again.

---

<!-- https://doc.forgeit.fr/docs/core-features/announcements/publish-an-announcement.md -->

# Publish an announcement

You are an administrator and you want to tell your users something: write the announcement, choose
its audience, and publish it.

## Before you start

You are signed in as an administrator.

## Publish

1. In the left sidebar, at the bottom, click **Administration**.
2. In the menu on the left, under **SETTINGS**, click **Announcements**.
3. At the top right, click **New Announcement**.
4. Fill in the form **Create Announcement**:

| Field | What to write | Example |
| --- | --- | --- |
| **Title** | The title (required) | `Planned maintenance` |
| **Description** | The text (required) | `Astrolabe is unavailable on Saturday from 8 pm to 9 pm.` |
| **Select Groups** | Who reads it. Click the field, pick **All Groups** or one team, then press Escape to close the list | `All Groups` |
| **Status** | It starts as **Draft**. Pick **Active** to publish now | `Active` |
| **Severity** | **Low**, **Normal**, **High** or **Critical** | `Normal` |

Under the **Select Groups** field, the number of readers appears, for example **7 users will be
notified**.

5. Click **Create**. The button stays grey until the required fields are filled in.

The list **Manage Announcements** shows your announcement with its **Audience** (**All Groups**, or
the name of the team), its **Status** (**Active**) and its **Published On** date, written in the
language of the interface. A draft reads **Inactive**. Your users see it in the megaphone: see
[Read the announcements](read-announcements.md).

## Prepare an announcement for later

The **Status** field also offers:

| Status | What it does |
| --- | --- |
| **Draft** | Saves the announcement without showing it to anyone. Its **Published On** reads `-` |
| **Scheduled** | Adds the field **Date and time of scheduling**: pick a date to come |

## Change an announcement

1. In **Manage Announcements**, click the title of the announcement.
2. In **Edit Announcement**, change what you want. On an announcement that is already active, a banner
   says: **This announcement is currently active. Recipients who have already been notified won't be
   notified again.**
3. Click **Save**.

## Delete an announcement

1. In **Manage Announcements**, at the end of its row, click the red bin (**Delete announcement**).
2. In the window **Delete Announcement**, click **Delete**.

✅ That's it!

Next: [Announcements FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/announcements/read-announcements.md -->

# Read the announcements

Your company uses announcements to tell every Astrolabe user something: a planned maintenance, a
new feature. You read them from the top bar.

## Open the announcements

1. At the top right of any page, click the megaphone (**Announcements**).

A panel opens on the right. It lists each announcement with its title, its text and when it was
published. When there is none, it says **No announcements** and **When announcements are available,
they'll appear here.**


:::tip When you open Astrolabe
An active announcement you have not read yet opens by itself in an **Important Announcements** window. Click **Understood** to close it.
:::

## Read one in full

1. In the panel, click the title of an announcement.

The page shows the title, **Published on** and its date, and the full text.

2. Click **Back to Announcements** to return to the list of all the announcements.

## See all the announcements

1. In the panel, click **All announcements** (under the list).

The **Announcements** page lists each announcement with its **Title**, its **Description** and its
**Published On** date. Click **Show 10 results** at the bottom to show 5, 10 or 25 per page.

2. Click the title of an announcement to open it.

✅ That's it!

Next: [Publish an announcement](publish-an-announcement.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/announcements/troubleshooting.md -->

# Common problems with announcements

| What you see | What to do |
| --- | --- |
| **No announcements** in the megaphone panel | Nothing was published for you. |
| **Create** is grey in the form | Fill in **Title**, **Description** and **Select Groups**: they are marked **(Required)**. |
| **Nothing here yet** and **There are no items to display.** in **Manage Announcements** | You have not published any announcement yet. Click **New Announcement**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/browse-the-catalog.md -->

# Browse the catalog

The catalog lists everything your company builds and runs: components, APIs, systems, teams. You open
it, pick a kind of thing, and open its page.

## Open the catalog

1. In the left sidebar, click **Catalog**.

The page opens on the **Components** tab: one row per component, with its **Name**, **System**,
**Owner**, **Type**, **Lifecycle** and **Description**.

## Switch to another kind of thing

1. Above the list, click another tab.

| Tab | What it lists |
| --- | --- |
| **APIs** | The interfaces your components offer or use |
| **Components** | Services, websites, libraries |
| **Domains** | Business areas that group systems |
| **Groups** | Teams |
| **Resources** | Databases, queues, caches |
| **Systems** | Components that work together as one product |
| **Templates** | The templates of [The Foundry](../the-foundry/create-a-component.md) |
| **Users** | The people of your Astrolabe |

## Open the page of a component

1. In the **Name** column, click the name of a component, for example `order-service`.

The page opens on its **Overview** tab. The **About** card shows its **Description**, **Owner**,
**System**, **Type**, **Lifecycle** and **Tags**. Click the owner or the system to open their pages.

The other tabs of the page:

| Tab | What it shows |
| --- | --- |
| **Overview** | The **About** card and the cards your administrator turned on |
| **Api** | The APIs the component provides, in **Provided APIs** |
| **Dependencies** | A graph of the components, resources and teams it is linked to, and the **Depends on components** list |
| **Docs** | The documentation of the component: see [Read the documentation of a component](../techdocs/read-component-docs.md) |

:::tip Back to the list
In the title of the page, click **Catalog** to come back to the list you left.
:::

✅ That's it!

Next: [Filter the catalog](filter-the-catalog.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/faq.md -->

# Catalog FAQ

## What does **Search by name** look at?

Only the name. A word of the description, a tag or the owner is not searched: use
[**Filters**](filter-the-catalog.md) for those.

## Where do I see the members of a team?

Open the **Groups** tab, click the team, and read **members** on its page: see
[See a group and its members](../groups/see-a-group.md).

## Why do I see fewer rows than I expect?

A filter is still on: an owner, a lifecycle, a tag, **Starred**, or a name in **Search by name**. Open
**Filters** and remove it, and clear the search field.

## How do I find the documentation of a component?

Open the component and click its **Docs** tab, or click **Documentation** in the left sidebar: see
[Read the documentation of a component](../techdocs/read-component-docs.md).

## Why are **Edit** and **Unregister entity** greyed out?

Your role does not let you change or remove a component. You see them on the page of a component
(**Edit** in the **About** card, **Unregister entity** in its **more** menu) and in **More actions**
on a row of the list. You can still open it, star it and watch it.

## Where is a component that nobody listed yet?

It is added to the catalog by registering its `catalog-info.yaml` file.

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/filter-the-catalog.md -->

# Filter the catalog

Your catalog is long. Type part of a name, or filter by owner, lifecycle or tag, to keep only what you
are looking for.

## Find a thing by its name

1. In the left sidebar, click **Catalog**.
2. Above the list, click in **Search by name** and type part of the name, for example `order`.

Only the rows whose name holds what you typed stay.

## Filter by owner, lifecycle or tag

1. Above the list, on the right, click **Filters**. A panel opens on the right.
2. Pick what you want:

| Filter | What it keeps | Example |
| --- | --- | --- |
| **Type** | Only one type of component | `service` or `website` |
| **Owner** | The things owned by the teams you pick | `platform-team` |
| **Lifecycle** | The things in the phases you pick | `experimental` |
| **Tags** | The things that carry the tags you pick | `backend` |
| **Namespace** | The things of the namespace you pick | `default` |

3. In **Owner**, **Lifecycle** or **Tags**, click the field and click a value in the list. You can pick
   several values. The list behind the panel updates at once.
4. Click **Close** when you are done.

To remove a value, open **Filters**, click the field and click the value again.

:::tip Share what you see
The address of the page keeps your filters. Copy it to send the same list to a colleague.
:::

## Keep only your own things

In **Filters**, the **Personal** block holds two entries, each with a number:

| Entry | What it keeps |
| --- | --- |
| **Owned** | The things you own |
| **Starred** | The things you added to your favorites |

Click one to keep only those. Click **All** to see everything again.

✅ That's it!

Next: [Star a component](star-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/register-a-component.md -->

# Register an existing component

Your component already has a `catalog-info.yaml` file in its repository. Give its URL to Astrolabe:
the component appears in the catalog.

## Before you start

- The URL of the `catalog-info.yaml` file, as your browser shows it. Example:
  `https://github.com/acme/shop-api/blob/main/catalog-info.yaml`.
- The integration of the tool that hosts the file (GitHub, GitLab…) in **Company connections**. See
  [Integrations](../../getting-started/Configuration/Integration/integration.md).

## 📥 Register the component

1. In the left sidebar, click **Catalog**.

2. At the top right of the page, click **Register an existing component**.

3. In **URL**, paste the URL of the `catalog-info.yaml` file.

4. Click **Analyze**. Astrolabe reads the file and lists **The following entities will be added to
   the catalog:**.

5. Check the list, then click **Import**. The screen says **The following entities have been added
   to the catalog:**.

6. Click **View Component** to open its page.

✅ That's it!

To add another one, click **Register another**.

## Common problems

| What you see | What to do |
| --- | --- |
| **Nothing was found at this address. Check that the file exists on …, on the branch you typed, then try again.** | The file is not at this address. Open the URL in your browser, copy the address of the `catalog-info.yaml` file itself, and paste it again. |
| **Astrolabe is not connected to …. Ask an administrator to add it in Administration › Company connections, then try again.** | Astrolabe has no integration for this host. Ask your Astrolabe administrator to add it in **Company connections**. |
| **The file was found, but it is not a valid component description. Check that it starts with apiVersion, kind and metadata, then try again.** | The file is not a component description. Open it and check that it starts with `apiVersion`, `kind` and `metadata`. |
| **Astrolabe could not read this address. Check the address, then try again.** | Check the address for a typo, then click **Analyze** again. |
| **The following locations already exist in the catalog:** | The file is already registered. Click **Refresh** to read it again, or **Back** to enter another URL. |

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/star-a-component.md -->

# Star a component

A star keeps a component within reach: one click in **Filters** and the list holds only your
favorites.

## Star a component

1. In the left sidebar, click **Catalog**.
2. At the end of the row of the component, click the three dots (**More actions**), then **Add to
   favorites**.

:::tip From the page of the component
Next to the name of the component, click the empty star. It turns yellow.
:::

## List your favorites

1. Above the list, click **Filters**.
2. In the **Personal** block, click **Starred**. The number next to it is how many favorites you have.

## Remove a favorite

1. At the end of its row, click the three dots (**More actions**), then **Remove from favorites**.

The same three dots also hold **Watch**, to hear of everything that happens to a component: see
[Watch a component](../../developer-dashboard/notifications/watch-a-component.md).

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/core-features/catalog/troubleshooting.md -->

# Common problems with the catalog

| What you see | What to do |
| --- | --- |
| **No data to display** in the list | No name holds what you typed in **Search by name**, or a filter keeps nothing. Clear the field and remove the filters in **Filters**. |
| The list is empty after you picked a value in **Filters** | Open **Filters** on the **Components** tab, where **Owner**, **Lifecycle** and **Tags** are shown, and remove the value: click the field, then click the value again. |
| **Starred** or **Owned** shows `0` and cannot be clicked | You have no favorite yet (or own nothing). Star a component first: see [Star a component](star-a-component.md). |
| The **Docs** tab of a component says **Missing Annotation** | See [Common problems with the documentation](../techdocs/troubleshooting.md). |
| **Edit** or **Unregister entity** is greyed out | Your role does not let you change or remove a component: see the [FAQ](faq.md). |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/add-the-dashboard-card.md -->

# Add the Compass card to your dashboard

The **Compass** card lists the scores of the components of the catalog on **My Dashboards**, so you see
what needs work without opening each component.

## Before you start

**Compass** is turned on in **Administration › Plugins**. Until then, the source `astrolabe` is not
offered in **Add a card**. See [Turn on a plugin](../../administration/plugins/turn-on-a-plugin.md).

## What it shows, and to whom

One line per component of the catalog: **Name**, **Owner**, **Mine**, one column per active compass,
and **Global Score**. **Mine** says **Mine** or **Others**: to keep only your components, filter on it
and save the filter with the card, see
[Keep only your rows](../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

*A card with scores in it was not checked on a live instance.*

Compass allows reading scores with one permission for the whole catalog. If your role does not have it,
the card says **Your role does not allow seeing the Compass scores. Ask an administrator.** above the
table.

With no score to show, the card says **Nothing here yet** and why: **No component of the catalog has a Compass score to show yet.**
Click **Learn more** under the sentence to come back to this page.

## ➕ Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, choose **Source** `astrolabe` and **Key** `Compass`. The line under the key
   reads **Compass scores per component**.

4. Type a **Card Name**, for example `Scores`, then click **Add**.

:::tip A card too narrow?
Click **Arrange**, drag the corner at the bottom right of the card to widen it, and click **Done**.
:::

✅ That's it!

Next: [Frequently asked questions](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/create-a-compass.md -->

# Create a compass

A compass is a list of rules that Astrolabe checks on your components. You write the rules
(**assessments**) first, then you group them in a compass.

## Before you start

You need to be an administrator, and Compass must be on ([Turn on Compass](turn-on-compass.md)).

## 1. 📝 Create an assessment

An assessment is one rule: "this datapoint, compared this way, with this value".

1. In **Administration**, under **INTELLIGENCE**, click **Compass**, then the **Assessments** tab.

2. Click **Create Assessment**.

3. Fill in the form:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Name** | What the rule checks | `Has an on-call schedule` |
   | **Description** | Why it matters | `Someone is on call for it.` |
   | **Datasource** | Where the value comes from | `Catalog` |
   | **Datapoint** | The value to read | `PagerDuty Set` |
   | **Passes when the check is** | What it must be | `True` |

   A yes-or-no datapoint, like this one, asks only **Passes when the check is**. A datapoint that
   reads a number (a count, a duration, a percentage) asks an **Operator** and a **Value** instead,
   for example `Greater than` and `80`.

   Under **Rules**, **All Of** means every rule must pass, **Any Of** means one is enough. Click
   **Add Rule** for a second rule.

4. Click **Save**. **Assessment saved successfully** appears, and the rule is in the table.

:::tip Which datasources can I use?
The **Data Sources** tab lists every datasource and datapoint. A datasource other than **Catalog**
(GitHub, GitLab, Jira, SonarQube, Azure, Repository) needs its connection in **Administration ›
Company connections**.
:::

## 2. 🧭 Create the compass

1. Click the **Compasses** tab, then **Create Compass**.

2. Fill in the form:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Name** | The name of the compass | `Production readiness` |
   | **Description** | What it is for | `What a service needs before it goes to production.` |
   | **Entity Kind** | The kind of entity it grades | `Component` |
   | **Entity Type** | A type, or `all` | `all` |
   | **Owners (optional)** | Only the components of these owners | |

3. Under **Assessments**, click **Add Assessment**. Tick the rules to use (**Select All** ticks them
   all), then click **Save Selected Assessments**.

4. Click **Save**. **Compass created** appears, and you are back on the **Compasses** tab, where the
   compass has its card.

## 3. ✅ Turn it on

1. On the card of the new compass, click the switch at the top right. **Compass updated** appears.

2. Click the score link on the card. The **Scores** tab shows a column for your compass.

✅ That's it!

Next: [Run a campaign](run-a-campaign.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/faq.md -->

# Frequently asked questions

## Where do I find the Compass page in the sidebar?

There is no entry in the left sidebar. Compass lives on each component (the **Compass** tab) and in
**Administration**, under **INTELLIGENCE**. To open the table of scores, click the score link on the
card of a compass.

## Why does the Compass card on my dashboard say "Nothing here yet"?

Because no component of the catalog has a Compass score yet. The card says it word for word: "No
component of the catalog has a Compass score to show yet." Check that a compass is on and grades your
components: see [Create a compass](create-a-compass.md).

## Why does the Compass card say "Your role does not allow seeing the Compass scores"?

Because your role does not have the permission that reads Compass scores, which is one permission for
the whole catalog. Ask an administrator: the card says "Your role does not allow seeing the Compass
scores. Ask an administrator."

## Does the Compass card show only my components?

No: it lists every component of the catalog. The column **Mine** says **Mine** or **Others**: filter on
it to keep yours, see
[Keep only your rows](../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

## Can I create a compass?

Not without administration rights: compasses, assessments and campaigns are created in
**Administration › Compass**, which only administrators see. You read the scores: the **Compass** tab
of a component, the **Compass Statistics** card on its **Overview**, and the **Compass** card of your
dashboard.

## What does Compass grade?

Components: the **Compass** tab is on the page of a component.

## What is the Global Score?

The average of the scores of the compasses shown in the table.

## Which components does a compass grade?

Those that match its **Components Filter**: the **Entity Kind**, the **Entity Type**, and the
**Owners (optional)** you chose in the compass.

## Can I edit or delete the Catalog essentials compass?

Yes, like any other compass: click the pencil on its card, then **Save** or **Delete**.

## A new compass has no score yet.

A new compass is off. Click the switch on its card, then open its score link.

## Where do I create compasses, assessments and campaigns?

In **Administration › Compass**.

## Can scores be refreshed on a schedule?

Yes. In **Administration › Compass**, open the **Settings** tab and tick **Run periodic scans**
under **Compass scans** and under **Campaign scans**, then click **Save**.

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/run-a-campaign.md -->

# Run a campaign

A campaign follows one or more rules across your components until a deadline, and shows what still
fails. Use it for a clean-up with a date: "every component documented by the end of the year".

## Before you start

You need to be an administrator, and the rule you want to follow must exist as an assessment
([Create a compass](create-a-compass.md)).

## 🚩 Create the campaign

1. In **Administration**, under **INTELLIGENCE**, click **Compass**, then the **Campaigns** tab.

2. Click **Create Campaign** (or **Create my first campaign** on an empty list).

3. **Details**: fill in the form, then click **Next**.

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Name** | The name of the campaign | `Docs by year end` |
   | **Owner** | The team in charge | `platform-team` |
   | **Description** | The goal | `Every component documented.` |
   | **Start Date** | The first day | |
   | **End Date** | The deadline | `2026-12-31` |

4. **Checks**: in **Datasource**, choose `Catalog`. In **Checks**, choose the rule to follow, for
   example `Has documentation`. Click **Next**.

5. **Filters**: choose the components concerned (**Entity Kind**, **Entity Type**, **Owner
   (optional)**). Click **Next**.

6. **Milestones**: click **Add Milestone**, then give it a **Name**, a **Target value (%)** and a
   **Due Date**. Click **Next**.

7. **Notifications**: tick when Astrolabe must notify: when the campaign starts, when it ends, when
   it is cancelled, when a milestone is reached. Click **Next**.

8. **Review**: read the summary, then click **Save**.

The campaign appears on the **Campaigns** tab with its status **Active**, the days left, a progress
bar, the number of checks and of components.

## 👀 Follow it

1. Open the **Compass** page (the link of a compass score, see
   [See the scores of all components](see-the-scores-of-all-components.md)), then the **Campaigns**
   tab.

2. Click the campaign. You see **Progress**, **Days Left**, **Components**, **Checks Completed**,
   **Completion Rate**, the **Checks**, a **Timeline** and the table of **Components**.

✅ That's it!

Next: [Add the Compass card to your dashboard](add-the-dashboard-card.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/see-the-score-of-a-component.md -->

# See the score of a component

Open a component to see its score for each compass, and which rules it fails.

## Before you start

Compass is on ([Turn on Compass](turn-on-compass.md)) and at least one compass is active.

## 🧭 Read the score on the Overview

1. In the left sidebar, click **Catalog**, then click a component.

2. On the **Overview**, find the **Compass Statistics** card. On the left, a gauge shows the score in
   percent, with the level reached under it (for example **Orbital Tuning**). Next to it, each compass
   has its own line with its score. The card is as tall as what it shows.

## 🔎 See which rules fail

1. At the bottom of the **Compass Statistics** card, click **View details**. The **Compass** tab opens.

2. At the top, a line of six levels shows how far the component has gone: **Star Dust**,
   **Constellation**, **Alignment**, **Orbital Tuning**, **Stellar Calibration**, **Celestial
   Harmony**.

3. Under it, each compass has its own block: its name, its description, a gauge with the score, and
   its **Assessments**. A green check means the rule passes, a red cross means it fails.

4. Click a rule to open it. It shows **Actual** (what Astrolabe found), **Expected** (what the rule
   asks) and the **weight** of the rule in the score. A yes-or-no rule shows **Result: Passed** or
   **Result: Failed** instead, with what Astrolabe **Read** when the source says it.

5. Click **Run scan** to evaluate the component again. **Last evaluated** shows when it was last
   done. **Run scan** is greyed out when your role does not allow it: the score stays the last one.

:::tip How the score is made
The score is the share of rules that pass, each counted with its weight. A compass with six rules of
the same weight gives each rule 17 %: five rules passed gives 83.3 %.
:::

✅ That's it!

Next: [See the scores of all components](see-the-scores-of-all-components.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/see-the-scores-of-all-components.md -->

# See the scores of all components

One table shows every component and its score for each compass, to see where to act first.

## Before you start

You need to be an administrator: the table is in **Administration**. Without it, the **Compass** card
of your dashboard lists the scores of the components of the catalog: see
[Add the Compass card to your dashboard](add-the-dashboard-card.md).

Compass is on and at least one compass is active ([Turn on Compass](turn-on-compass.md)).

## 📊 Open the table

1. In the left sidebar, at the bottom, click **Administration**, then, under **INTELLIGENCE**,
   **Compass**.

2. On the card of a compass, click its score link (for example **Average score: 71.4 %**; a compass not calculated yet says **Not scored yet**).

The **Scores** tab opens on that compass only: the **Compass Name** filter shows its name. Its
columns are **Entity Name**, **Owner**, one column per compass shown, and **Global Score**, which is
the average of the compass scores shown. To see every compass, choose **All** in the **Compass Name**
filter.

3. Click the name of a component to open it.

## 🔍 Filter the table

1. At the top right, click **Filters**.

2. Choose a **Compass Name**, an **Owners** value, or move the **Global Score Range** sliders
   (**0 – 100**).

3. Click **Close**.

✅ That's it!

Next: [Create a compass](create-a-compass.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/troubleshooting.md -->

# Common problems with Compass

| What you see | What to do |
| --- | --- |
| No **Compass** tab on a component | Turn on **Compass** in **Administration › Plugins**. The tab is on the page of a component. |
| `No compasses available for this entity yet.` in the **Compass** tab | No active compass grades this component. Click **Create a compass**, or turn on a compass in **Administration › Compass**, and check its **Components Filter**. |
| **Nothing here yet** and `No component of the catalog has a Compass score to show yet.` in the **Compass** card of **My Dashboards** | No compass grades a component yet. Turn on a compass in **Administration › Compass**, and check its **Components Filter**. |
| `Your role does not allow seeing the Compass scores. Ask an administrator.` above the table of the **Compass** card | Your role cannot read Compass scores. Ask an administrator to give it the permission. |
| No key **Compass** in **Add a card** | Turn on **Compass** in **Administration › Plugins**. |
| The **Compass** entry is missing in **Administration** | Turn on **Compass** in **Administration › Plugins**. |
| The new compass shows no score | Click the switch on its card to turn it on, then open its score link. |
| A rule is red and you do not know why | Open the **Compass** tab of the component, click the rule: **Actual** and **Expected** (or, for a yes-or-no rule, **Result** and **Read**) show what Astrolabe found and what the rule asks. |
| A rule on GitHub, GitLab, Jira, SonarQube or Azure does not measure | Add the connection in **Administration › Company connections**: the **Data Sources** tab says which one a datasource needs. |
| **Run scan** is greyed out in the **Compass** tab | Your role does not allow a new scan. The score shown is the last one: see **Last evaluated**. |
| `You are not allowed to run the calculations: ask an administrator for the right to refresh the scores.` | Your role cannot refresh the Compass scores. Ask an administrator to give it the permission. |
| `Astrolabe could not run the calculations: try again in a minute; if it persists, tell your company's Astrolabe administrator.` | Wait a minute and click **Run calculations** again. If the message comes back, write to your company's Astrolabe administrator. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and of the compass.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/compass/turn-on-compass.md -->

# Turn on Compass

Compass gives each component a score, based on rules such as "has an owner" or "has documentation".
You turn it on once, in the administration.

## Before you start

You need to be an administrator. Compass needs no connection for its first rules: they read the
catalog.

## 🔌 Turn on the plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. In the Administration menu, under **PLATFORM**, click **Plugins**.

3. On the **Compass** card, click the switch at the top right of the card. It turns on at once.

A new entry, **Compass**, appears in the Administration menu, under **INTELLIGENCE**. Click it: the
**Compasses** tab already holds one compass, **Catalog essentials**, with six rules about what every
component should say about itself (an owner, a description, a lifecycle, a system, documentation, a
link to its repository).

Each component now has a **Compass** tab, and a **Compass Statistics** card on its **Overview**.

✅ That's it!

Next: [See the score of a component](see-the-score-of-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/cost-insights/troubleshooting.md -->

# Common problems with Cost Insights

| What you see | What to do |
| --- | --- |
| The **Configure** button of the **Cost Insights** card is greyed out | Turn on the switch of the card first. |
| `Cost Insights is not configured yet` in the **Costs** tab of a component, with `Missing or invalid: Account ID, Region` | Click **Open the Cost Insights settings** and fill in **Account ID** and **Region**. |
| `Still waiting for: Account ID, Region` at the top of the settings | Fill in **Account ID** and **Region**, then click **Save**. |
| **Cost Insights**: **Switched on, but not configured yet.** in **Administration › Problems** | Click **Fix it**, then **Configure** on the **Cost Insights** card, fill in **Account ID** and **Region**, and click **Save**. Go back to **Problems** and click **Check again**. |
| **Needs configuration** on the **Cost Insights** card | Click **Configure**, fill in **Account ID** and **Region**, then click **Save**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/cost-insights/turn-on-cost-insights.md -->

# Turn on Cost Insights

Cost Insights shows the cloud costs of your components, read from AWS Cost Explorer. You turn it on,
then you tell Astrolabe which AWS account to read.

## Before you start

You need to be an administrator, and to know the ID of your AWS account and the AWS region of
Cost Explorer (for example `eu-west-1`).

## 🔌 Turn on the plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. On the **Cost Insights** card, click the switch at the top right. It turns on at once.

The card now says **Needs configuration**. Each component now has a **Costs** tab. Until Cost Insights is set up, it says **Cost Insights is
not configured yet**, and **Administration › Problems** lists **Cost Insights** with **Switched on,
but not configured yet.**

## 🔧 Enter the settings

1. On the **Cost Insights** card, click **Configure**.

2. Fill in the fields:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Account ID** | The AWS account whose costs are read | `123456789012` |
   | **Region** | The AWS region of the Cost Explorer endpoint | `eu-west-1` |
   | **Cost metric** | The Cost Explorer metric (optional) | `UnblendedCost` |
   | **Access key ID** and **Secret access key** | Leave both empty to use the credentials of the machine that runs Astrolabe | |

3. Click **Save**. The message **Settings saved.** appears at the bottom left of the screen and goes away by itself. The line at the top changes from **Still waiting for: Account ID, Region** to **This plugin is configured.**

Open a component from **Catalog** and click its **Costs** tab: it opens on **Total cost**, titled **Cloud Cost**, with a **Past 6 Months** button. The figures it shows once AWS answers were not checked on a live instance.

## 🏷️ Link a component to its costs

Add this annotation to the `catalog-info.yaml` of the component, with the AWS tag that marks its
resources:

```yaml
metadata:
  annotations:
    aws.amazon.com/cost-insights-tags: Team=platform-team
```

This step was not checked on a live instance.

✅ That's it!

Next: [Common problems with Cost Insights](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/add-the-dashboard-card.md -->

# Add the Deployments card to your dashboard

The **Deployments** card lists the version deployed on each environment for the components of the
catalog, on **My Dashboards**.

## Before you start

**Deployments** is turned on in **Administration › Plugins**. Until then, the source `astrolabe` is
not offered in **Add a card**. See [Turn on a plugin](../../administration/plugins/turn-on-a-plugin.md).

## What it shows, and to whom

One line per component of the catalog: **Name**, **Owner**, **Mine**, then one column per environment (for example **Production**
and **Staging**) with the version deployed there. **Mine** says **Mine** or **Others**: to keep only
your components, filter on it and save the filter with the card, see
[Keep only your rows](../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

*A card with versions in it was not checked on a live instance.*

A card with nothing to show says **Nothing here yet** and why: **No deployment is recorded yet for a component of the catalog.**
Click **Learn more** under the sentence to come back to this page.

The versions come from the source chosen in the **Deployments** settings: see
[See the versions deployed](see-deployed-versions.md).

## ➕ Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, choose **Source** `astrolabe` and **Key** `Deployments`. The line under the key
   reads **Deployed versions per component by environment**.

4. Type a **Card Name**, for example `Versions per environment`, then click **Add**.

:::tip A card too narrow?
Click **Arrange**, drag the corner at the bottom right of the card to widen it, and click **Done**.
The columns of the environments then show their full name.
:::

✅ That's it!

Next: [Read the versions in Argo CD](read-from-argo-cd.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/faq.md -->

# Frequently asked questions

## We have two Argo CD, one for production and one for the rest. Two sources?

No, one. Connect each Argo CD in **Administration › Company connections**, choose **argocd** once in
the **Deployments** settings: Astrolabe looks in all of them.

## Why does the Deployments card on my dashboard say "Nothing here yet"?

Because no pipeline has reported a deployment for a component of the catalog yet. The card says it word for word: "No deployment is recorded yet for a component of the catalog." Report deployments from your pipelines, see [Report deployments from your pipelines](report-from-pipelines.md), then click **Refresh** in the card menu.

## Why does a component say "Nothing deployed yet"?

Because no pipeline has reported a deployment under the name of this component. The name is the `metadata.name` of its `catalog-info.yaml`: see [Report deployments from your pipelines](report-from-pipelines.md). With Argo CD, the card says what is missing, with the label to add: see [Common problems with Deployments](troubleshooting.md).

## Do I type the list of environments somewhere?

No. The environments are the values of the label you named in **Environment label** (`environment`
by default), as they are written on your Argo CD applications.

## An application has no environment label. What happens?

Astrolabe does not know which column it belongs to, so the **Deployments** card of the component says it: `The Argo CD application shop-pay-recette belongs to shop-pay but appears in no environment. In Argo CD, add the label environment to this application, …`. Add the label and the application appears: see [Common problems with Deployments](troubleshooting.md).

## A component has no application on an environment.

Its cell shows a dash (**—**).

## Is `argocd/app-name` enough?

No: it shows the **Argo CD** tab of the component. For **Deployments**, label your Argo CD applications: see
[Read the versions in Argo CD](read-from-argo-cd.md).

## Do I have to write something in the `catalog-info.yaml` of each component?

No. The **Component label** setting links a component to every Argo CD application that carries this
label with its name: see [Read the versions in Argo CD](read-from-argo-cd.md).

## Who sees the deployments?

Anyone who can open the component. Astrolabe reads Argo CD with the token of the integration, the
same for everyone.

## Does the order matter between the Argo CD integration and the Deployments settings?

No. Either one first.

## Which version is shown when an application runs several images?

The image named after the component (`.../shop-api:2.5.0` for `shop-api`). Without one, the image of
the application's Deployment or StatefulSet.

## Can someone report a deployment from their own session?

No. Only the pipeline token reports a deployment: see
[Report deployments from your pipelines](report-from-pipelines.md).

## Each team has its CI. One token per team?

No, one token for the whole Astrolabe: every CI stores the same in its `ASTROLABE_PIPELINE_TOKEN`
secret. Replacing it means giving the new one to every CI.

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/read-from-argo-cd.md -->

# Read the versions in Argo CD

If Argo CD deploys your applications, Astrolabe reads the version **actually deployed**: the tag of
the component's image, on each environment. Nothing to report from your pipelines, and nothing to write
in the `catalog-info.yaml` of your components.

Several Argo CD (production, the other environments) make **one** source: Astrolabe looks in all of
them.

:::tip Before you start
Connect each Argo CD in **Administration › Company connections**: see
[Add the Argo CD integration](../../getting-started/Configuration/Integration/argocd/add-the-integration.md).
You can do it before or after the steps below.
:::

## 1. ⚙️ Choose Argo CD as the source

1. In the left sidebar, click **Administration**, then **Plugins**.

2. On the **Deployments** card, click **Configure**. The **Settings** tab opens.

3. In **Source**, choose **argocd**. Two fields appear under it:

   | Field | What to write | Left empty |
   | --- | --- | --- |
   | **Component label** | The label of your Argo CD applications whose value is the **name of the component**, for example `app.kubernetes.io/name` | `backstage.io/component` |
   | **Environment label** | The label of your Argo CD applications whose value is the **environment**, for example `env` | `environment` |

   Write a label without spaces or accents.

4. Click **Save**. The message **Settings saved.** appears.

:::tip The screen says "Still waiting for: integrations.argocd"
No Argo CD is connected yet. Add one in **Administration › Company connections**.
:::

## 2. 🏷️ Label your Argo CD applications

Give each Argo CD application of a component two labels: the component label, with the name of the
component as its value, and the environment label, with the name of the environment as its value.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: shop-api-recette
  labels:
    backstage.io/component: shop-api   # the component label: the name of the component
    environment: recette               # the environment label: the name of the column
```

The name of the component is the `metadata.name` of its `catalog-info.yaml`. The value of the
environment label is the name of the column, character for character: `recette` and `Recette` make two
columns.

Nothing else to do: Astrolabe links a component to every application that carries the component label
with its name.

## ✅ Check

Open the component from **Catalog**: the **Deployments** card of the **Overview** shows each environment and its version, for example `recette`
`2.5.0` and `prod` `2.4.0`.

The version is the tag of the image named after the component: `registry.example.com/shop-api:2.5.0`
gives `2.5.0`. A proxy or an agent next to it never wins.

✅ That's it!

## 🔗 Link one component with another label

Most of your components follow the component label of step 1. For one component whose applications carry
another label, add one line to its `catalog-info.yaml`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    argocd/app-selector: team.example.com/app=shop-api
spec:
  type: service
  lifecycle: production
  owner: group:default/platform
```

The selector must contain a label whose value is the name of the component: `team.example.com/app=shop-api`
for the component `shop-api`. A selector that does not name the component links nothing: see
[Common problems with Deployments](troubleshooting.md).

*This annotation was checked only when it is wrong. The case where it links the component was not
checked on an instance.*

Next: [Frequently asked questions](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/report-from-pipelines.md -->

# Report deployments from your pipelines

With the **astrolabe** source, your pipelines tell Astrolabe what they deploy: at the end of each
deployment, one call, and the version shows on the component and on the **Deployments** page. The
pipeline authenticates with a **pipeline token**, which can do nothing but report a deployment.

:::tip Before you start
You need to be an administrator, and **Deployments** must be on: see
[See the versions deployed](see-deployed-versions.md). The source must be **astrolabe** (the default).
If Argo CD deploys your applications, read [Read the versions in Argo CD](read-from-argo-cd.md)
instead: nothing to do in your pipelines.
:::

## 1. 🔑 Generate the pipeline token

1. In the sidebar, click **Administration**, then, under **PLATFORM**, **Plugins**.

2. On the **Deployments** card, click **Configure**.

3. At the top of the page, click the **Pipeline token** tab. It says
   `No pipeline token yet: no pipeline can report a deployment.`

4. Click **Generate a pipeline token**.

5. The token appears in a green box, under
   `Copy this token now and store it as the secret ASTROLABE_PIPELINE_TOKEN of your CI: it will not be shown again.`
   Click **Copy the token**.

## 2. 🔒 Store it in your CI

In your CI (GitLab CI, GitHub Actions, Jenkins…), create a secret variable named
`ASTROLABE_PIPELINE_TOKEN` and paste the token in it. Never write it in a file of your repository.

## 3. 🧩 Check the name of the component

Nothing to add to the catalog: a deployment is attached to the component by its **name**, the `metadata.name` of its `catalog-info.yaml`. For example, for `shop-api`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
spec:
  type: service
  lifecycle: production
  owner: group:default/platform
```

## 4. 🚀 Report a deployment

1. Back on the **Pipeline token** tab, under **Report a deployment from a pipeline**, click
   **Copy the call**. It holds the address of your Astrolabe:

   ```bash
   curl -X POST "https://astrolabe.example.com/api/release-manager/pipeline/projects/$COMPONENT/environments/$ENVIRONMENT" \
     -H "Authorization: Bearer $ASTROLABE_PIPELINE_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"version\": \"$VERSION\", \"deploymentUrl\": \"$CI_JOB_URL\"}"
   ```

2. Paste it at the end of the deployment job of your pipeline, and give it its values:
   - `COMPONENT`: the name of the component in the catalog, for example `shop-api`;
   - `ENVIRONMENT`: the environment, for example `production` or `staging` — it is the name of the
     column;
   - `VERSION`: the version deployed, for example `2.4.0`;
   - `CI_JOB_URL`: the link to the job; GitLab CI gives it under that name. You can leave it out.

3. Run the pipeline. The call answers `201`.

## ✅ Check

1. In the sidebar, click **Deployments**: the row of the component shows the version under its
   environment, for example `2.4.0` under `production`.

2. Back on the **Pipeline token** tab, the token says when it was last used:
   `Last used on 16/10/2026 10:11:21.`

✅ That's it!

## 🔄 Replace or revoke the token

The token has leaked, or someone who knew it has left:

1. On the **Pipeline token** tab, click **Replace the token**.

2. The window **Replace the pipeline token?** says
   `The current token stops working at once: every pipeline that uses it must get the new one.`
   Click **Replace**.

3. Copy the new token and put it in the `ASTROLABE_PIPELINE_TOKEN` secret of each CI.

To stop every pipeline from reporting, click **Revoke the token**, then **Revoke**. The message
`Pipeline token revoked.` appears; nothing is reported until a new token is generated.

:::tip One token for all your pipelines
Astrolabe holds one pipeline token: every CI uses the same. Generating a new one replaces the old one.
:::

Next: [Common problems with Deployments](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/see-deployed-versions.md -->

# See the versions deployed

**Deployments** shows which version of each component runs on each environment: on a page of its
own, and on each component.

## What you see, and for whom

- **Deployments**, in the sidebar: a table with one row per component. It has a **Component** column,
  an **Owner** column, then one column per environment, named after it (for example **production** and
  **staging**). Each environment cell holds the version deployed there, in a green chip. The most
  recent version of the component is a solid chip; an older one is paler. A component that is not
  deployed on an environment shows a dash (**—**).
- On a component: a **Deployments** card on its **Overview** (the version on each environment), and a
  **Deployments** tab with a table (each environment, its version, when it was deployed). The
  timeline is one click away. The card is on the **Overview** of every component: it says **Nothing deployed yet**
  until a pipeline or Argo CD reports a version for it.

Anyone who can open a component sees its deployments. The versions come from the source your
administrator chose: what your pipelines report to Astrolabe — see
[Report deployments from your pipelines](report-from-pipelines.md) — or Argo CD — see
[Read the versions in Argo CD](read-from-argo-cd.md).

## 1. 🔌 Turn on Deployments

You need to be an administrator.

1. In the sidebar, click **Administration**, then, under **PLATFORM**, **Plugins**.

2. On the **Deployments** card, click the switch **in the top right corner of the card** (named
   "Enable Deployments"). It turns on at once, and **Deployments** appears in the sidebar.

## 2. 🔎 Find a component

1. In the sidebar, click **Deployments**.

2. In **Search a component**, type part of its name. Only the rows whose component holds what you
   typed stay. When no row is left, the page says **No results with these filters**: click **Clear
   filters**.

:::tip Narrow the table down
**Filters** (top right) keeps some components, owners or environments. **Select Only My Component(s)**
keeps the components of your teams.
:::

## When nothing has been reported yet

With the **astrolabe** source, the page says **No deployment has been reported yet.** until a pipeline
reports one. An administrator sees the link **Report deployments from your pipelines** under it: it
leads to the **Pipeline token** tab, see [Report deployments from your pipelines](report-from-pipelines.md).
Anyone else reads **An administrator generates the token your pipelines report deployments with.**

## 3. 📦 Look at one component

1. Open the component from **Catalog**.

2. On its **Overview**, the **Deployments** card shows the version on each environment. Click a version
   to open its deployment.

3. Click the **Deployments** tab: the **Table** shows each environment, its version and when it was
   deployed. Click **Timeline** to see the versions one after the other.

✅ That's it!

Next: [Report deployments from your pipelines](report-from-pipelines.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/deployments/troubleshooting.md -->

# Common problems with Deployments

## On a component, or on the Deployments page

| What you see | What to do |
| --- | --- |
| No **Deployments** tab, no **Deployments** card, no key **Deployments** in **Add a card** | Turn on **Deployments** in **Administration › Plugins**. |
| `shop-web shows no Argo CD deployment: its argocd/app-selector annotation ("env=prod") does not contain its name. Remove this annotation to use the label backstage.io/component (the applications that carry backstage.io/component=shop-web), or write: argocd/app-selector: backstage.io/component=shop-web.` in the **Deployments** card of the **Overview** | Remove the `argocd/app-selector` annotation from the `catalog-info.yaml` of the component. The component is then linked to the applications that carry the component label with its name. |
| `The Argo CD application shop-pay-recette belongs to shop-pay but appears in no environment. In Argo CD, add the label environment to this application, with the name of its environment as the value (for example environment=prod). The label to look for is the "Environment label" setting of Administration › Deployments.` in the **Deployments** card of the **Overview** | In Argo CD, add the environment label named in the message to the application named in the message, with the name of its environment as the value, for example `environment: prod`. |
| `No Argo CD application of admin-api was found. In Argo CD, add the label backstage.io/component with the value admin-api to each of its applications. The label to look for is the "Component label" setting of Administration › Deployments.` in the **Deployments** card of the **Overview** | In Argo CD, add the label named in the message, with the name of the component as the value, to each application of the component, for example `backstage.io/component: admin-api`. Check that the label named in the message is the one your applications carry: it is the **Component label** setting of **Administration › Plugins › Deployments**. |
| `Argo CD (argocd-prod) refuses the connection.` | Check the host and port of that Argo CD in **Administration › Company connections**, and that it runs. The other Argo CD keep showing their versions. |
| `Argo CD is not connected to Astrolabe yet.` | Add your Argo CD in **Administration › Company connections**: click **Open the Argo CD integration**. |
| **Nothing here yet** and `No deployment is recorded yet for a component of the catalog.` in the **Deployments** card of **My Dashboards** | No pipeline has reported a deployment yet. Report one: see [Report deployments from your pipelines](report-from-pipelines.md). |
| **Nothing deployed yet** | With Argo CD: read the message above the card, it names the label to add. With a pipeline: no deployment has been reported under the name of the component. |
| `Astrolabe's server failed to answer (503).` | Try again in a moment. If it lasts, tell your company's Astrolabe administrator what you were doing. |
| **No deployment has been reported yet.** on the Deployments page | No pipeline has reported a deployment. As an administrator, click **Report deployments from your pipelines** under the sentence and follow [Report deployments from your pipelines](report-from-pipelines.md). Anyone else asks an administrator: the page says **An administrator generates the token your pipelines report deployments with.** |
| **No results with these filters** on the Deployments page | Clear **Search a component**, or click **Clear filters**. |

## In the Deployments settings

| What you see | What to do |
| --- | --- |
| `"mon env" is not accepted.` under **Environment label** or **Component label** | A label is written without spaces or accents, for example `env` or `app.kubernetes.io/environment`. |
| `Still waiting for: integrations.argocd` | No Argo CD is connected yet: add one in **Administration › Company connections**. |

## When a pipeline reports a deployment

The pipeline's call answers with one of these messages; read them in the log of the job.

| What you see | What to do |
| --- | --- |
| `A pipeline token is required: generate one in Administration › Plugins › Deployments › Configure › Pipeline token and send it as « Authorization: Bearer <token> ».` | The call carries no token. Check that the job sees the `ASTROLABE_PIPELINE_TOKEN` secret (protected branches, environments of your CI), and that the call sends the `Authorization` line. |
| `This pipeline token is not valid: it was replaced or revoked. Generate a new one in Administration › Plugins › Deployments › Configure › Pipeline token.` | The token was replaced or revoked. Generate a new one and put it in the `ASTROLABE_PIPELINE_TOKEN` secret: see [Report deployments from your pipelines](report-from-pipelines.md). |
| `No component named shop-api in the catalog: COMPONENT must be the name of a component of the catalog.` | `COMPONENT` holds a name the catalog doesn't know. Use the name of the component, as in `metadata.name` of its `catalog-info.yaml`. |
| `version is required` | `VERSION` is empty in the job: give it the version deployed. |
| The call succeeds but the component shows **Nothing deployed yet** | Check that `COMPONENT` is the name of the component, as in `metadata.name` of its `catalog-info.yaml`, and that you look at the same environment. |

## When you add an Argo CD

| What you see | What to do |
| --- | --- |
| `argocd.example.com refused the credentials (401). Check the token, and that it has not expired.` | Create a new Argo CD API token: see [Create an Argo CD API token](../../getting-started/Configuration/Integration/argocd/create-a-token.md). |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/groups/change-or-delete-a-group.md -->

# Change or delete a group

You are an administrator.

## Change a group

1. In **Administration**, under **SECURITY**, click **Groups**.
2. At the end of the row of the group, click the pencil (**Edit group**).
3. In the window **Edit group**, change the **Title**, the **Description**, the **Parent group** or the
   **Members**. To remove a member, click the cross on its chip. The **Name** is greyed out: it
   never changes.
4. Click **Save**.

:::tip
The group **astrolabe-administrators** is in the list from the start: its members are the
administrators. See [Give administrator rights to someone](../../administration/access-control/give-administrator-rights.md).
Its bin is greyed out: this group cannot be deleted.
:::

## Delete a group

1. At the end of the row of the group, click the red bin (**Delete group**).
2. In the window **Delete this group?**, read **The group acme-team will leave the catalog, and its
   members will lose the roles it gives.**
3. Click **Delete**.

✅ That's it!

Next: [Groups FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/groups/create-a-group.md -->

# Create a group

You are an administrator. A group lists people, owns components and receives roles. You create it
once; it then appears in the catalog.

## Create it

1. In the left sidebar, at the bottom, click **Administration**.
2. In the menu on the left, under **SECURITY**, click **Groups**.
3. At the top right, click **Add group**.
4. In the window **Add group**, fill in:

| Field | What to write | Example |
| --- | --- | --- |
| **Name** | Lowercase letters, digits and dashes (required). It cannot change once created | `acme-team` |
| **Title** | The name shown to everyone | `Acme team` |
| **Description** | What the team does | `The Acme platform team` |
| **Parent group** | The group above it. Leave **No parent** for a top-level group | `No parent` |
| **Members** | Click the field, pick a person, and repeat for each one | `Jane Doe (user:default/jane.doe)` |

5. Click **Create**.

A message says **Group created. It reaches the catalog in a few seconds.** The list shows the group
with its **Name**, **Title**, **Parent group** and **Members**.

In **Catalog › Groups**, the group appears under its **Title**: see
[See a group and its members](see-a-group.md).

✅ That's it!

Next: [Change or delete a group](change-or-delete-a-group.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/groups/faq.md -->

# Groups FAQ

## What is a group for?

It lists people, it owns components, and it receives roles. In the catalog, the **Owner** of a
component is a group.

## Where do I see the groups?

Everyone sees them in **Catalog › Groups**. Administrators create and change them in **Administration ›
Groups**.

## Can I change the name of a group?

No. The **Name** cannot change once the group is created. Change its **Title** instead, or delete the
group and create it again.

---

<!-- https://doc.forgeit.fr/docs/core-features/groups/see-a-group.md -->

# See a group and its members

A group is a team. Its page lists its members and everything it owns: components, APIs, databases.

## Open a group

1. In the left sidebar, click **Catalog**.
2. Above the list, click the **Groups** tab.
3. Click the name of the group, for example `platform-team`.

## What the page shows

| Where | What |
| --- | --- |
| **Ownership** card | A tile per kind of thing the group owns, with a number: for example **4 SERVICES**, **2 DATABASES**. Click a tile to list them in the catalog |
| **Include indirect ownership** | Switch it on to include what is owned indirectly, through other groups |
| **… members** card | The people of the group, with their email address. Type in **Search members…** to find one |
| **About** card | Its description, its type, its owner |
| Card with the group name | Its **Entity Ref**, its **Parent Group** and its **Child Groups** (**N/A** when it has none) |

4. In the **members** card, click the name of a person to open their page.

:::tip Follow a team
Next to the name of the group, click the eye (**Watch**) to hear of what happens to it, and the star
to put it in your favorites.
:::

✅ That's it!

Next: [Create a group](create-a-group.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/groups/troubleshooting.md -->

# Common problems with groups

| What you see | What to do |
| --- | --- |
| `Use lowercase letters, digits and dashes only (63 characters at most).` under **Name** | Write the name with lowercase letters, digits and dashes, for example `acme-team`. |
| **No group yet. Groups own components and receive roles.** in **Administration › Groups** | No group was created here yet. Click **Add group**. |
| The group you just created is not in **Catalog › Groups** | Wait a few seconds: **Group created. It reaches the catalog in a few seconds.** Then open the catalog again. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/choose-language-and-theme.md -->

# Choose your language and your theme

Astrolabe speaks English and French, and comes in a light and a dark theme. You choose both from the
menu of your avatar.

Astrolabe first opens in the language of your browser: in French if your browser is set to French,
in English if it is set to English. The choice you make in the menu comes first, and Astrolabe keeps
it on this browser.

## Switch the language

1. At the top right of any page, click your avatar.
2. Next to **Language**, click **FR** for French, or **EN** for English.

The whole interface changes at once: the sidebar, the menus, the pages.

## Switch the theme

1. At the top right of any page, click your avatar.
2. Next to **Theme**, click the moon (**Dark mode**) or the sun (**Light mode**).

The theme changes at once. The menu closes.

✅ That's it!

Next: [Connect your own accounts](connect-my-accounts.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/connect-my-accounts.md -->

# Connect your own accounts

Some cards of your dashboard show your own work: your issues, your pull requests. They read it with
**your** account on the tool, not with the company's. You connect it once, from **My Account**.

## Open the list

1. At the top right of any page, click your avatar, then **My Account**.
2. Open the **My accounts** tab.

Each tool your company connected has a card with its state: **Connected**, **Not connected**,
**Token refused** or **Not verified**. **Connect** adds your token, **Configure** changes or deletes
it.

When your company connected none of GitHub, GitLab, Jira or Azure DevOps, the tab says: **No source
to connect yet: your administrator has not configured GitHub, GitLab, Jira or Azure DevOps.** Ask
your Astrolabe administrator to connect them.

The step by step, tool by tool, is in
[The company's token and your own account](../../getting-started/Configuration/Integration/company-token-and-my-account.md).

✅ That's it!

Next: [See your achievements](see-my-achievements.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/faq.md -->

# My account FAQ

## Where do I change my language?

In the menu of your avatar, next to **Language**: see
[Choose your language and your theme](choose-language-and-theme.md). It is not in **My Account**.

## Why does Astrolabe open in another language on another computer?

Because your choice is kept on the browser where you made it. On another browser, Astrolabe opens in
the language of that browser: pick yours again in the menu of your avatar.

## Where do I change my name or my email address?

The **Profile** tab shows them but does not let you change them here.

## What is the difference between the company's token and my account?

The company's token serves the pages of the components. Your own account serves the cards of your
dashboard that show your own work. See
[The company's token and your own account](../../getting-started/Configuration/Integration/company-token-and-my-account.md).

## How do I stop the achievement messages?

Switch off **When you unlock an achievement** in **My Account › Notifications**.

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/open-my-account.md -->

# Open your account

Your account page holds your profile, your own connections, your notifications and your achievements.

## Open it

1. At the top right of any page, click your avatar (a round button with your initial).
2. In the menu, click **My Account**.

The page opens on the **Profile** tab: your name and your email address.

## The tabs

| Tab | What it holds |
| --- | --- |
| **Profile** | Your name and your email address |
| **My accounts** | Your own accounts on GitHub, GitLab, Jira and Azure DevOps: see [Connect your own accounts](connect-my-accounts.md) |
| **Notifications** | What you want to be told, and where: see [Choose your notifications](../../developer-dashboard/notifications/choose-your-notifications.md) |
| **Achievements** | Your level and the achievements you unlocked: see [See your achievements](see-my-achievements.md) |

The same menu of your avatar holds your language and your theme: see
[Choose your language and your theme](choose-language-and-theme.md).

✅ That's it!

Next: [Choose your language and your theme](choose-language-and-theme.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/see-my-achievements.md -->

# See your achievements

Astrolabe rewards what you do with it. Each reward is an achievement, and each achievement earns
points that raise your level.

## Open them

1. At the top right of any page, click your avatar, then **My Account**.
2. Open the **Achievements** tab.

The top of the page shows your level, for example **Level 2 — Apprentice**, your points (**50 / 150
XP**) and how many you unlocked (**5 / 35 achievements unlocked**). Your level also shows in the
menu of your avatar.

Below, the achievements are grouped by theme: **Exploration**, **Catalogue**, **The Foundry**,
**Compass**, **Chronicles**, **Guild**, **Sentinel**, **Dashboard**, **Release Manager**,
**Administration**, **Secrets** and **Legends**. Next to each theme, a counter such as `3/5` says how
many you unlocked.

- An unlocked achievement shows its picture and its name.
- A locked one shows a padlock.
- Under each name, **IRON**, **STEEL**, **MITHRIL** or **STELLAR** is its rank.
- The achievements of **Secrets** read **Hidden achievement** until you unlock them.

## When you unlock one

A message **Achievement unlocked!** appears at the bottom left of the screen, and goes away by itself after a few seconds. It shows the name of the
achievement and the points you win (**+10 Forge Shards**). The bell also gets a notification
**Achievement unlocked: …**.

Click the message, or the notification in the bell, and Astrolabe opens the **Achievements** tab of
**My Account** with the achievement you just unlocked in front.

To stop these notifications, see [Choose your notifications](../../developer-dashboard/notifications/choose-your-notifications.md):
the **Achievements** section has a switch **When you unlock an achievement**.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/core-features/my-account/troubleshooting.md -->

# Common problems with My Account

| What you see | What to do |
| --- | --- |
| **No source to connect yet: your administrator has not configured GitHub, GitLab, Jira or Azure DevOps.** in **My accounts** | Ask your Astrolabe administrator to connect the tools. |
| **This browser refused notifications; allow them in its settings first.** in **Notifications** | Allow notifications for Astrolabe in the site settings of your browser, then reload the page. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/polaris/ask-polaris.md -->

# Ask Polaris a question

Ask Polaris a question, and come back to your conversations later.

## Before you start

An administrator has [turned on Polaris](turn-on-polaris.md).

## 💬 Ask a question

1. In the left sidebar, click **Polaris**.

2. In the field **Your question**, type your question, for example `How do I deploy shop-api?`.

3. Click **Send**.

The conversation appears in the list on the left, under the **New conversation** button. This step was not
checked against a working AI server: what the answer looks like was not seen.

## ➕ Start another conversation

Click **New conversation**, then ask your question.

✅ That's it!

Next: [Common problems with Polaris](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/polaris/troubleshooting.md -->

# Common problems with Polaris

| What you see | What to do |
| --- | --- |
| No **Polaris** in the left sidebar | An administrator turns on **Enable Polaris** in **Administration › Plugins**: [Turn on Polaris](turn-on-polaris.md). |
| On the Polaris page: `Polaris is not configured yet` `This plugin is running but has nothing to show until it is configured from the administration.` `Missing or invalid: IP address, Token` | Click **Open the Polaris settings**, fill in **IP address** and **Token**, click **Save**, then **Reload**. |
| A message `Polaris could not answer. Try again in a moment.` and your question back in the field | Polaris cannot reach its AI server. Try again in a moment. If it keeps happening, ask your administrator to check **IP address** and **Token** in **Administration › Plugins › Polaris › Configure**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/polaris/turn-on-polaris.md -->

# Turn on Polaris

Polaris is the conversational assistant of Astrolabe. It has a page of its own, where each user asks
questions and keeps their conversations.

You set it up once, as an administrator.

## Before you start

Polaris answers through an AI server. You need its address, and the bearer token that server expects.

## 🔌 Turn on the plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. On the **Polaris** card, click the switch **Enable Polaris**. The card now says **Needs configuration**,
   and **Polaris** appears in the left sidebar.

## 🔧 Give Polaris its AI server

1. On the **Polaris** card, click **Configure**. The **Settings** page opens. It says **Still waiting for:
   IP address, Token**.

2. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **IP address** | The host of the AI server, without `http://` or `https://`. Astrolabe pastes it into `https://<host>:8443`. An address or a name. | `ai.example.com` |
   | **Token** | The bearer token the AI server expects. It stays in Astrolabe: the browser never talks to the AI server. | |

3. Click **Save**. The message **Settings saved.** appears at the bottom left of the screen and goes away by itself. The page says **The configuration has changed.**

4. Click **Reload**. The page says **This plugin is configured.**

✅ That's it!

Next: [Ask Polaris a question](ask-polaris.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/search/faq.md -->

# Search FAQ

## Is there a shortcut to open the search?

No: click **Search** in the left sidebar.

## Does the search look inside the documentation of a component?

Yes, even if nobody has opened that documentation yet: Astrolabe builds it in the background. A
documentation that does not build is not searched, and
**Administration › Problems** says it: see [Common problems with
Confluence](../../getting-started/Configuration/Integration/confluence/troubleshooting.md). To read
the documentation of a component, see
[Read the documentation of a component](../techdocs/read-component-docs.md).

## Does the search look inside Confluence?

Yes, once Confluence is connected: see
[Add the Confluence integration](../../getting-started/Configuration/Integration/confluence/add-the-integration.md).

## Where is the difference with **Search by name** in the catalog?

**Search by name** (in the [catalog](../catalog/filter-the-catalog.md)) only looks at names, in one
kind of thing at a time. **Search** looks at names and descriptions, in every kind at once.

## Why does the search find nothing on a new instance?

Because the search index takes a few minutes to build. The page says it: **On a new instance, the search index can take a few minutes to build.** Wait, then search again.

## Why does a component I know not show up?

Its name and its description hold none of your words, or a filter is on. Open **Filters**, pick
**All** under **Kind** and untick **Lifecycle**.

---

<!-- https://doc.forgeit.fr/docs/core-features/search/search-astrolabe.md -->

# Search Astrolabe

One search field for the whole catalog. Type a word and open what you find.

## Search

1. In the left sidebar, click **Search**.
2. Click in the search field at the top of the page (it reads **Search in** followed by the name of
   your company) and type a word, for example `payment`.

The list updates as you type. Each result shows its name, its description and chips: its kind
(**Component**, **API**, **System**, **Group**, **User**, **Template**, **Resource**, **Domain**)
and its type or lifecycle.

3. Click a result to open its page.

At the bottom of the list, **Previous** and **Next** move between pages of results.

:::tip What is searched
The name **and** the description. `gestion` finds a component whose description says "Service de
gestion des commandes", even if its name does not hold the word.
:::

## Documentation and Confluence pages are found too

The search also reads the documentation of your components, and the pages of Confluence once it is
[connected](../../getting-started/Configuration/Integration/confluence/add-the-integration.md). The
documentation of a component is found **even if nobody has opened it yet**: Astrolabe builds it in
the background, so you do not have to open a documentation page first for its words to be searched.

Type a word of the documentation: the result is the page of the documentation that holds it. A
Confluence page shows its space (for example **Space ENG**) and opens on your Confluence, in a new
window.

:::note
Searching the words of a component's documentation was not tried on an instance with a real
documentation; the Confluence pages were.
:::

## Keep one kind of result

1. At the top right, click **Filters**.
2. Under **Kind**, click **All** and pick **Component**, **Template**, **User** or **Group**.
3. Under **Lifecycle**, tick **production** or **experimental** to keep only the things in that
   phase.
4. Click **Close**.

Untick the box, or pick **All** again, to remove a filter.

✅ That's it!

Next: [Search FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/search/troubleshooting.md -->

# Common problems with search

| What you see | What to do |
| --- | --- |
| **We couldn't find a match** and **Try adjusting your search terms or filters.** | No name or description holds your word, or a filter is on. Try a shorter word, then open **Filters** and pick **All** under **Kind**. |
| **We couldn't find a match**, **Try adjusting your search terms or filters.** and **On a new instance, the search index can take a few minutes to build.** | Your Astrolabe is new and the search has not finished listing the catalog. Wait a few minutes, then search again. |
| **We couldn't find a match** for a word of a Confluence page or of a component's documentation | Open **Filters** and pick **All** under **Kind**. Then see [Common problems with Confluence](../../getting-started/Configuration/Integration/confluence/troubleshooting.md). |
| The page lists everything before you type | That is normal: with an empty field, the search lists the catalog. Type a word to narrow it. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/tech-atlas/add-entries.md -->

# Add entries to the radar

An entry is one technology on the radar: a library, a platform, a practice, a tool.

## Before you start

You need to be an administrator, and the rings exist ([Turn on Tech Atlas](turn-on-tech-atlas.md)).

## ➕ Add an entry

1. In **Administration**, under **INTELLIGENCE**, click **Tech Atlas**. The **Entries** tab opens.

2. Click **Add Entry**.

3. Fill in the form:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Title** | The name shown on the radar | `React Query` |
   | **Key** | A short identifier, in `snake_case` | `react_query` |
   | **Quadrant** | Where it sits | `Languages & Frameworks` |
   | **Ring** | Its recommendation today | `Adopt` |
   | **URL** | A page to learn more | `https://example.com/react-query` |
   | **Description** | Why you recommend it | `Our way to fetch data in the browser.` |

4. Click **Add**. The entry is in the table, with its **Current Ring** and **Last Updated**.

The **Quadrant** and **Ring** lists above the table keep the entries you want to see.

## 🕒 Move an entry to another ring

An entry keeps a history: each change of ring is a **snapshot**.

1. On the row of the entry, click the clock icon (**Manage timeline for** the entry). The window
   **Timeline** lists the snapshots.

2. Click **Add snapshot**.

3. Choose the new **Ring**, the **Date**, and the **Movement** (**Moved out**, **No change** or
   **Moved in**). Add a **Description** if you want to say why.

4. Click **Confirm**. **Snapshot added** appears, and the radar shows the entry in its new ring.

✅ That's it!

Next: [Read the radar](read-the-radar.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/tech-atlas/faq.md -->

# Frequently asked questions

## Can I add a fifth quadrant or delete one?

No. A radar has exactly four quadrants. You can rename them on the **Quadrants** tab of **Administration › Tech Atlas**.

## Where do the entries come from?

From **Administration › Tech Atlas › Entries**, where you add them by hand. The **Settings** tab
also offers a second **Data source**, `url`, to read the entries from a published document: type
its address in **URL**, then click **Save**.

## What does Run discovery do?

It reads the repositories of your components to find the technologies they use. It needs an
integration for the host of your repositories.

## Can I add or move an entry from the radar?

No. The radar only reads: click an entry to see its description and its **History**. Entries are
added and moved in **Administration › Tech Atlas**, by administrators.

## Who sees the radar?

The radar is the **Tech Atlas** page in the left sidebar. Its settings, rings and entries are in
**Administration › Tech Atlas**.

---

<!-- https://doc.forgeit.fr/docs/core-features/tech-atlas/read-the-radar.md -->

# Read the radar

The radar shows every technology your administrators placed on it, so you know what to start with
and what to leave.

## Before you start

Tech Atlas is on and has entries ([Turn on Tech Atlas](turn-on-tech-atlas.md)).

## 🛰️ Open the radar

1. In the left sidebar, click **Tech Atlas**. The page is titled **Forge Atlas**.

2. The four quadrants (**Techniques**, **Tools**, **Platforms**, **Languages & Frameworks**) each
   list their entries by ring, from the centre (**Adopt**) outwards (**Hold**). A ring with nothing
   in it says **(empty)**. Each entry has a number, the same as its dot on the radar.

3. Under the radar, the legend gives each ring its meaning, as written by your administrators.

4. Click an entry. A window opens with its description, its **History** (**Moved to ring**,
   **Moved on date**) and a **LEARN MORE** link to its page.

5. Type in **Filter**, at the top right, to find an entry.

✅ That's it!

Next: [Frequently asked questions](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/tech-atlas/troubleshooting.md -->

# Common problems with Tech Atlas

| What you see | What to do |
| --- | --- |
| No **Tech Atlas** in the left sidebar | Turn on **Tech Atlas** in **Administration › Plugins**. |
| `No integration can read your components' repositories (github.com). Add one for this host in Administration › Company connections.` after **Run discovery** | Add the integration of the host named in the message (here GitHub) in **Administration › Company connections**, then click **Run discovery** again. |
| `Tech Atlas is on, but your catalog has no repository to read yet. Add a provider in Administration › Catalog › Providers, then run the discovery from the Entries tab.` after turning Tech Atlas on | Add a catalog provider in **Administration › Catalog**, then click **Run discovery** on the **Entries** tab of **Administration › Tech Atlas**. |
| `Tech Atlas is on, but no integration is set for github.com. Add one in Administration › Company connections, then run the discovery from the Entries tab.` after turning Tech Atlas on | Add the integration of the host named in the message in **Administration › Company connections**, then click **Run discovery**. |
| `Discovery failed: no repository could be read (github.com). Check the integration's token in Administration › Company connections. Nothing was changed.` | The token of the integration is refused or expired: replace it in **Administration › Company connections**, then click **Run discovery**. |
| `Tech Atlas is on, but you are not allowed to run the discovery. Ask an administrator.` | Your role cannot run the discovery. Ask an administrator to click **Run discovery**. |
| `Discovery failed. Nothing was changed. Run it again from the Entries tab.` | Click **Run discovery** on the **Entries** tab of **Administration › Tech Atlas**. |
| `No rings configured yet.` on the **Rings** tab | Click **Add Ring** and create at least one ring. |
| `No entries found.` on the **Entries** tab | Click **Add Entry**. |
| Every ring of the radar says **(empty)** | No entry was added yet: add entries in **Administration › Tech Atlas**. |

---

<!-- https://doc.forgeit.fr/docs/core-features/tech-atlas/turn-on-tech-atlas.md -->

# Turn on Tech Atlas

Tech Atlas is a technology radar: one page that tells everyone which languages, platforms, techniques
and tools your company recommends. You turn it on, then you create the **rings** (the levels of
recommendation).

## Before you start

You need to be an administrator.

## 🔌 Turn on the plugin

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Plugins**.

3. On the **Tech Atlas** card, click the switch at the top right. It turns on at once. Already on? Tech Atlas is on: go to the next step.

**Tech Atlas** appears in the left sidebar, and in the Administration menu under **INTELLIGENCE**.

A first discovery starts at once, without you asking: it reads the repositories of your catalog to find
the technologies they use. Above the cards of **Plugins**, the page says **Discovery is running: the
repositories of your catalog are being read. This page reloads when it is done.** Then, in a few
seconds, for example **Discovery done: 17 repositories read, 10 added, 0 moved.** The entries found are
in **Administration › Tech Atlas**, on the **Entries** tab. You can run the discovery again there with
**Run discovery**.

## ⭕ Create the rings

A new radar has no ring: the list **Ring** of an entry offers the rings you create here.

1. In **Administration**, under **INTELLIGENCE**, click **Tech Atlas**, then the **Rings** tab.

2. Click **Add Ring**.

3. Fill in the form:

   | Field | What to write | Example |
   | --- | --- | --- |
   | **Name** | The name of the ring | `Adopt` |
   | **Position (1 = centre)** | 1 is the centre of the radar | `1` |
   | **Color** | A colour, as `#rrggbb` | `#0ea586` |
   | **Description** | What the ring means | `Use it by default.` |

4. Click **Add**. **Ring created successfully** appears.

5. Repeat for the other rings, for example `Trial` (2), `Assess` (3) and `Hold` (4).

:::tip The four quadrants
The radar has exactly four quadrants: **Languages & Frameworks**, **Platforms**, **Techniques**,
**Tools**. They cannot be created or deleted. On the **Quadrants** tab, you can rename them.
:::

✅ That's it!

Next: [Add entries to the radar](add-entries.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/techdocs/add-docs-to-a-component.md -->

# Add documentation to a component

A component without documentation says so on its **Docs** tab. One annotation in its
`catalog-info.yaml` file connects it to the documentation in its repository.

## Before you start

- The component is in the catalog.
- Its repository holds a `mkdocs.yml` file and a `docs` folder.

## Add the annotation

1. In the repository of the component, open `catalog-info.yaml`.
2. Under `metadata`, add the annotation `backstage.io/techdocs-ref`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  owner: platform-team
```

3. Save and push the file.

Once Astrolabe has read the file again, the **Docs** tab of the component shows
the documentation, and the component appears in the **Documentation** page.

This step was not checked on a live instance.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/core-features/techdocs/faq.md -->

# Documentation FAQ

## Why is my component not in the **Documentation** page?

Only the components that carry the `backstage.io/techdocs-ref` annotation are listed. See
[Add documentation to a component](add-docs-to-a-component.md).

## Where do I find the documentation of one component?

On the page of the component, in the **Docs** tab. In the **About** card, **View TechDocs** opens the
same documentation.

## Can I search the documentation?

The **Search** of the left sidebar lists catalog things, not the pages of a documentation: see
[Search FAQ](../search/faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/techdocs/read-component-docs.md -->

# Read the documentation of a component

The documentation of a component lives next to its code. You read it in Astrolabe, with the page
list on the left and the outline on the right.

## From the Documentation page

1. In the left sidebar, click **Documentation**.

The page lists the components that have documentation: **Document**, **Owner**, **Kind**, **Type**
and **Actions**.

2. Click the name of a document, for example `customer-portal`.

The documentation opens. At the top you see the **Component**, its **Owner** and its **Lifecycle**:
click the component to open its page. Below:

| Where | What |
| --- | --- |
| Left | The pages of the documentation. Click one to open it |
| Middle | The page you read |
| Right, **Table of contents** | The headings of the page. Click one to jump to it |

:::tip A banner says a newer version is available
**A newer version of this documentation is now available, please refresh to view.** Click
**Refresh**: the page reloads with the latest version.
:::

## From the component

1. In the left sidebar, click **Catalog** and open the component.
2. Click the **Docs** tab. Or, in the **About** card, click **View TechDocs**.

## Find a document in the list

1. On the **Documentation** page, click **Filters**.
2. In the **Personal** block, click **Starred** to keep the documentation of your favorite
   components. Or pick a value in **Owner** or **Tags**.
3. Click **Close**.

In the **Actions** column, the first button copies the link of the documentation, the second adds it
to your favorites.

✅ That's it!

Next: [Add documentation to a component](add-docs-to-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/techdocs/troubleshooting.md -->

# Common problems with the documentation

| What you see | What to do |
| --- | --- |
| **Missing Annotation**, then `The annotation backstage.io/techdocs-ref is missing. You need to add it to your Component if you want to enable this tool.` on the **Docs** tab | The component has no documentation yet. Add the annotation: see [Add documentation to a component](add-docs-to-a-component.md). The screen shows the YAML to copy. |
| **A newer version of this documentation is now available, please refresh to view.** | Click **Refresh**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/core-features/the-foundry/create-a-component.md -->

# Create a component from a template

A template is a ready-made starting point: a documentation site, a Node.js service, a Python API.
You pick one, answer a few questions, and Astrolabe creates the component for you.

## Pick a template

1. In the left sidebar, click **The Foundry**.

The **Templates** tab shows one card per template: its category, its title, its description, its
tags and its owner.

2. To narrow the list, click **Filters** (top right). In the panel, click **Starred** to keep your
   favorite templates, or pick a value in **Categories**, **Tags** or **Owner**. Click **Close**.
3. On the card of the template you want, click **Choose**.

## Fill in the form

The form is split into steps, shown at the top. Example with the **Component Sandbox** template,
which generates the files of a component without publishing them anywhere: one step,
**Component Information**.

1. Fill in:

| Field | What to write | Example |
| --- | --- | --- |
| **Component Name** | The name of the new component | `acme-sandbox` |
| **Description** | A short description | `Sandbox for acme` |
| **Owner** | The team or user who owns it. Click the field and pick one | `platform-team` |

2. Click **Review**. In the table, check your answers. Click **Back** to change one.
3. Click **Create**.

Astrolabe opens the page of the task and runs its steps: see
[Follow the creation of a component](follow-a-task.md).

:::tip Each template has its own form
The questions, and the steps, change from one template to another. A template with several steps
has a **Next** button between them.
:::

✅ That's it!

Next: [Follow the creation of a component](follow-a-task.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/the-foundry/faq.md -->

# The Foundry FAQ

## Where do I see all the templates?

In **The Foundry**, or in the **Templates** tab of the [catalog](../catalog/browse-the-catalog.md).

## What are the **Editor**, **Actions** and **Templating Extensions** tabs?

They are for the people who write templates: **Editor** loads or creates a template to try it, **Actions** lists what a template can do, **Templating Extensions** lists the helpers it can use. To create a component, stay in the **Templates** tab.

## Why do the template cards have no **Choose** button?

Your role does not let you create components. You can read the templates, but not start one. Ask
your administrator to give your role `scaffolder.task.create`.

## Why does the **Tasks** tab say `Error: Request failed with 403 Forbidden`?

Your role does not let you read tasks. Ask your administrator to give your role
`scaffolder.task.read`.

## Can I start again with the same answers?

Yes: on the page of the task, click **Start Over**. The form opens with your answers already filled in.

---

<!-- https://doc.forgeit.fr/docs/core-features/the-foundry/follow-a-task.md -->

# Follow the creation of a component

When you click **Create**, Astrolabe runs the steps of the template one after the other. You watch
them on the page of the task.

## Watch the steps

The page shows the steps of the template, for example **Generate the Files** and **List the Files** for **Component Sandbox**, or **Fetch Base Template**, **Publish to GitHub**
and **Register Component**. Each has an icon: a step that fails turns red, the steps after it are
skipped.

Under the steps, the log lists what each step did. The buttons at the top right:

| Button | What it does |
| --- | --- |
| **Hide Logs** | Hides the log under the steps |
| **Start Over** | Opens the form again, with your answers already filled in |
| **Cancel** | Greyed out when the task is over |

In the log, the search field filters the lines, and the arrow beside it downloads the log.

## When the creation succeeds

Each step ends with a green check mark, and the bar above the steps turns green. Under the steps, a
block shows the result of the template, with a title the template chose (for example **Files
generated**). **Cancel** is greyed out and **Start Over** stays available. In the **Tasks** tab, the
**Status** of the task reads **Completed**.

The links that a template can show in that block, such as **Repository** or **Open in Catalog**,
were not checked on a live instance.

## When the creation fails

The failed step turns red, and a red message appears under the steps. It starts with **The template
did not finish**, then names the step and says what went wrong. The log under it keeps the details.
The messages are listed in [Common problems with The Foundry](troubleshooting.md).

## Find your past creations

1. In **The Foundry**, click the **Tasks** tab.

The table lists each task: **Task ID**, **Template**, **Created**, **Owner** and **Status**
(for example **Failed**). Click a **Task ID** to reopen its page.

At the bottom, **Show 20 results** changes how many tasks one page shows.

✅ That's it!

Next: [The Foundry FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/core-features/the-foundry/troubleshooting.md -->

# Common problems with The Foundry

| What you see | What to do |
| --- | --- |
| **Please fill out this field.** when you click **Next** | Fill in the field marked with a star (`*`). |
| A red message starts with **The template did not finish** and says `could not find a file that the template needs` | The template points at files that do not exist. Tell the owner of the template (shown on its card) to fix its source. |
| The red message says `was not allowed to read or write a file` | Ask your administrator to check the permissions of the server. |
| The red message says `could not reach` followed by an address | Check that the address is right and that the service answers, then click **Start Over**. |
| The red message says `was refused by the service it publishes to: the connection is missing or its token is no longer valid` | Ask an administrator to fix the connection in **Administration › Company connections**, then click **Start Over**. |
| The red message says `was not given what it expects: the template is wrongly written` | Tell the owner of the template (shown on its card) to fix it. |
| The red message says `failed. The log below tells what happened; share it with your administrator` | Read the log of the red step, then send the **Task ID** and the red lines to your administrator. |
| A step is red, and the next ones read `Skipping step … because a previous step failed` | Read the log of the red step: it says what failed. Fix it, then click **Start Over**. |
| The **Tasks** table shows **Failed** in **Status** | Click the task to read its log. |
| No **Choose** button on the cards of the **Templates** tab | Your role does not let you create components. Ask your administrator: see the [FAQ](faq.md). |
| `Error: Request failed with 403 Forbidden` in the **Tasks** tab | Your role does not let you read tasks. Ask your administrator: see the [FAQ](faq.md). |

:::tip Still stuck?
Write to **support@forgeit.fr** with the **Task ID**.
:::

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/add-a-card.md -->

# Add a card

A card shows one thing from one source on your dashboard: your merge requests, your pipelines, the
Compass scores of your components. You choose the source and what it shows.

## Before you start

Your role must allow it. Without it, **Add a card** shows a padlock. Hover it: the tooltip says **Your role can't add cards to dashboards. Ask an administrator.** Ask your administrator to give your role the **Orion-dashboard** permissions `dashboard.create`, `dashboard.update`, `dashboard.card.create`, `dashboard.card.update` and `dashboard.card.delete`
([Check what a role gives](../../administration/access-control/check-what-a-role-gives.md)).

A source other than **astrolabe** needs a connection that your administrator added in
**Administration › Company connections**: see for example
[Add the GitLab integration](../../getting-started/Configuration/Integration/gitlab/add-the-integration.md).

The source **astrolabe** is offered only when a plugin it serves is on in **Administration › Plugins**:
**Deployments** gives the key **Deployments**, **Compass** gives the key **Compass**. With both off,
**astrolabe** is not in the list; with one on, only its key is.

## 🔧 Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page next to **Arrange** and **Fullscreen**. On an empty
   dashboard, the same button is in the middle of the page.

3. In the window **Add a card**, fill in the form:

   | Field | What to choose | Example |
   | --- | --- | --- |
   | **Source** | Where the data comes from: `astrolabe`, `github`, `gitlab`, `jira`… | `astrolabe` |
   | **Key** | What the card shows. A line under the field says what. | `Compass` |
   | **Card Name** | The title of the card (required) | `Scores` |
   | **In dashboard** | The dashboard that receives the card. It starts on the dashboard you are looking at. | `Delivery` |

4. Click **Add**.

Nothing to save afterwards. When you chose another dashboard than the one you are looking at, a
message says **Card added to « Delivery »**, with a button **Open** that takes you there.

| Source | Keys |
| --- | --- |
| `astrolabe` | **Deployments** (the versions deployed on each environment), **Compass** (the scores of each component) |
| `github` | **Pull Requests**, **Workflows**, **Releases**, **Detailed Workflows** |
| `gitlab` | **Merge Requests**, **Pipelines**, **Releases**, **Detailed Pipelines**, **To-Do List** |
| `jira` | **To Review**, **My Open Issues**, **JQL Query** |

## 👀 What a card shows, and how to keep only yours

A card reads **everything that your account can see** among the components of the catalog, not only
what is yours: every pull request of a repository of the catalog that your token reads, every
application, every build. Some tables carry a column that says which rows are yours (**My role**,
**Mine**), and you can **filter** on it and save the filter with the card: see
[Change or remove a card](change-or-remove-a-card.md#-keep-only-your-rows).

The cards of each tool have their own page: for example
[Add the GitHub cards to your dashboard](../../getting-started/Configuration/Integration/github/add-the-dashboard-cards.md),
[Add the GitLab cards to your dashboard](../../getting-started/Configuration/Integration/gitlab/add-the-dashboard-cards.md),
[Add the Argo CD card](../../getting-started/Configuration/Integration/argocd/add-the-dashboard-card.md),
[Add the Jira cards](../../getting-started/Configuration/Integration/jira/add-the-dashboard-cards.md).

✅ That's it!

Next: [Arrange your cards](arrange-your-cards.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/arrange-your-cards.md -->

# Arrange your cards

Put the cards where you want them, as big as you want, and split a dashboard that became too long.

## 🔧 Move and resize

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard.

2. Click **Arrange**, at the top of the page (a dashboard with no card does not offer it). The tabs are greyed out, **Cancel** and **Done** replace
   the buttons, and the page says: **Drag the cards to move them, pull a corner to resize them. Tick
   cards to move them to another dashboard.**

3. To move a card, drag it by its title to its new place.

4. To resize a card, drag the bottom right corner of the card.

5. Click **Done**. The message **Saved successfully** appears. **Cancel** gives you back the layout you had before **Arrange**.

Your layout is kept: it is the same next time you open the dashboard.

## 📦 Move cards to another dashboard

1. Click **Arrange**.

2. On each card to move, tick the box **Select** in the top right corner of the card. A bar appears
   above the cards: **1 selected**, **Move to…** and **Clear selection**.

3. Click **Move to…** and pick the dashboard that receives the cards.

4. A message says **Moved 1 card(s) to « Delivery »**, with a button **Open** that takes you to that
   dashboard. Click **Done**.

**Clear selection** unticks all the cards. With only one dashboard, **Move to…** has nowhere to go:
[create another dashboard](create-a-dashboard.md) first.

✅ That's it!

Next: [Change or remove a card](change-or-remove-a-card.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/change-or-remove-a-card.md -->

# Change or remove a card

## ✏️ Change a card

1. On **My Dashboards**, open the tab of the dashboard.

2. On the card, click the **More** button, always visible in the top right corner of the card. A menu
   offers **Refresh**, **Edit** and **Delete**.

3. Click **Edit**. The window **Edit Card** has three tabs:

   | Tab | What you do |
   | --- | --- |
   | **General** | Choose an icon with **Select an icon**, and change the **Card Name**. |
   | **Columns** | Under **Select columns to display**, untick a column to hide it, tick it to show it. |
   | **Filters** | See, for each column, the values the card shows, and remove the ones you do not want: see [Keep only your rows](#-keep-only-your-rows). |

4. Click **Save**.

## 🔎 Keep only your rows

A card shows everything your account can see. Some tables have a column that tells whether a row is
yours: **My role** on the pull request cards (**Author**, **Reviewer**… or **None**), **Mine** on the
cards that list components (**Mine** or **Others**). You keep your rows by removing the other values of
that column.

1. On **My Dashboards**, open the tab of the dashboard.

2. On the **Pull requests** card, click **More**, then **Edit**.

3. Open the **Filters** tab. Under **Configure columns data**, each column lists the values the card
   holds. Under **my role**, you read **None** and **Author**.

4. Click the cross of **None** (**Remove filter None**). Only **Author** stays.

5. Click **Save** in the window.

The card now lists only the pull requests where you are the author. The filter is saved with the card:
you find it again after reloading the page. In the **Filters** tab, **Reset** under a column puts all
its values back.

## 🔄 Read the source again

On the card, click **More**, then **Refresh**. The card reads its source again: see [Read a card's source again](refresh-a-card.md).

## 🗑️ Remove a card

1. On the card, click **More**, then **Delete**.

The card goes away at once, without a question. To put it on another dashboard instead, see
[Arrange your cards](arrange-your-cards.md#-move-cards-to-another-dashboard).

✅ That's it!

Next: [Choose how many results a card shows](choose-how-many-results.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/choose-how-many-results.md -->

# Choose how many results a card shows

A card that lists rows (issues, pull requests, builds…) shows 5 of them at first. You can show 10, 25 or
50 instead. The choice belongs to the card: Astrolabe keeps it.

## 🔢 Pick the number of rows

1. On **My Dashboards**, open the tab of the dashboard.

2. Under the table of the card, click **Show 5 results**. The list offers **Show 5 results**,
   **Show 10 results**, **Show 25 results** and **Show 50 results**.

3. Click **Show 50 results**, for example.

The table shows 50 rows at once. The count under the table follows, for example **1-50 of 1000**. The
arrows **Previous table page** and **Next table page** move through the other pages.

## 💾 Your choice stays

Reload the page, or come back tomorrow: the button under the card still says **Show 50 results**. Each
card keeps its own number: another card of the same dashboard stays on 5 until you change it.

✅ That's it!

## Frequently asked questions

### Why is there no such button under my card?

The button sits under the **table** of a card. A card that shows a message instead of a table, for
example **Your Jira account is not connected.**, has no table, so no button. Connect the account or do
what the message says: the table and its button come back.

### Which cards have this button?

The cards that list rows. *Checked on a Jira card; the other list cards were not checked one by one.*

Next: [Read a card's source again](refresh-a-card.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/create-a-dashboard.md -->

# Create a dashboard

Your cards do not fit on one screen? Give each subject its own dashboard: one tab per dashboard, side
by side at the top of the page.

## Before you start

Your role must allow it. Without it, the **+** button shows a padlock. Hover it: the tooltip says **Your role can't create dashboards. Ask an administrator.** Ask your administrator to give your role the **Orion-dashboard** permission
`dashboard.create` ([Check what a role gives](../../administration/access-control/check-what-a-role-gives.md)).

## 🔧 Create it

1. In the left sidebar, click **My Dashboards**. The tabs are at the top of the page, under the
   title.

2. At the right of the last tab, click the **+** button (**New dashboard**).

   A new tab appears, called `New dashboard`, and its name is already in edit mode.

3. Type the name, for example `Delivery`, then press Enter.

The new dashboard is empty. It says **Welcome to your Astrolabe Dashboard!** and **This dashboard is
empty. Add a card, or move cards here from another dashboard with Arrange.** Next:
[Add a card](add-a-card.md).

## 🚫 What Astrolabe refuses

A refusal about the name appears under the name, in red, and the name stays in edit mode.

| Message | Why |
| --- | --- |
| **A dashboard name has 1 to 60 characters.** | The name is empty or too long. |
| **A dashboard with this name already exists.** | Two of your dashboards cannot have the same name. |
| **You can have 10 dashboards at most. Delete one to create another.** | You have 10 dashboards. Click **+**: the message appears at once at the bottom left of the screen and stays there until you close it with its **×** button, and no tab is added. [Delete one](delete-a-dashboard.md). |

✅ That's it!

Next: [Rename a dashboard](rename-a-dashboard.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/critical-notifications.md -->

# Follow the critical notifications of your dashboards

When something breaks in a card (a failed workflow, a red pipeline), Astrolabe sends you a critical
notification. Your dashboards tell you where to look, and the notification takes you to the card.

## Which dashboard has unread critical notifications

A small number appears on the tab of each dashboard whose cards have unread critical notifications.
Hover or read the tab: it says, for example, **2 unread critical notifications**. The number goes
down as you read the notifications: see [Read your notifications](../notifications/read-your-notifications.md).

*Not verified on an instance yet: the counter needs a critical notification sent by a webhook.*

## Open a notification on its card

1. In the top bar, click the bell (**Notifications**).

2. Click a notification that comes from a card.

Astrolabe opens **My Dashboards** on the dashboard that holds the card, scrolls to it and highlights
it, with the message **Showing the card « Pipeline »**.

*Not verified on an instance yet, as above.*

## When the card or the dashboard is gone

| What you see | What happened |
| --- | --- |
| **This card is no longer on your dashboards.** | You deleted the card, or moved it out of your dashboards, since the notification arrived. The dashboard opens, with nothing highlighted. |
| **The dashboard of this link does not exist anymore. Showing « My Dashboard ».** | The dashboard of the link was deleted. The dashboard named in the message opens instead. The message appears at the bottom left of the screen and goes away by itself after a few seconds. |

✅ That's it!

Next: [See your dashboard full screen](full-screen.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/delete-a-dashboard.md -->

# Delete a dashboard

## 🔧 Delete it

1. Click the tab of the dashboard.

2. Click its options button (**Options of the dashboard** and its name, next to **+**), then **Delete**.

3. The window **Delete dashboard** asks: **Delete « Delivery » and all its cards? Notifications for
   repositories that are in no other dashboard stop.** Click **Delete**.

The tab goes away with its cards. The message **Dashboard « Delivery » deleted** appears at the bottom
left of the screen and goes away by itself after a few seconds, and the neighbouring dashboard opens. To keep a card, [move it to another dashboard](arrange-your-cards.md#-move-cards-to-another-dashboard)
before.

## 🚫 Your last dashboard

You cannot delete your only dashboard. The window **Keep at least one dashboard** says: **« My
Dashboard » is your last dashboard. Create another one before deleting it.** Click **Close**, [create
another dashboard](create-a-dashboard.md), then delete this one.

✅ That's it!

Next: [Add a card](add-a-card.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/faq.md -->

# Dashboard FAQ

## Can I have several dashboards?

Yes, up to 10, one tab each: see [Create a dashboard](create-a-dashboard.md). All of them are yours;
nobody else sees them.

## Is there a dashboard for my team?

No. Every dashboard is personal.

## Why is there no Edit button?

There is none on the dashboard anymore: **Add a card** is always at the top of the page, and each card
has its own **more** button. To move and resize the cards, click **Arrange**.

## Why do Add a card or Arrange show a padlock?

Your role does not let you change dashboards. Hover the padlock: it says **Your role can't add cards to dashboards. Ask an administrator.** (**Add a card**) or **Your role can't edit dashboards. Ask an administrator.** (**Arrange**). Ask your administrator to give your
role `dashboard.create` or `dashboard.update`. The cards already on the dashboard stay visible.

## Can I move a card to another dashboard?

Yes: click **Arrange**, tick the card, then **Move to…**: see
[Arrange your cards](arrange-your-cards.md#-move-cards-to-another-dashboard).

## What happens to the cards when I delete a dashboard?

They are deleted with it, and the notifications of the repositories that are in no other dashboard stop.
Move the cards you want to keep first.

## Why does a card say "Nothing here yet"?

Because it has nothing to show for you. It says why under the title, for example "No open merge
request that you authored, are assigned to or review…": the sentence names what would fill the card.
Click **Learn more** under it to open the page of the card.

## Does a card show only my own items?

No. A card shows what **your account can see** among the components of the catalog. A product owner
or a team lead sees every pull request of the repositories of the catalog that their token reads, and
keeps their own with the **My role** filter: see
[Keep only your rows](change-or-remove-a-card.md#-keep-only-your-rows).

## Why is the source `astrolabe` missing in Add new data?

Because neither **Deployments** nor **Compass** is on. Ask your administrator to turn one on in
**Administration › Plugins**: see [Turn on a plugin](../../administration/plugins/turn-on-a-plugin.md).

## A card says "List cut: too many items to read, only the most recent are shown."

The source holds more than the card can read. The sentence appears above the table, and the rows shown
are the most recent ones.

## How do I read a card's source again?

Click **more** on the card, then **Refresh**.

## Where are the pages of the cards?

Each tool has its pages under **Integration**: for example GitLab,
[Add the GitLab cards to your dashboard](../../getting-started/Configuration/Integration/gitlab/add-the-dashboard-cards.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/full-screen.md -->

# See your dashboard full screen

## 🔧 Go full screen

1. In the left sidebar, click **My Dashboards**.

2. At the top of the page, click **Fullscreen**.

The menus disappear and your cards fill the screen.

## 🔙 Come back

Click **Exit fullscreen**.

✅ That's it!

Next: [Dashboard FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/refresh-a-card.md -->

# Read a card's source again

A card reads its source (Jira, GitLab, GitHub…) by itself from time to time. To see the latest data right
now, ask it to read again.

## 🔄 Refresh a card

1. On **My Dashboards**, open the tab of the dashboard.

2. At the top right of the card, click the **More** button. A menu offers **Refresh**, **Edit** and
   **Delete**.

3. Click **Refresh**.

A loading bar appears on the card with the text **Refreshing the data**. When it disappears, the table
shows what the source answered just now.

✅ That's it!

*Checked on a Jira card; the other cards use the same menu and were not checked one by one.*

Next: [Follow the critical notifications of your dashboards](critical-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/rename-a-dashboard.md -->

# Rename a dashboard

## 🔧 Rename it

Use the way you prefer. All three open the name in edit mode.

- **Double-click** the tab.
- Click the tab, then press **F2**.
- Click the options button of the dashboard (**Options of the dashboard** and its name, next to **+**), then **Rename**.

Then type the new name and press Enter. Press Escape to keep the old name.

The refusals are the ones of [Create a dashboard](create-a-dashboard.md#-what-astrolabe-refuses): a
name of 1 to 60 characters, and no two dashboards with the same name.

Your role needs the **Orion-dashboard** permission `dashboard.update`. Without it, **Rename** shows a padlock. Hover it: the tooltip says **Your role can't edit dashboards. Ask an administrator.**

✅ That's it!

Next: [Put your dashboards in order](reorder-your-dashboards.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/reorder-your-dashboards.md -->

# Put your dashboards in order

## 🔧 Move a tab

1. Click the tab you want to move.

2. Click its options button (**Options of the dashboard** and its name, next to **+**).

3. Click **Move left** or **Move right**.

The tab changes place at once, and the order is the same next time you open **My Dashboards**. **Move
left** is greyed out on the first tab, **Move right** on the last one.

✅ That's it!

Next: [Delete a dashboard](delete-a-dashboard.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/my-dashboard/troubleshooting.md -->

# Common problems with the dashboard

| What you see | What to do |
| --- | --- |
| In a GitLab card: **Your GitLab account is not connected.** and **Connect my GitLab account** | This card shows what your own GitLab account sees. Click **Connect my GitLab account**, or go to **My Account › My accounts**. |
| **Nothing here yet** and a sentence under it, in a card | The card works and has nothing to show: the sentence says what would fill it. Click **Learn more** under it to open the page of the card. |
| **Welcome to your Astrolabe Dashboard!** and **This dashboard is empty.** | This dashboard has no card yet. Click **Add a card**: see [Add a card](add-a-card.md). |
| In **Add a card**, the title **No data source is connected** and a link **Open Company connections** | No source is connected yet. Ask an administrator to connect one in **Administration › Company connections**, for example [Add the GitLab integration](../../getting-started/Configuration/Integration/gitlab/add-the-integration.md). If you are an administrator, click **Open Company connections**. |
| In **Add a card**, the title **Grafana requires the Premium license** and a link **Open the license** | The only source connected is Grafana, and your license does not cover it. An administrator clicks **Open the license** and [adds a license](../../administration/licensing/add-your-license.md) that covers Grafana. |
| **Add a card** shows a padlock. Hover it: **Your role can't add cards to dashboards. Ask an administrator.** | Your role does not allow it. Ask your administrator: see [Add a card](add-a-card.md). |
| **Arrange** or **Rename** shows a padlock. Hover it: **Your role can't edit dashboards. Ask an administrator.** | Your role does not let you change dashboards. Ask your administrator to give it `dashboard.update`. |
| The **+** button shows a padlock. Hover it: **Your role can't create dashboards. Ask an administrator.** | Ask your administrator to give your role `dashboard.create`. |
| Under the name of a dashboard: **A dashboard with this name already exists.** or **A dashboard name has 1 to 60 characters.** — or, at the bottom left of the screen (it stays until you close it with its **×**), **You can have 10 dashboards at most. Delete one to create another.** | See [Create a dashboard](create-a-dashboard.md#-what-astrolabe-refuses). |
| The window **Keep at least one dashboard** | You cannot delete your last dashboard: see [Delete a dashboard](delete-a-dashboard.md#-your-last-dashboard). |
| **Create another dashboard to move cards to it.** in **Arrange** | You have only one dashboard. [Create another one](create-a-dashboard.md). |
| **This card is no longer on your dashboards.** or **The dashboard of this link does not exist anymore.** | See [Follow the critical notifications of your dashboards](critical-notifications.md#when-the-card-or-the-dashboard-is-gone). |
| **Astrolabe could not apply this change. Try again, or reload the page.** | The change did not reach the server. Reload the page and do it again. |
| In a card: **Astrolabe does not offer this Grafana feature on this instance.** and **A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.** | The installation of Astrolabe lacks the module of this source. Tell your administrator, with the name of the source: nothing to change in the card. |
| In an **Azure costs this month** card, under the field **tag**: **The tag "foo" is not written key=value (for example app=shop-api), with letters, digits and _ . : / @ + - only.** | Write the tag as `key=value`, for example `app=shop-api`, or leave the field empty for the whole subscription. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the card and what it says.
:::

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/choose-your-notifications.md -->

# Choose your notifications in 2 minutes

Astrolabe tells you when something happens in your tools: a pipeline that fails, a PR to review, an
issue assigned to you. You choose which events, and where they reach you.

## How to

### 1. Open your notification settings

1. Top right, click your avatar, then **My Account**.
2. Open the **Notifications** tab.

The **What do you want to receive?** card lists the tools of your Astrolabe, one section each
(**Jira**, **GitHub**…).

### 2. Read the two columns

| Column | Where the notification reaches you |
| --- | --- |
| **In Astrolabe** | In the bell, top right of Astrolabe |
| **On this browser** | As a notification of your browser, even with the Astrolabe tab closed |

### 3. Switch each event on or off

Each line is an event. Turn its switch on or off, in each column. It is saved right away.

- What breaks comes first, marked **Critical** (a pipeline that fails, a quality gate in red…). It is on
  by default.
- What only starts or succeeds is folded under **Starts and successes**. Click it to see it. It is off
  by default, except in the **Watched components** section: everything that happens to a component
  you watch is on, successes included.

:::tip The browser column is greyed out?
It says **Off on this browser**: your browser does not receive notifications yet. Click **Turn on**
under the column title: see [Receive notifications on this browser](turn-on-this-browser.md). It says
**Blocked in this browser’s settings**: allow Astrolabe's notifications in the site settings of your
browser, then reload the page.
:::

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/delete-read-notifications.md -->

# Delete the notifications you have read

Once you have read a notification, you can remove it from your history. You delete one, or all the read
ones at once. A notification you have not read yet stays: Astrolabe never deletes it.

## 🗑️ Delete one notification

1. At the top right of any page, click the bell (**Notifications**). The panel opens on the right.

2. Read the notification, or mark it as read: see [Read your notifications](read-your-notifications.md#mark-as-read).

3. At the right end of the row of the notification, click the delete button. Its name is
   **Delete notification:** followed by the title of the notification.

The notification disappears from the list at once. Astrolabe asks nothing first.

A notification you have not read has no delete button. Read it first.

## 🧹 Delete all the read notifications

1. In the panel, at the top right, click **Delete read notifications**. It sits next to the double
   check that marks everything as read.

2. The window **Delete read notifications** asks:

   `2 notifications you have already read will be deleted from your history. Unread ones are kept. This cannot be undone.`

   The number is how many you have read.

3. Click **Delete**. To change your mind, click **Cancel**.

The read notifications are gone. The ones you have not read are still there. When nothing is left, the
panel says **No notifications yet**, and **Delete read notifications** is greyed out.

✅ That's it!

:::tip Deleting is final
A deleted notification does not come back. Read the ones you want to keep before you delete.
:::

Next: [Choose your notifications](choose-your-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/faq.md -->

# Notifications FAQ

## Why don't I see GitLab (or another tool)?

Your Astrolabe only shows the tools it is connected to. Ask your Astrolabe administrator to connect it.

## Why are « starts » and « successes » off?

So that what breaks stands out. Open **Starts and successes** under a tool and turn on what you want.

## Do I set this once for all my browsers?

The **In Astrolabe** and **On this browser** switches are yours, wherever you sign in. Turning the
browser on (**Enable on this browser**) is done once per browser.

## A switch I moved is back where it was

It was not saved: the screen says **This change was not saved**. See
[Common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/read-your-notifications.md -->

# Read your notifications

The bell, top right of Astrolabe, collects everything Astrolabe tells you: an achievement you
unlocked, a pipeline that fails on a component you watch. You read it there.

## Open the bell

1. At the top right of any page, click the bell (**Notifications**). A number on it counts what you
   have not read yet.

A panel opens on the right. The notifications are grouped by day (**Today**), the newest first. Each
one has a title, a text and how long ago it arrived. What you have not read yet has a green bar on
its left.

## Keep only what you have not read

1. At the top of the panel, click **Unread**. The number in brackets is how many you have not read.
2. Click **All** to see everything again.

## Keep only one level

1. At the top of the panel, click the funnel (**Filter notifications**).
2. Pick **Critical**, **High**, **Normal** or **Low**. Pick **All** to remove the filter.

The same list also offers the source of the notifications, for example **achievements**.

## Open what a notification is about

1. Click anywhere on a notification, its title, its text or its time. You land on what it tells you
   about: the component page of a watched component, the dashboard card, or, for a merge request or a
   pipeline, its page in GitHub or GitLab, in a new tab.
2. When a new notification arrives, a small alert appears at the bottom left of the page. Click its
   message to open the same thing.

## Mark as read

1. Click a notification to read it: it is marked as read, and the number on the bell goes down by one.
2. To mark everything at once, click the double check at the top right of the panel (**Mark 5
   notifications as read**, the number is how many you have not read).

✅ That's it!

Next: [Delete the notifications you have read](delete-read-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/troubleshooting.md -->

# Common problems with notifications

| What you see | What to do |
| --- | --- |
| `Your notification settings could not be loaded: Astrolabe did not answer. Reload the page in a minute. If it keeps happening, tell your administrator.` | Reload the page in a minute. |
| `This change was not saved: Astrolabe did not answer. Try again in a minute.` | The switch went back to where it was. Move it again in a minute. |
| `Failed to delete notification: …` or `Failed to delete read notifications: …` | Nothing was deleted. Try again in a minute: see [Delete the notifications you have read](delete-read-notifications.md). |
| No delete button on a notification | You have not read it yet. Read it, or mark it as read, then the button appears. |
| The **On this browser** column is greyed out, with **Off on this browser** | Click **Turn on** under the column title, then **Allow** in your browser. |
| **Blocked in this browser's settings** under **On this browser** | Your browser refused notifications for Astrolabe. Allow them in the site settings of your browser, then reload the page. |
| **Not available on this browser** under **On this browser** | Your browser cannot receive push notifications. Use the **In Astrolabe** column. |
| `No tool is connected to Astrolabe yet: there is nothing to receive.` | Ask your Astrolabe administrator to connect your tools. |
| `Could not watch payment-processor: …` or `Could not stop watching payment-processor: …` | Nothing changed: the eye is as it was. Try again in a minute. |
| You watch a component but hear nothing of its pipelines | Its `catalog-info.yaml` does not name its project for that tool: add the annotation (see [Watch a component](watch-a-component.md)). |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/turn-on-this-browser.md -->

# Receive notifications on this browser

Astrolabe can show its notifications as notifications of your browser, even when its tab is closed.
You turn it on once per browser.

## How to

1. Top right, click your avatar, then **My Account**.
2. Open the **Notifications** tab.
3. In the **Browser notifications** card, click **Enable on this browser**.
4. Your browser asks whether Astrolabe may show notifications: click **Allow**.

The card says **This browser receives critical notifications, even without an open tab.** The **On this
browser** column of **What do you want to receive?** is no longer greyed out: choose there what reaches
this browser.

✅ That's it!

To stop: click **Disable on this browser** in the same card.

---

<!-- https://doc.forgeit.fr/docs/developer-dashboard/notifications/watch-a-component.md -->

# Watch a component in 1 minute

You work with a component you don't own: an API you call, a library you depend on. Watch it, and
Astrolabe tells you everything that happens to it: a pipeline that starts, fails or succeeds, a quality
gate that turns red or green, a Compass score that drops.

## How to

### 1. Watch it from the catalog

1. In the sidebar, click **Catalog**.
2. Find the component in the list (type its name in **Search by name**, above the list).
3. On its row, click **More actions** (the three dots), then **Watch**.

A message confirms: **You are watching payment-processor: you will be notified of everything that
happens to it.**

:::tip From the component's page
Next to the star beside the component's name, click the eye **Watch**. Pressed, it reads
**Stop watching**.
:::

### 2. Find what you watch

1. Top right, click your avatar, then **My Account**.
2. Open the **Notifications** tab.

The **Watched components** card lists them. Click a name to open its page.

### 3. Receive the notifications

What happens to a watched component reaches you in the bell, top right of Astrolabe. Click a
notification: it opens the component's tab that shows the problem (its CI, SonarQube, Codacy or
Compass tab), or the component's page.


### 4. Turn one event off

You want the failures, not the successes? Keep watching, and switch that event off.

1. In **My Account** › **Notifications**, go down to **What do you want to receive?**.
2. In the **Watched components** section, what breaks comes first. Click **Starts and successes** to see
   the rest.
3. Turn off the event, for example **GitHub — When a workflow completes successfully**, in the
   **In Astrolabe** column (the bell) or **On this browser**. It is saved right away.

### 5. Stop watching

In **My Account** › **Notifications** › **Watched components**, click **Stop watching
payment-processor** next to its name. Or, on its page, click the pressed eye **Stop watching**.

✅ That's it!

## What you hear of, and when

| Tool | Events | When |
| --- | --- | --- |
| GitHub, GitLab, Azure DevOps | Pipeline started, succeeded, failed, cancelled | Right away with the tool's webhook, otherwise within a few minutes |
| Jenkins | Build started, succeeded, failed, aborted | Within a few minutes |
| SonarQube | Quality gate turned red, back to green | Right away with the webhook, otherwise within a few minutes |
| Codacy | Grade dropped, grade rose | Within a few minutes |
| Compass | Score dropped, score rose | Within a few minutes |

A failure is **Critical**. A state that does not change says nothing: a quality gate that stays red is
told once.

The component must name its project in its `catalog-info.yaml`, for each tool:

```yaml
metadata:
  annotations:
    github.com/project-slug: acme/payment-processor
    gitlab.com/project-slug: acme/payment-processor
    dev.azure.com/project-repo: payments/payment-processor
    jenkins.io/job-full-name: payment-processor
    sonarqube.org/project-key: acme-payment-processor
    codacy.com/project-slug: gh/acme/payment-processor
```

Compass needs no annotation.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/astrolabe-account/reset-the-password.md -->

# Reset the administrator password

If you forgot the administrator password, Astrolabe sends a verification code to the **administrator email
address**.

## Before you start

Your Astrolabe needs a mail server to send the code. An administrator enters it once, in
**Administration › General**, on the **Mail server** tab:

| Field | What to enter | Example |
| --- | --- | --- |
| **Host** | The address of the mail server | `smtp.example.com` |
| **Port** | Its port, usually `587` | `587` |
| **User** | The account that sends the messages | `astrolabe` |
| **Password** | The password of that account | |
| **From** | The address the messages come from | `astrolabe@example.com` |

Click **Save**. The screen says **Settings saved.** The mail server must offer a secure connection (STARTTLS), usually on port `587`.

## 🔑 Ask for the code

1. On the sign-in page, click **Forgot password?**

2. The window **Reset Administrator Password** opens: **Click below to send a verification code to the
   administrator email.** Click **Send verification code**.

3. The window now shows the administrator email address, partly hidden, under **Administrator Email**. Astrolabe
   says **Verification code sent to your email**.

4. Open the administrator mailbox. Open the message **[Astrolabe] Password Request - Your verification code**
   and read the six-digit code.

## 🔓 Get the password

1. Back in the window, click the **Verification Code** field and type the code.

2. Click **Verify code**. The sign-in page says **Password was sent by email to** followed by the hidden
   address.

3. Open the administrator mailbox. Open the message **[Astrolabe] Password Request - Your admin password**.

4. On the sign-in page, type the administrator name in **Username** and the password from the message in
   **Password**, then click **SIGN IN**.

✅ That's it!

Something is wrong? See [Common problems with sign-in](../troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/astrolabe-account/sign-in.md -->

# Sign in with your Astrolabe account

The **Username** and **Password** form of the sign-in page is the way in for the **administrator** account of
your Astrolabe. It is always there, whichever providers you turn on.

Everyone else signs in with a provider: see [Choose how people sign in](../authentification.md).

## Before you start

You need the address of your Astrolabe, and the administrator username and password.

## 🔐 Sign in

1. Open the address of your Astrolabe in your browser.

2. In **Username**, enter the administrator username.

3. In **Password**, enter the password. Click the eye icon, **Show value**, to read what you typed.

4. Click **SIGN IN**.

You land on **My Dashboards**. **Administration** is in the left sidebar.

## 🚪 Sign out

1. Top right, click your initial.

2. Click **Logout**.

The sign-in page is back.

:::tip
A new administrator password signs out every browser still open with the old one: sign in again there with
the new password.
:::

✅ That's it!

Forgot the password? See [Reset the administrator password](reset-the-password.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/atlassian/add-atlassian.md -->

# Add Atlassian

You give Astrolabe the Atlassian app you created. Atlassian then appears in **Administration ›
Authentication** as an active provider.

You do it once, as an administrator.

## Before you start

You need the **Client ID** and the **Secret** of an Atlassian OAuth 2.0 app: see
[Create the Atlassian OAuth 2.0 app](create-the-atlassian-app.md).

## 🔧 Turn Atlassian on

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**.

3. On the **Atlassian** card, turn on the switch at the top right. The window **Configure Atlassian**
   opens.

4. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Client ID** | The Client ID of the app | |
   | **Client Secret** | Its Secret | |
   | **Scope** | The scopes, separated by spaces | `offline_access read:jira-work read:jira-user` |

   The three fields are marked **(Required)**.

5. Click **Install**. The screen says **The configuration has changed; the server is restarting.** Wait a
   few seconds.

The **Atlassian** card is now among the active providers at the top of the list, its switch is on, and it
has a **Configure** button.

## 🔄 Change or remove Atlassian

1. On the **Atlassian** card, click **Configure**.

2. To change a value, edit the field. To change the secret, click **Replace** next to **Client
   Secret**. Click **Update Configuration**.

3. To remove Atlassian, click **Uninstall**.

✅ That's it!

Something is wrong? See [Common problems with sign-in](../troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/atlassian/create-the-atlassian-app.md -->

# Create the Atlassian OAuth 2.0 app

Atlassian needs to know Astrolabe before it talks to it. You create an **OAuth 2.0 integration** in the
Atlassian developer console and copy two values from it.

You do it once. These steps happen at Atlassian. They were not checked on a live instance.

## Before you start

You need the address of your Astrolabe, for example `astrolabe.example.com`.

## 🔑 Create the app

1. In the Atlassian developer console, click **Create**, then **OAuth 2.0 integration**.

2. In **Name**, enter `Astrolabe`, then create the app.

3. Open **Authorization**. In **Callback URL**, enter:

   ```text
   https://astrolabe.example.com/api/auth/atlassian/handler/frame
   ```

   Replace `astrolabe.example.com` with the address of your Astrolabe.

4. Save.

5. Open **Settings**, and **copy the Client ID and the Secret**.

✅ That's it!

Next: [Add Atlassian](add-atlassian.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/auth0/add-auth0-sign-in.md -->

# Add Auth0 sign-in

Once Auth0 is on, the sign-in page shows a **Continue with Auth0** button.

You do it once, as an administrator.

## Before you start

You need the **Domain**, the **Client ID** and the **Client Secret** of an Auth0 application: see
[Create the Auth0 application](create-the-auth0-app.md).

## 🔧 Turn Auth0 on

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**.

3. On the **Auth0** card, turn on the switch at the top right. The window **Configure Auth0** opens.

4. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Client ID** | The Client ID of the application | |
   | **Client Secret** | Its Client Secret | |
   | **Domain** | The Auth0 domain, **without** `https://` | `example.eu.auth0.com` |
   | **Audience** | Leave empty | |
   | **Connection** | Leave empty | |
   | **Connection Scope** | Leave empty | |

   **Client ID**, **Client Secret** and **Domain** are marked **(Required)**. The three other fields are
   optional.

5. Click **Install**. The screen says **The configuration has changed; the server is restarting.** Wait a
   few seconds.

The **Auth0** card is now among the active providers at the top of the list, its switch is on, and it has a **Configure** button.

## ✅ Check

1. Top right, click your initial, then **Logout**.

2. The sign-in page shows **Continue with Auth0**, above **Or** and the **Username** and **Password** form.

Signing in through Auth0 was not checked on a live instance. Astrolabe then looks in your catalog for the
user whose email address is the one of the Auth0 account.

## 🔄 Change or remove Auth0

1. On the **Auth0** card, click **Configure**.

2. To change a value, edit the field. To change the secret, click **Replace** next to **Client Secret**.
   Click **Update Configuration**.

3. To remove Auth0, click **Uninstall**.

✅ That's it!

Something is wrong? See [Common problems with sign-in](../troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/auth0/create-the-auth0-app.md -->

# Create the Auth0 application

Auth0 needs to know Astrolabe before it lets people sign in. You create an **application** in Auth0 and
copy three values from it.

You do it once. These steps happen in Auth0. They were not checked on a live instance.

## Before you start

You need the address of your Astrolabe, for example `astrolabe.example.com`.

## 🔑 Create the application

1. In the Auth0 dashboard, open **Applications**, then **Applications**.

2. Click **Create Application**.

3. In **Name**, enter `Astrolabe`. For the type, choose **Regular Web Applications**. Click **Create**.

4. Open the **Settings** tab.

5. In **Allowed Callback URLs**, enter:

   ```text
   https://astrolabe.example.com/api/auth/auth0/handler/frame
   ```

   Replace `astrolabe.example.com` with the address of your Astrolabe.

6. Click **Save Changes**.

7. **Copy the Domain, the Client ID and the Client Secret.**

✅ That's it!

Next: [Add Auth0 sign-in](add-auth0-sign-in.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/authentification.md -->

# Choose how people sign in

Your Astrolabe always has a **username and password** form for the administrator account. You can add
**providers** next to it: people then sign in with the account they already have at Google or Auth0.

You choose the providers once, as an administrator.

## What the sign-in page shows

The sign-in page lists one button per active provider, for example **Continue with Google**. Under
**Or**, the **Username** and **Password** form is always there.

## Where you turn a provider on

In the left sidebar, at the bottom, click **Administration**. Under **PLATFORM**, click
**Authentication**. The **Providers** tab shows one card per provider, with a switch at the top right. The
active providers come first, each with a **Configure** button.

## The providers

| Provider | What you do |
| --- | --- |
| Astrolabe account | [Sign in with your Astrolabe account](astrolabe-account/sign-in.md) |
| Google | [Add Google sign-in](google/add-google-sign-in.md) |
| Auth0 | [Add Auth0 sign-in](auth0/add-auth0-sign-in.md) |
| Okta | [Add Okta](okta/add-okta.md) |
| Atlassian | [Add Atlassian](atlassian/add-atlassian.md) |
| Azure | [Azure Entra ID](./microsoft/set-up-sign-in.md) |
| GitHub | [GitHub](./github/configure-github-sign-in.md) |

## The steps are always the same

1. At the provider, create an application and copy its **Client ID** and **Client Secret**. You give the
   provider the address Astrolabe shows in the **?** next to **Client ID**.

2. In Astrolabe, turn the provider on and enter what you copied.

3. Sign out, and check the sign-in page.

✅ That's it!

Questions? See the [Authentication FAQ](faq.md). Something is wrong? See
[Common problems with sign-in](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/faq.md -->

# Authentication FAQ

## Can I turn on several providers?

Yes. The sign-in page shows one button per provider, for example **Continue with Auth0** and **Continue
with Google**.

## Is the username and password form still there?

Yes. It stays under **Or**, whichever providers you turn on. It is the way in for the administrator.

## Where do I see which providers are on?

In **Administration › Authentication**. The active providers come first, each with a **Configure** button
and its switch on.

## How do I turn a provider off?

On its card, click **Configure**, then **Uninstall**.

## Do I have to restart Astrolabe?

No. After **Install**, **Update Configuration** or **Uninstall**, Astrolabe restarts by itself: the screen
says **The configuration has changed; the server is restarting.**

## Why are the buttons grayed?

Without an active license, the provider buttons are grayed, with **Sign-in disabled: license is not
active** under them. The username and password form keeps working. See
[Common problems with sign-in](troubleshooting.md).

## Where do I create the other accounts?

Not in Astrolabe: people sign in with the account they have at their provider.

## What do I give the provider?

The address Astrolabe shows in the **?** next to **Client ID**, `<Astrolabe address>/api/auth/<provider>/handler/frame`,
where `<provider>` is `google`, `auth0`, `okta` or `atlassian`.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/github/configure-github-sign-in.md -->

# Configure GitHub sign-in in Astrolabe

You give Astrolabe the **Client ID** and **Client Secret** of your GitHub OAuth app. Then the sign-in
page offers **Continue with GitHub**.

You do it once, as an administrator.

## Before you start

You need the **Client ID** and **Client Secret** of the app: see
[Create the OAuth app in GitHub](create-the-oauth-app.md).

## 🔧 Install the GitHub provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**. The **Providers** tab opens.

3. On the **GitHub** card, click the switch at the top right of the card. The **Configure GitHub**
   window opens.

4. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Client ID** | The Client ID of your OAuth app | `Ov23li…` |
   | **Client Secret** | The client secret of the app | `0123…` |
   | **Entreprise Instance URL** | Leave empty. For GitHub Enterprise only: its full address with `https://`. | `https://github.example.com` |
   | **Callback URL** | Leave empty: Astrolabe uses `<Astrolabe address>/api/auth/github/handler/frame`. | |

5. Click **Install**. The instance reloads.

When the page is back, the **GitHub** card shows its switch on, with a **Configure** button. A warning
above the cards says `Nobody can sign in with GitHub yet: an account must be in the catalog first.`
until the next section is done.

## 👥 Import the members

Signing in with GitHub only works for an account Astrolabe already knows. You import the members of your
GitHub organization into the catalog.

1. In the warning, click **Open Catalog › GitHub**. The **Catalog** page opens.

2. On the **GitHub** card, click **Configure**. The **Configure GitHub** window opens.

3. Fill in **Organization** with the name of your GitHub organization.

4. Tick **Import GitHub members and teams**.

5. Click **Install**. The instance reloads.

6. Go back to **Administration › Authentication**: the warning is gone.

Steps 3 to 6 were not checked on an instance connected to a real GitHub organization.

The token of your GitHub connection needs the **`read:org`** and **`read:user`** scopes. The other fields are described in
[Import your GitHub repositories](../../Catalogue/github/import-repositories.md#-members-and-teams).

✅ That's it!

Next: [Sign in with GitHub](sign-in-with-github.md).

## 🔌 Turn GitHub sign-in off

1. In **Administration › Authentication**, click **Configure** on the **GitHub** card.

2. Click **Uninstall**. The instance reloads, without asking for confirmation.

The **Continue with GitHub** button leaves the sign-in page.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/github/create-the-oauth-app.md -->

# Create the OAuth app in GitHub

For your users to sign in to Astrolabe with GitHub, GitHub must know Astrolabe: you create an **OAuth
app** there, and it gives you a **Client ID** and a **Client Secret**.

You do it once, as an administrator of your GitHub account or organization.

## Before you start

You need the address of your Astrolabe, as your users open it. Astrolabe's own form gives the address
GitHub must call back:

```text
<Astrolabe address>/api/auth/github/handler/frame
```

## 🔑 Create the app

1. In GitHub, open **Settings › Developer settings › OAuth Apps**, then **New OAuth App**.

2. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Application name** | A name of your choice | `Astrolabe` |
   | **Homepage URL** | The address of your Astrolabe | `https://astrolabe.example.com` |
   | **Authorization callback URL** | The address above | `https://astrolabe.example.com/api/auth/github/handler/frame` |

3. Click **Register application**.

4. Copy the **Client ID**.

5. Click **Generate a new client secret** and copy the secret.

This step was not checked on a live instance: the GitHub screens come from Astrolabe's form help, which
only names the OAuth app and the address to call back.

✅ That's it!

Next: [Configure GitHub sign-in in Astrolabe](configure-github-sign-in.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/github/faq.md -->

# GitHub sign-in FAQ

### Which callback address do I give GitHub?

`<Astrolabe address>/api/auth/github/handler/frame`. Leave **Callback URL** empty in Astrolabe: it uses
this address.

### Does it work with GitHub Enterprise?

The form has an **Entreprise Instance URL** field for it: write the full address of your GitHub
Enterprise, with `https://`. Leave it empty for github.com.

### Where do I read the Client ID again?

In **Administration › Authentication**, in **Configure** on the **GitHub** card. The secret is hidden
there: next to it, **Replace** lets you enter a new one.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/github/sign-in-with-github.md -->

# Sign in with GitHub

Once GitHub sign-in is configured, your users sign in to Astrolabe with their GitHub account.

## Before you start

The administrator has [configured GitHub sign-in](configure-github-sign-in.md).

## 🚪 Sign in

1. Open your Astrolabe. The sign-in page says **welcome to Astrolabe**.

2. Click **Continue with GitHub**.

3. Authorize the application on GitHub. You come back to Astrolabe, signed in.

This step was not checked on a live instance.

✅ That's it!

Something does not work? Read the [frequently asked questions](faq.md) and the
[common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/github/troubleshooting.md -->

# Common problems with GitHub sign-in

| What you see | What to do |
| --- | --- |
| In the **Configure GitHub** window, under **Client ID**: `Client ID is required` | Paste the Client ID of your OAuth app. |
| Under **Client Secret**: `Client Secret is required` | Paste the client secret of your OAuth app. |
| On the sign-in page, **Continue with GitHub** is disabled, with `Sign-in disabled: license is not active` | The instance has no active license. In **Administration**, click **Licensing** and configure it. |
| Someone who signs in with GitHub reads `Your account is not known to Astrolabe yet. Ask your administrator to add you, then try again.` | The members of your GitHub organization are not in the catalog. An administrator opens **Administration › Authentication**, clicks **Open Catalog › GitHub** in the warning, then on the **GitHub** card **Configure**, ticks **Import GitHub members and teams** and clicks **Install**. See [Import the members](configure-github-sign-in.md#-import-the-members). Once the import has run, the person tries again. |
| In **Administration › Authentication**, above the cards: `Nobody can sign in with GitHub yet: an account must be in the catalog first.` | Click **Open Catalog › GitHub** and import the members, as above. |

:::tip Still stuck?
Write to **support@forgeit.fr**.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/gitlab/configure-gitlab-sign-in.md -->

# Configure GitLab sign-in in Astrolabe

You give Astrolabe the **Application ID** and the **Secret** of your GitLab application. Then the
sign-in page offers GitLab.

You do it once, as an administrator.

## Before you start

You need the **Application ID** and the **Secret** of the application: see
[Create the GitLab application](create-the-oauth-app.md).

## 🔧 Install the GitLab provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**. The **Providers** tab opens.

3. On the **GitLab** card, click the switch at the top right of the card. The **Configure GitLab**
   window opens.

4. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Application ID** | The Application ID of your GitLab application | `1a2b3c…` |
   | **Secret** | The secret of that application | `0123…` |
   | **GitLab URL** | Leave empty for gitlab.com. For your own GitLab: its full address with `https://`. | `https://gitlab.exemple.com` |
   | **Callback URL** | Leave empty: Astrolabe uses `<Astrolabe address>/api/auth/gitlab/handler/frame`. | |

5. Click **Install**. The instance reloads.

When the page is back, the **GitLab** card shows its switch on, with a **Configure** button.

## 👥 Import the members

Signing in with GitLab only works for an account Astrolabe already knows. You import your GitLab
groups and their members into the catalog. This needs a GitLab connection first.

1. In the left sidebar, under **PLATFORM**, click **Company connections**.

2. On the **GitLab** card, click **Manage**. Under **Tokens**, click **Add a token** (« Ajouter un jeton »).

3. Fill in the **name**, the **GitLab instance host** (for example `gitlab.exemple.com`, without
   `https://`) and the **GitLab token**. Click **Test the connection** (« Tester la connexion »), then
   **Add** (« Ajouter »). The instance reloads.

4. Go to **Administration › Catalog**. On the **GitLab** card, click **Configure**.

5. Tick **Import GitLab groups and their members**. Click **Install**. The instance reloads.

Then the groups and their members come into the catalog. See
[Import your GitLab groups](../../Catalogue/gitlab/import-groups.md).

These screens were checked up to the GitLab card of the catalog; the rest of this section was not
checked on a live GitLab.

✅ That's it!

Next: [Sign in with GitLab](sign-in-with-gitlab.md).

## 🔌 Turn GitLab sign-in off

1. In **Administration › Authentication**, click **Configure** on the **GitLab** card.

2. Click **Uninstall**. The instance reloads, without asking for confirmation.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/gitlab/create-the-oauth-app.md -->

# Create the GitLab application

For your users to sign in to Astrolabe with GitLab, GitLab must know Astrolabe: you create an
**application** there, and it gives you an **Application ID** and a **Secret**.

You do it once. You need an account that can create applications on your GitLab: your own
(**User settings › Applications**) or, for a GitLab you run yourself, the **Admin area › Applications**.

## Before you start

You need the address of your Astrolabe, as your users open it. The **Callback URL** that GitLab must
call back is:

```text
<Astrolabe address>/api/auth/gitlab/handler/frame
```

For `https://astrolabe.example.com`, that is `https://astrolabe.example.com/api/auth/gitlab/handler/frame`.

## 🔑 Create the application

1. In GitLab, open **User settings › Applications**, or **Admin area › Applications** if you are
   creating it for the whole instance.

2. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice | `Astrolabe` |
   | **Redirect URI** | The callback address above | `https://astrolabe.example.com/api/auth/gitlab/handler/frame` |
   | **Scopes** | `read_user`, `openid`, `profile` and `email` | |

3. Save the application. GitLab shows the **Application ID** and the **Secret**. Copy both.

These screens were not checked on a live GitLab: the steps come from the help of Astrolabe's form,
which names the scopes and the callback address.

✅ That's it!

Next: [Configure GitLab sign-in in Astrolabe](configure-gitlab-sign-in.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/gitlab/faq.md -->

# GitLab sign-in FAQ

### Which callback address do I give GitLab?

`<Astrolabe address>/api/auth/gitlab/handler/frame`. Leave **Callback URL** empty in Astrolabe: it uses
this address.

### Does it work with a GitLab I run myself?

Yes. Write its full address in **GitLab URL**, with `https://`, for example `https://gitlab.exemple.com`.
Leave it empty for gitlab.com.

### Where do I read the Application ID again?

In **Administration › Authentication**, in **Configure** on the **GitLab** card. The secret is hidden
there.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/gitlab/sign-in-with-gitlab.md -->

# Sign in with GitLab

Once GitLab sign-in is configured, your users sign in to Astrolabe with their GitLab account.

## Before you start

The administrator has [configured GitLab sign-in](configure-gitlab-sign-in.md), and your account has
been imported into the catalog.

## 🚪 Sign in

1. Open your Astrolabe. The sign-in page says **welcome to Astrolabe**.

2. Click the GitLab button on the sign-in page.

3. Authorize the application on GitLab. You come back to Astrolabe, signed in.

This step was not checked on a live GitLab.

✅ That's it!

Something does not work? Read the [frequently asked questions](faq.md) and the
[common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/gitlab/troubleshooting.md -->

# Common problems with GitLab sign-in

The messages below are quoted as the French interface shows them.

| What you see | What to do |
| --- | --- |
| In the **Configure GitLab** window, under **Application ID**: `ID de l'application est requis` | Paste the Application ID of your GitLab application. |
| Under **Secret**: `Secret est requis` | Paste the secret of your GitLab application. |
| In **Company connections › GitLab**, after **Test the connection**: `Aucun serveur ne répond au nom gitlab.exemple.com.` | Check the spelling of the **GitLab instance host**, without `https://`. If it is right, your Astrolabe cannot reach that server: ask the administrator of your company. |
| In **Administration › Catalog**, the **GitLab** card: `Configurez d'abord l'intégration GitLab : sans elle, ce fournisseur ne peut rien lire.` | Add the GitLab token first, in **Company connections › GitLab**, as described in [Import the members](configure-gitlab-sign-in.md#-import-the-members). |
| Someone who signs in with GitLab reads `Your account is not known to Astrolabe yet. Ask your administrator to add you, then try again.` | The members of your GitLab groups are not in the catalog. An administrator imports them, as described in [Import the members](configure-gitlab-sign-in.md#-import-the-members). Once the import has run, the person tries again. |

:::tip Still stuck?
Write to **support@forgeit.fr**.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/google/add-google-sign-in.md -->

# Add Google sign-in

Once Google is on, the sign-in page shows a **Continue with Google** button.

You do it once, as an administrator.

## Before you start

You need the **Client ID** and the **Client Secret** of a Google OAuth client: see
[Create the Google OAuth client](create-the-google-app.md).

## 🔧 Turn Google on

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**.

3. On the **Google** card, turn on the switch at the top right. The window **Configure Google** opens.

4. Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Client ID** | The Client ID of the OAuth client |
   | **Client Secret** | Its Client secret |

   Both are marked **(Required)**. The **?** next to **Client ID** gives the address to declare at Google:
   `<Astrolabe address>/api/auth/google/handler/frame`.

5. Click **Install**. The screen says **The configuration has changed; the server is restarting.** Wait a
   few seconds.

The **Google** card is now among the active providers at the top of the list, its switch is on, and it has a **Configure** button.

## ✅ Check

1. Top right, click your initial, then **Logout**.

2. The sign-in page shows **Continue with Google**, above **Or** and the **Username** and **Password**
   form.

Signing in through Google was not checked on a live instance. Astrolabe then looks in your catalog for the
user whose name is the part of the Google email address before the `@`.

## 🔄 Change or remove Google

1. On the **Google** card, click **Configure**.

2. To change the client, edit **Client ID**. To change the secret, click **Replace** next to **Client
   Secret**. Click **Update Configuration**.

3. To remove Google, click **Uninstall**.

✅ That's it!

Something is wrong? See [Common problems with sign-in](../troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/google/create-the-google-app.md -->

# Create the Google OAuth client

Google needs to know Astrolabe before it lets people sign in. You create an **OAuth client** in Google
Cloud and copy two values from it.

You do it once. These steps happen in Google Cloud. They were not checked on a live instance.

## Before you start

You need the address of your Astrolabe, for example `astrolabe.example.com`.

## 🔑 Create the client

1. In the Google Cloud console, open **APIs & Services**, then **Credentials**.

2. Click **Create credentials**, then **OAuth client ID**.

3. In **Application type**, choose **Web application**.

4. In **Name**, enter `Astrolabe`.

5. Under **Authorized redirect URIs**, click **Add URI** and enter:

   ```text
   https://astrolabe.example.com/api/auth/google/handler/frame
   ```

   Replace `astrolabe.example.com` with the address of your Astrolabe.

6. Click **Create**.

7. **Copy the Client ID and the Client secret.**

✅ That's it!

Next: [Add Google sign-in](add-google-sign-in.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/microsoft/faq.md -->

# Microsoft sign-in FAQ

## Which redirect URL do I declare in Microsoft Entra ID?

The address of your Astrolabe followed by `/api/auth/microsoft/handler/frame`. The **?** next to
**Client ID**, in the **Configure Azure** window, says the same.

## Why is the button "Continue with Microsoft" greyed?

Because the instance has no active license: the page says **Sign-in disabled: license is not
active**. See **Administration › Licensing**.

## What is the Domain Hint for?

To skip Microsoft's account picker: write your organization's domain, for example `exemple.com`.
The field is optional.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/microsoft/set-up-sign-in.md -->

# Set up the Microsoft sign-in

Your users sign in to Astrolabe with their Microsoft Entra ID account, with the button **Continue
with Microsoft** on the sign-in page.

You set it up once, as an administrator.

*The Microsoft sign-in itself was not checked: the button stays greyed on an instance without an
active license, and no Microsoft user account was at hand. This step was not checked on a live
instance.*

## Before you start

You need:

- an **active license** (**Administration › Licensing**);
- an app registration in Microsoft Entra ID, with a client secret. Keep its **Application (client)
  ID**, its **Directory (tenant) ID** and the **Value** of its client secret;
- the **redirect URL** declared on that app registration, which is the address of your Astrolabe
  followed by `/api/auth/microsoft/handler/frame`. For example:

  ```
  https://astrolabe.exemple.com/api/auth/microsoft/handler/frame
  ```

## 🔧 Add the provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**. The **Providers** tab opens.

3. On the **Azure** card, click the switch. The window **Configure Azure** opens.

4. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Client ID** | The Application (client) ID | |
   | **Client Secret** | The Value of the client secret, not the Secret ID | |
   | **Tenant ID** | The Directory (tenant) ID | |
   | **Domain Hint** | Optional. Your organization's domain, to skip Microsoft's account picker. | `exemple.com` |
   | **Skip User Profile** | Optional. Tick it so Astrolabe does not read the user's profile and photo from Microsoft Graph, if the app may not call Graph. | |

5. Click **Install**. A banner says **The configuration has changed; the server is restarting.**

About a minute later, the **Azure** card is at the top of the list, with a **Configure** button.

## 🚪 See the button

1. Top right, click your name, then **Logout**.

2. The sign-in page shows **Continue with Microsoft**.

On an instance without an active license, the button is greyed and the page says **Sign-in disabled:
license is not active**. Sign in with your username and password, and activate the license.

✅ That's it!

Next: [Common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/microsoft/troubleshooting.md -->

# Common problems with the Microsoft sign-in

| What you see | What to do |
| --- | --- |
| On the sign-in page, **Continue with Microsoft** is greyed and the page says `Sign-in disabled: license is not active` | The instance has no active license. Sign in with your username and password, then go to **Administration › Licensing**. |
| In **Administration**, a banner `No license configured. The application still works; licensed features are limited.` | Click **Configure the license**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/okta/add-okta.md -->

# Add Okta

You give Astrolabe the Okta application you created. Okta then appears in **Administration ›
Authentication** as an active provider.

You do it once, as an administrator.

## Before you start

You need the **Client ID** and the **Client secret** of an Okta application, and the address of your Okta:
see [Create the Okta application](create-the-okta-app.md).

## 🔧 Turn Okta on

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Authentication**.

3. On the **Okta** card, turn on the switch at the top right. The window **Configure Okta** opens.

4. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Client ID** | The Client ID of the application | |
   | **Client Secret** | Its Client secret | |
   | **Audience** | The address of your Okta, **with** `https://` | `https://example.okta.com` |
   | **Auth Server ID** | Leave empty | |
   | **IDP** | Leave empty | |
   | **Session Duration** | Leave empty | |
   | **Additional Scopes** | Leave empty | |
   | **Sign In Configuration** | Leave empty | |

   **Client ID**, **Client Secret** and **Audience** are marked **(Required)**. The other fields are optional.

5. Click **Install**. The screen says **The configuration has changed; the server is restarting.** Wait a
   few seconds.

The **Okta** card is now among the active providers at the top of the list, its switch is on, and it has a
**Configure** button.

## 🔄 Change or remove Okta

1. On the **Okta** card, click **Configure**.

2. To change a value, edit the field. To change the secret, click **Replace** next to **Client Secret**.
   Click **Update Configuration**.

3. To remove Okta, click **Uninstall**.

✅ That's it!

Something is wrong? See [Common problems with sign-in](../troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/okta/create-the-okta-app.md -->

# Create the Okta application

Okta needs to know Astrolabe before it talks to it. You create an **application** in Okta and copy two
values from it.

You do it once. These steps happen in Okta. They were not checked on a live instance.

## Before you start

You need the address of your Astrolabe, for example `astrolabe.example.com`, and the address of your Okta,
for example `https://example.okta.com`.

## 🔑 Create the application

1. In the Okta admin console, open **Applications**, then **Applications**.

2. Click **Create App Integration**.

3. In **Sign-in method**, choose **OIDC - OpenID Connect**. In **Application type**, choose **Web
   Application**. Click **Next**.

4. In **App integration name**, enter `Astrolabe`.

5. In **Sign-in redirect URIs**, enter:

   ```text
   https://astrolabe.example.com/api/auth/okta/handler/frame
   ```

   Replace `astrolabe.example.com` with the address of your Astrolabe.

6. Click **Save**.

7. **Copy the Client ID and the Client secret.**

✅ That's it!

Next: [Add Okta](add-okta.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/request-access.md -->

# Request access when sign-in is refused

When you sign in with a provider and Astrolabe refuses you, the sign-in page lets you ask an administrator
for access. There are two cases: you have no license, or Astrolabe does not know your account yet. An
administrator then answers in **Administration › Licensing**.


## 🙋 Ask for access when you have no license

1. On the sign-in page, the window **Request Access to Astrolabe** is open. It says **You don't have an
   active license for Astrolabe. Would you like to request access?** and, under it, your account, for
   example `User: user:default/acme.dupont`. You have nothing to type for that line.

2. In **Reason for access request (optional)**, write why you need access.

3. Click **Request Access**.

The window closes and a message says **Access request sent. An administrator will review it.**

The window opens the same way when the provider sends you back to Astrolabe after the refusal. This
page was written from that return to the sign-in page; the provider's own screen was not checked on a
live instance.

✅ That's it!

## 🙋 Ask for access when Astrolabe does not know your account

When the provider accepts you but Astrolabe has no account for you in its catalog, you come back to the
sign-in page and a message at the top says **Your account is not known to Astrolabe yet. Ask your
administrator to add you, then try again.**

1. Under **Astrolabe**, click **Request access**.

2. In the window **Request Access to Astrolabe**, type your address in **Your email**. It is required:
   **Request Access** stays grayed until the address is valid.

3. In **Your name (optional)**, type your name.

4. In **Reason for access request (optional)**, write why you need access.

5. Click **Request Access**.

The window closes and a message says **Access request sent. An administrator will review it.**

If you send a second request with the same address while the first one waits, a message says **An access
request for this email is already pending.** Nothing more to do: wait for the administrator.

✅ That's it!

## 🛡️ Answer a request (administrator)

1. In the left sidebar, at the bottom, click **Administration**, then, under **SECURITY**, **Licensing**.

2. Click the **Access Requests** tab. The title says how many there are, for example **Access Requests
   (1)**.

3. Each line shows **User**, **Origin**, **Status** (**Pending**), **Requested**, **Reason** and two
   buttons, **Approve** and **Deny**. **Origin** is **No license** or **Account not in the catalog**.

4. For a request whose **Origin** is **Account not in the catalog**, click **Approve**. A message says
   **Request approved. The account is not in the catalog: add it so the person can sign in.** The request
   moves to **Approved** (click **Show All Requests** to see it), but the person can sign in only once
   you have added their account to the catalog.

What **Approve** and **Deny** do for a person who has no license was not checked on a live instance.
**Deny** was not checked either.

Next: [Common problems with sign-in](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Authentication/troubleshooting.md -->

# Common problems with sign-in

## On the sign-in page

| What you see | What to do |
| --- | --- |
| A banner **Authentication failed** after **SIGN IN** | The **Username** or the **Password** is wrong. Type them again: click the eye icon, **Show value**, to read the password. If you forgot it, see [Reset the administrator password](astrolabe-account/reset-the-password.md). |
| **Sign-in disabled: license is not active** under a provider button | Astrolabe has no active license. In **Administration**, the banner **Configure the license** leads to the license screen. |
| **Sign-in was cancelled. Click the button again to try again.** | You closed the provider's window before the end. Click the provider button again. |
| **Your browser blocked the sign-in window. Allow pop-ups for this site, then click the button again.** | Your browser blocks pop-ups for this address. Allow them for this site in the browser, then click the provider button again. |
| **Your account is not known to Astrolabe yet. Ask your administrator to add you, then try again.** | The provider knows you, Astrolabe does not. Click **Request access** under **Astrolabe**: see [Request access when sign-in is refused](request-access.md). |
| **Your session has expired. Sign in again.** | Sign in again with the provider button or with your username and password. |
| **Astrolabe could not reach the sign-in provider. Try again in a minute. If it keeps happening, tell your administrator.** | The provider does not answer. Wait a minute, then try again. If it keeps happening, tell your administrator. |
| **This sign-in method is not set up correctly. Tell your administrator.** | The provider settings are wrong. Your administrator checks them in **Administration › Authentication**. |
| **Sign-in failed. Try again. If it keeps happening, tell your administrator.** | Astrolabe cannot tell the cause. Try again, then tell your administrator. |
| The window **Request Access to Astrolabe** opens: **You don't have an active license for Astrolabe. Would you like to request access?** | Astrolabe refused your sign-in for lack of an active license. Click **Request Access**: see [Request access when sign-in is refused](request-access.md). |
| **The mail server does not offer an encrypted connection, which Astrolabe requires to send a password.** in the window **Reset Administrator Password** | The mail server does not offer a secure connection (STARTTLS). Ask your mail provider for a server and a port that do, usually port `587`, then enter them in **Host** and **Port** on the **Mail server** tab of **Administration › General**. |
| **The mail server cannot be reached.** in the window **Reset Administrator Password** | **Host** is misspelled, or the server does not answer. Check **Host** and **Port** on the **Mail server** tab of **Administration › General**. |
| **The mail server refuses connections on this port.** in the window **Reset Administrator Password** | The **Port** is not the one the mail server listens on. Check **Port** on the **Mail server** tab of **Administration › General**, usually `587`. |
| **The mail server refused the user name or password.** in the window **Reset Administrator Password** | **User** or **Password** is wrong. Check them on the **Mail server** tab of **Administration › General**. |
| **The mail server is not set up yet.** in the window **Reset Administrator Password** | No mail server is saved yet: [set the mail server](../../../administration/general/set-the-mail-server.md). |
| **Email service is unavailable.** in the window **Reset Administrator Password** | Astrolabe could not send the message. Check **Host**, **Port**, **User** and **Password** on the **Mail server** tab of **Administration › General**: see [Reset the administrator password](astrolabe-account/reset-the-password.md). |
| **Invalid or expired code.** after **Verify code** | The code is wrong or too old. Click **Close**, click **Forgot password?** again, click **Send verification code** and use the code of the new message. |

## In Administration › Authentication

| What you see | What to do |
| --- | --- |
| **Client ID is required** under a field | Fill in the field. Every field marked **(Required)** must have a value. |
| **Client Secret is required** under a field | Same: enter the Client Secret. |
| The provider refuses the sign-in because of the redirect address | The address given to the provider must be exactly `https://<your-astrolabe-address>/api/auth/<provider>/handler/frame`. Copy it from the **?** next to **Client ID**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the provider.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/azure-devops/faq.md -->

# Azure DevOps catalog FAQ

### How often does the catalog read Azure DevOps?

Every 30 minutes. The **Catalog collection** table of **Administration › Catalog** shows **Last run** and
**Next run**. To read it now, click **Run the Azure DevOps collection now**.

### Can I import only some projects or repositories?

Yes. In **Project**, write the name of the project instead of `*`. In **Repository**, write a prefix
followed by `*`, for example `service-*`. See
[Import your Azure DevOps repositories](import-repositories.md#-configure-the-azure-devops-provider).

### Which file does Astrolabe look for?

The file named in **Path**, in each repository: `/catalog-info.yaml` by default.

### Which token reads the repositories?

The token of the [Azure DevOps integration](../../Integration/azure-devops/add-the-integration.md). The
provider has no token field of its own.

### Where do I see that something is wrong?

On the **Azure DevOps** card, in the **Catalog collection** table, and in **Administration › Problems**.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/azure-devops/import-repositories.md -->

# Import your Azure DevOps repositories

Astrolabe reads the `catalog-info.yaml` file of your Azure DevOps repositories and adds them to the
catalog.

You set it up once, as an administrator.

## Before you start

The catalog reads Azure DevOps with the token of the **Azure DevOps integration**. Add it first: see
[Add the Azure DevOps integration](../../Integration/azure-devops/add-the-integration.md).

Until it is added, the **Azure DevOps** card of **Administration › Catalog** is greyed out, with
**Configure the azure integration first: without it, this provider cannot read anything.**

## 🔧 Configure the Azure DevOps provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **Azure DevOps** card, click **Configure**.

4. In **Host**, keep the host of your integration, for example `dev.azure.com`.

5. Fill in the other fields.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Organization** | The organization, as in `https://dev.azure.com/<organization>`. | `acme` |
   | **Project** | The project to scan. `*` for every project of the organization. | `*` |
   | **Repository** | The repositories to scan. `*` for all, or a prefix followed by `*`. | `*` |
   | **Path** | Where the descriptor file sits in each repository. | `/catalog-info.yaml` |
   | **Branch** | Optional. The branch to read the descriptor from. Empty: each repository's default branch. | `main` |

6. Click **Install**.

The window **Reloading configuration** says **Please wait while the instance is reloading...**. Then the
page comes back.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## ▶️ Run the collection now

The catalog reads Azure DevOps every 30 minutes. You don't want to wait?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the row that starts with **Azure DevOps**, click **Run the Azure DevOps collection now** in the
   **Actions** column.

3. Wait half a minute, then reload the page. **State** shows the result of the run, and **Detail** says why
   when it failed.

Your repositories are then in **Catalog**. This step was not checked on a live instance.

✅ That's it!

Next: [Questions about the Azure DevOps catalog](faq.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/azure-devops/troubleshooting.md -->

# Common problems with the Azure DevOps catalog

| What you see | What to do |
| --- | --- |
| On the **Azure DevOps** card, **Configure the azure integration first: without it, this provider cannot read anything.** | Add the integration first: [Add the Azure DevOps integration](../../Integration/azure-devops/add-the-integration.md). |
| In **Configure Azure DevOps**, under **Host**, `The integration of this host does not connect right now: The source refused the token (401): check it in Administration › Company connections. The collection will fail until it is fixed in Administration › Company connections.` | The token of the integration is wrong or expired. Replace it in **Administration › Company connections › Azure DevOps**. |
| In the **Catalog collection** table, **State** says **Failed**, and **Detail** says `The source refused the token (401): check it in Administration › Company connections.` | Same: replace the token, then click **Run the Azure DevOps collection now**. |
| In **Administration › Problems**: `refuses the credentials (203). The token may be wrong or expired.` or `refuses the credentials (302). The token may be wrong or expired.` | Same. Click **Fix it**, replace the token, then click **Check again**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-cloud/faq.md -->

# Bitbucket Cloud catalog FAQ

### How often does the catalog read Bitbucket Cloud?

Every 30 minutes. The **Catalog collection** table of **Administration › Catalog** shows **Last run** and
**Next run**. To read it now, click **Run the Bitbucket Cloud collection now**.

### Can I import only some repositories?

Yes. Fill in **Project Key Regex** to keep the projects whose key matches, and **Repo Slug Regex** to keep
the repositories whose slug matches. Empty means all of them. See
[Import your Bitbucket Cloud repositories](import-repositories.md#the-other-fields).

### Which file does Astrolabe look for?

The file named in **Catalog Path**, in each repository: `/catalog-info.yaml` by default.

### Which token reads the repositories?

The token of the [Bitbucket Cloud integration](../../Integration/bitbucket-cloud/add-the-integration.md).
The provider has no token field of its own.

### Where do I see that something is wrong?

On the **Bitbucket Cloud** card, in the **Catalog collection** table, and in **Administration › Problems**.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-cloud/import-repositories.md -->

# Import your Bitbucket Cloud repositories

Astrolabe reads the `catalog-info.yaml` file of the repositories of your Bitbucket Cloud workspace and adds
them to the catalog.

You set it up once, as an administrator.

## Before you start

The catalog reads Bitbucket Cloud with the token of the **Bitbucket Cloud integration**. Add it first: see
[Add the Bitbucket Cloud integration](../../Integration/bitbucket-cloud/add-the-integration.md).

Until it is added, the **Bitbucket Cloud** card of **Administration › Catalog** is greyed out, with
**Configure the bitbucketCloud integration first: without it, this provider cannot read anything.**

## 🔧 Configure the Bitbucket Cloud provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **Bitbucket Cloud** card, click **Configure**.

4. In **Workspace**, enter your workspace, as in `https://bitbucket.org/<workspace>`. For example `acme`.

5. Click **Install**.

The window **Reloading configuration** says **Please wait while the instance is reloading...**. Then the
page comes back.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## The other fields

| Field | What it does |
| --- | --- |
| **Catalog Path** | Where the descriptor file sits in each repository. Default: `/catalog-info.yaml`. |
| **Project Key Regex** | Only the projects whose key matches are imported, for example `^team-.*`. Empty: all of them. |
| **Repo Slug Regex** | Only the repositories whose slug matches are imported, for example `^team-.*`. Empty: all of them. |
| **Repositories Per Page** | How many repositories Astrolabe asks Bitbucket Cloud for at a time. Empty: Bitbucket's default. |

## ▶️ Run the collection now

The catalog reads Bitbucket Cloud every 30 minutes. You don't want to wait?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the **Bitbucket Cloud** row, click **Run the Bitbucket Cloud collection now** in the **Actions**
   column.

3. Wait half a minute, then reload the page. **State** shows the result of the run, and **Detail** says why
   when it failed.

Your repositories are then in **Catalog**. This step was not checked on a live instance.

✅ That's it!

Next: [Questions about the Bitbucket Cloud catalog](faq.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-cloud/troubleshooting.md -->

# Common problems with the Bitbucket Cloud catalog

| What you see | What to do |
| --- | --- |
| On the **Bitbucket Cloud** card, **Configure the bitbucketCloud integration first: without it, this provider cannot read anything.** | Add the integration first: [Add the Bitbucket Cloud integration](../../Integration/bitbucket-cloud/add-the-integration.md). |
| In the **Catalog collection** table, **State** says **Failed**, and **Detail** says `The source refused the token (401): check it in Administration › Company connections.` | The token of the integration is wrong or expired. Replace it in **Administration › Company connections › Bitbucket Cloud**, then click **Run the Bitbucket Cloud collection now**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-server/faq.md -->

# Bitbucket Server catalog FAQ

### How often does the catalog read Bitbucket Server?

Every 30 minutes. The **Catalog collection** table of **Administration › Catalog** shows **Last run** and
**Next run**. To read it now, click **Run the Bitbucket Server collection now**.

### Can I import only some repositories?

Yes. Fill in **Project Key Regex** to keep the projects whose key matches, and **Repo Slug Regex** to keep
the repositories whose slug matches. Empty means all of them. See
[Import your Bitbucket Server repositories](import-repositories.md#the-other-fields).

### Which file does Astrolabe look for?

`catalog-info.yaml` at the root of each repository. **Catalog Path** changes where it looks.

### Are archived repositories imported?

Yes, unless you tick **Skip Archived Repos**.

### Which token reads the repositories?

The token of the [Bitbucket Server integration](../../Integration/bitbucket-server/add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-server/import-repositories.md -->

# Import your Bitbucket Server repositories

Astrolabe reads the `catalog-info.yaml` file of your Bitbucket Server repositories and adds them to the
catalog.

You set it up once, as an administrator.

## Before you start

The catalog reads Bitbucket Server with the token of the **Bitbucket Server integration**. Add it first:
see [Add the Bitbucket Server integration](../../Integration/bitbucket-server/add-the-integration.md).

Until it is added, the **Bitbucket Server** card of **Administration › Catalog** is greyed out, with
**Configure the bitbucketServer integration first: without it, this provider cannot read anything.**

## 🔧 Configure the Bitbucket Server provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **Bitbucket Server** card, click **Configure**.

4. In **Host**, pick your server in the list. It is the host of your integration.

5. Click **Install**.

The window **Reloading configuration** says **Please wait while the instance is reloading...**. Then the
page comes back.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## The other fields

| Field | What it does |
| --- | --- |
| **Catalog Path** | Where the descriptor file sits in each repository. Default: `/catalog-info.yaml`. |
| **Project Key Regex** | Only the projects whose key matches are imported, for example `^team-.*`. Empty: all of them. |
| **Repo Slug Regex** | Only the repositories whose slug matches are imported, for example `^team-.*`. Empty: all of them. |
| **Skip Archived Repos** | Leaves out archived repositories. |
| **Validate Locations Exist** | Checks that the descriptor file exists before registering it. |

## ▶️ Run the collection now

The catalog reads Bitbucket Server every 30 minutes. You don't want to wait?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the **Bitbucket Server** row, click **Run the Bitbucket Server collection now** in the **Actions**
   column. A message says **Collection started**.

3. Wait a minute, then reload the page. **State** shows the result of the run, and **Detail** says why when it failed.

Your repositories are then in **Catalog**. This step was not checked on a live instance.

✅ That's it!

Next: [Questions about the Bitbucket Server catalog](faq.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/bitbucket-server/troubleshooting.md -->

# Common problems with the Bitbucket Server catalog

| What you see | What to do |
| --- | --- |
| On the **Bitbucket Server** card, **Configure the bitbucketServer integration first: without it, this provider cannot read anything.** | Add the integration first: [Add the Bitbucket Server integration](../../Integration/bitbucket-server/add-the-integration.md). |
| In **Configure Bitbucket Server**, under **Host**, `The integration of this host does not connect right now: No server answers to this host name: check its spelling in the integration (host and URLs). If it is right, tell your company's Astrolabe administrator. The collection will fail until it is fixed in Administration › Company connections.` | Fix the host of the integration in **Administration › Company connections › Bitbucket Server**. |
| In the **Catalog collection** table, **State** says **Failed**, and **Detail** says `No server answers to this host name: check its spelling in the integration (host and URLs). If it is right, tell your company's Astrolabe administrator.` | Same: fix the integration, then click **Run the Bitbucket Server collection now**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/github/faq.md -->

# GitHub catalog FAQ

### If I enter one organization, are all its repositories imported?

Every repository that has a `catalog-info.yaml` file, and that your filters let through. A repository
without the file adds nothing.

### Are the users and teams of my organization imported?

Yes, when **Import GitHub members and teams** is ticked on the **GitHub** card. See
[Import your GitHub repositories](import-repositories.md#-members-and-teams).

### Can I import several organizations?

The **GitHub** card takes one **Organization**. For a component of another organization, use
**Register an existing component** in **Catalog**: see
[Show the GitHub tab](../../Integration/github/show-the-tab.md#3--put-the-component-in-the-catalog).

### How do I read only a few repositories?

Write a **Repository Regex** that matches their names, for example `^(shop-api|shop-web)$`.

### How often does the catalog read GitHub?

Every 30 minutes. To read it now, click **Run the GitHub collection now** in **Administration ›
Catalog**.

### If I leave Branch empty, does it read every branch?

No. Each repository is read on its default branch, and only on it.

### Does the GitHub tab appear on the imported components?

Yes, when their `catalog-info.yaml` carries the `github.com/project-slug` annotation. See
[Show the GitHub tab](../../Integration/github/show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/github/import-repositories.md -->

# Import your GitHub repositories

Astrolabe reads the `catalog-info.yaml` file of the repositories of a GitHub organization and adds them
to the catalog.

You set it up once, as an administrator. Then the catalog fills itself every 30 minutes.

## Before you start

The catalog reads GitHub with the token of the **GitHub integration**. Add it first: see
[GitHub › Add the GitHub integration](../../Integration/github/add-the-integration.md).

The token needs the **`repo`**, **`read:org`** and **`read:user`** scopes.

## 🔧 Configure the GitHub provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **GitHub** card, click **Configure**.

4. In **Organization**, enter the organization to read, as in `https://github.com/<organization>`, for
   example `acme`.

5. Leave **Host** on `github.com`.

6. At the bottom of the form, tick **Import GitHub members and teams**.

7. Click **Install**.

The window **Reloading configuration** says **Please wait while the instance is reloading...**. Then
the page comes back.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## 👥 Members and teams

**Import GitHub members and teams** also imports the members and the teams of the organization. They
can then sign in with GitHub and own components: `owner: group:github/<team>`. Hover the **?** next to
it to read it. It needs the **Organization** above: without one, the form refuses with
`Organization is required`. The token needs the **`read:org`** and **`read:user`** scopes.

To see them, click **Catalog** in the left sidebar, then the **Users** or **Groups** tab.

If the box is not ticked, only repositories are imported: nobody can sign in with GitHub, and the
catalog holds no GitHub user. To change it later, click **Configure** on the **GitHub** card again,
tick or untick the box, and click **Update Configuration**.

## The other fields

| Field | What it does |
| --- | --- |
| **GitHub App ID** | Empty: Astrolabe reads with the token. |
| **Host** | `github.com`. For GitHub Enterprise, its domain name, written exactly as in the GitHub integration. |
| **Catalog Path** | Where the file sits in each repository. Empty: `/catalog-info.yaml`. Wildcards allowed: `/**/catalog-info.yaml`. |
| **Branch** | The branch to read. Empty: each repository's default branch. |
| **Repository Regex** | Only the repositories whose name matches, for example `^team-.*`. |
| **Include Forks** | Ticked: forked repositories are imported too. |
| **Include Archived Repositories** | Ticked: archived repositories are imported too. |
| **Include Topics** | Click **Add Include Topics** and type a topic: only the repositories with one of these topics. |
| **Exclude Topics** | Click **Add Exclude Topics** and type a topic: the repositories with it are left out. |
| **Visibility** | Click **Add Visibility**: only repositories with these visibilities (public, private, internal). Empty: all. |
| **Validate Locations Exist** | Ticked: checks that the file exists before adding it. Slower, but no error for a repository without one. |
| **Repositories Per Page** | How many repositories are read per request. Default: 25. |

## ▶️ Run the collection now

You don't want to wait 30 minutes?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the **GitHub** row, click **Run the GitHub collection now** in the **Actions** column.

3. Reload the page. **State** says **Done**. **Detail** says how many files were found, for example
   **3 catalog files found**.

Your components are now in **Catalog**.

✅ That's it!

Next: [show the GitHub tab on a component](../../Integration/github/show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/github/troubleshooting.md -->

# Common problems with the GitHub catalog

| What you see | What to do |
| --- | --- |
| Under **Organization**: `Organization is required` | Enter the organization, as in `https://github.com/<organization>`. |
| In the **Catalog collection** table, **State** says **Done** and **Detail** says `Nothing found: no catalog-info.yaml on the branch read, or the token is not a member of the projects.` | No repository passed the filters. Check **Repository Regex**, **Branch** and **Catalog Path**, and that the token's account can see the repositories. |
| **State** says **Failed** and **Detail** says `The collection failed for a reason Astrolabe could not identify. Run it again; if it fails again, tell your company's Astrolabe administrator.` | With **Import GitHub members and teams** ticked, the token is usually missing the **`read:user`** scope: in GitHub, open the token, tick **`read:user`** and click **Update token** (the token stays the same, nothing to paste again). Otherwise, check that **Organization** is written as in `https://github.com/<organization>`, and that the token's account can see it. Then click **Run the GitHub collection now**. |
| **Administration › Problems** lists `Catalog collection`, `The last collection failed. Run it again from the Catalog screen.` | Click **Fix it**: it leads to **Administration › Catalog**. Fix the provider, then run the collection again. |
| **State** says **Unknown** and **Detail** says `Ran before Astrolabe restarted: its outcome is not known. Run it now to see it.` | Click **Run the GitHub collection now**. |
| You only see **administrator** in **Catalog**, under **Users** | **Import GitHub members and teams** is not ticked. In **Administration › Catalog**, click **Configure** on the **GitHub** card, tick **Import GitHub members and teams** (with **Organization** filled in), click **Update Configuration**, then **Run the GitHub collection now**. |
| Someone who signs in with GitHub reads `Your GitHub account is not in the Astrolabe catalog yet. Ask your Astrolabe administrator to tick « Import GitHub members and teams » in Administration › Catalog › GitHub.` | Same fix: tick **Import GitHub members and teams**, as above. |
| A new repository or a changed `catalog-info.yaml` does not show up | The catalog reads GitHub every 30 minutes. Click **Run the GitHub collection now**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the repository.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/gitlab/faq.md -->

# Questions about GitLab owners

### How do I make `owner` name a real GitLab group?

[Import your GitLab groups](import-groups.md), then write `owner: group:gitlab/<name>` in the
`catalog-info.yaml`. The `group:gitlab/` prefix is required. With `owner: paiement-api` alone, Astrolabe
looks among its own groups and finds nothing.

### If I enter one group, is only that group imported?

No. That group **and all its subgroups**, at every level.

### My company has several top-level groups, with no common parent. How do I get them all?

Leave **Group** empty: on a self-managed GitLab, every group comes in. On gitlab.com, a group is
required: there, you import one top-level group.

### The group is several levels down. How do I write it?

One separator per level.

- **Group** set to `acme`: `acme/paiement/api/v2` → `owner: group:gitlab/paiement-api-v2`
- **Group** empty: `acme/paiement/api/v2` → `owner: group:gitlab/acme.paiement.api.v2`

63 characters at most. In doubt, [copy the name from the catalog](give-an-owner.md#-find-the-exact-name).

### What happens if I name a group that was not imported?

The component is imported all the same. Its page shows a warning:

`This entity has relations to other entities, which can't be found in the catalog.`
`Entities not found are: group:gitlab/does-not-exist`

**OWNER** shows `gitlab/does-not-exist`. The link leads to **Warning: Entity not found**. Nobody owns
the component: it counts for no team.

**Administration › Problems** lists it too, in a **Catalog** block, with every component that names the
same group. See [Fix a component whose owner is not found](../../../../administration/problems/fix-a-missing-owner.md).

### Why does Catalog › Groups show `api` and not `paiement-api`?

The list shows the group's GitLab name. `owner` needs the catalog name, which carries its parents. Open
the group and copy its **Entity Ref**.

### How often does the catalog read GitLab?

Every 30 minutes. To read it now, click the play button (**Run the GitLab collection now**) in the
**Catalog collection** table of **Administration › Catalog**.

### Why does the screen say the teams will be renamed when I change Group?

Because the name of an imported team comes from its path **under** the **Group**. With `acme`,
`acme/paiement/api` is `paiement-api`; with `acme/paiement`, it is `api`. The owner of your components must
follow. See [Change the group later](import-projects.md#change-the-group-later).

### If I leave Branches empty, does it read every branch?

No. Each project is read on its own default branch, and only on it. To read several branches, list them in
**Branches**: for example `master` and `backstage` if your projects keep their `catalog-info.yaml` on one or
the other. Astrolabe reads each project on each branch of the list.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/gitlab/give-an-owner.md -->

# Give a component its GitLab owner

Each component names its owner in its `catalog-info.yaml`. With your GitLab groups imported, it can be a
real GitLab group.

You need [the import of your GitLab groups](import-groups.md) first.

## ✏️ Write the owner

In the component's `catalog-info.yaml`, in GitLab, write the group in `spec.owner`, **with** the
`group:gitlab/` prefix:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api
spec:
  type: service
  lifecycle: production
  owner: group:gitlab/paiement-api
```

At the next collection, the component page shows the group under **OWNER**, in **About**.

## Build the group name

One separator per level of the GitLab path. Which one depends on the **Group** field of the provider.

| Group field | GitLab group | Write |
| --- | --- | --- |
| `acme` | `acme/paiement/api` | `group:gitlab/paiement-api` |
| `acme` | `acme/paiement/api/v2` | `group:gitlab/paiement-api-v2` |
| Empty | `acme/paiement/api` | `group:gitlab/acme.paiement.api` |
| Empty | `acme/paiement/api/v2` | `group:gitlab/acme.paiement.api.v2` |

With a group set, the name starts **below** it, with a `-` per level. With **Group** empty, it is the full
path, with a `.` per level.

:::warning With Group empty, a path that holds a « . » is left out
A `.` must only ever stand for a `/`. Otherwise two different groups could share a name, and one would
take the components of the other.
:::

## 🔎 Find the exact name

In doubt? Copy it from the catalog.

1. Open **Catalog**, then the **Groups** tab.

2. Click the group. The list shows its GitLab name (`api`), not the name to write.

3. In the group card, copy the line above **Entity Ref**, for example `group:gitlab/paiement-api`.

4. Paste it as is in `owner`.

The same page shows the **Parent Group**, the components the group owns (**Ownership**) and its
members.

✅ That's it!

Something does not match? Read the [frequently asked questions](faq.md) and the
[common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/gitlab/import-groups.md -->

# Import your GitLab groups

Your GitLab groups can come into the catalog, with their members.

A component can then name a real GitLab group as its owner.

## 👥 Turn on the import

1. Open **Administration › Catalog**, then **Configure** on the **GitLab** card.

2. Tick **Import GitLab groups and their members**.

3. Click **Install**, or **Update Configuration** if the provider was already installed.

4. In the **Catalog collection** table, on the **GitLab (groups and users)** row, click the play button
   (**Run the GitLab groups and users collection now**).

5. Reload the page. **State** says **Done**. **Detail** says what came in, for example
   **3 groups and 1 user imported**.

Your groups are in **Catalog**, on the **Groups** tab.

## Which groups come in

It depends on the **Group** field.

| Group | Groups imported |
| --- | --- |
| A group, for example `acme` | `acme` and **all** its subgroups, at every level |
| Empty | **Every** group of your GitLab, all top-level groups included. Self-managed GitLab only. |

Other fields of the same form narrow or widen the import:

| Field | What it does |
| --- | --- |
| **Group Regex** | Only the groups whose full path matches, for example `^acme/team-.*`. Empty: all of them. |
| **User Regex** | Only the users whose username matches. Empty: all of them. |
| **Restrict Users to Group** | Only the users of this group path, for example `acme/staff`. |
| **Allow Inherited Memberships** | Also counts a person as a member of a subgroup when they belong to a parent group. |
| **Include Users Without a Seat** | Also imports users who take no paid seat. |
| **Import Relations** | Links each group to its parent and to its members in the catalog. |

:::tip Several top-level groups?
Your teams are spread over several top-level groups, with no common parent? Leave **Group** empty: they
all come in.
:::

:::warning On gitlab.com, Group is required
Without a group, it would be every public group of gitlab.com. Astrolabe refuses, under the field:

`On gitlab.com, importing GitLab groups needs a Group: without one it would be every public group of gitlab.com. Enter your top-level group (for example acme); its subgroups come with it.`
:::

## Two rules from Backstage

:::warning A group with no direct member is not imported
A group whose people are only members of its subgroups, or of its parent, does not appear.
:::

:::warning A name is 63 characters at most
A longer group path is refused. The group is missing from the catalog.
:::

✅ That's it!

Now [give each component its owner](give-an-owner.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/gitlab/import-projects.md -->

# Import your GitLab projects

Astrolabe reads the `catalog-info.yaml` file of your GitLab projects and adds them to the catalog.

You set it up once, as an administrator. Then the catalog fills itself every 30 minutes.

## Before you start

The catalog reads GitLab with the token of the **GitLab integration**. Add it first: see
[GitLab › Add the GitLab integration](../../Integration/gitlab/add-the-integration.md).

The token needs the **`read_api`** and **`read_repository`** scopes.

## 🔧 Configure the GitLab provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **GitLab** card, click **Configure**.

4. In **Host**, pick your GitLab in the list. It is the host of your integration.

5. In **Group**, enter the group to read, as in `https://<host>/<group>`. Its subgroups come with it.

   :::tip This field also names your teams
   Imported teams are named after their path **under** this group: with `acme`, the group
   `acme/paiement/api` becomes `paiement-api`. Components write that name in `owner`. So pick the
   top group of your company. See [Give a component its GitLab owner](give-an-owner.md).
   :::

6. Click **Install**.

The window **Reloading configuration** says **Please wait while the instance is reloading...**. Then the
page comes back.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## ✏️ Change the group later {#change-the-group-later}

1. Open **Administration › Catalog**, then **Configure** on the **GitLab** card.

2. In **Group**, type the new group. As soon as it differs from the saved one, a warning shows under the
   field, for example with `acme` saved and `acme/paiement` typed:

   `The teams already imported will be renamed, and the owner of the components that name them will no longer be found until you update it. Example: acme/paiement/api was paiement-api and becomes api.`

3. Click **Update Configuration**.

4. In each `catalog-info.yaml`, write the new team name in `owner`. See
   [Give a component its GitLab owner](give-an-owner.md).

Type the saved group back and the warning goes away.

## The other fields

| Field | What it does |
| --- | --- |
| **Only projects I am a member of** | Only the projects of the token's user. Recommended on gitlab.com. |
| **Branches** | The branches to read, one per row: click **Add Branches**, type `master`, click **Add Branches** again, type `backstage`. Empty: each project's default branch. No `/` in a name. **Remove** takes a branch out. |
| **Catalog File** | The file to read at the root of each project. Default: `catalog-info.yaml`. |
| **Project Regex** | Only the projects whose name matches, for example `^team-.*`. |
| **Skip Forked Repositories** | Leaves out forked projects. |
| **Import GitLab groups and their members** | Also imports your groups. See [Import your GitLab groups](import-groups.md). |
| **Excluded Repositories** | Projects to leave out, one path per line, for example `acme/sandbox`. |
| **Topics** | Only the projects that carry one of these GitLab topics, one per line. |
| **Include Archived Repositories** | Also imports archived projects. |
| **Fallback Branch** | The branch to read when the catalog file is not on a project's default branch. |
| **Use GitLab Search** | Finds the projects through GitLab search instead of listing every project in scope. |

## ▶️ Run the collection now

You don't want to wait 30 minutes?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the **GitLab** row, in the **Actions** column, click the play button (**Run the GitLab collection now**; once you also import groups, it is **Run the GitLab projects collection now**).

3. Don't reload the page. **State** turns to **Running**, then to **Done**. **Detail** says how many files
   were found, for example **3 catalog files found**. The play of the **GitLab** row starts only that row:
   see [Run a catalog collection now](../../../../administration/catalog/run-a-collection.md).

The **GitLab (groups and users)** row, just above, appears once you turned on
**Import GitLab groups and their members**. Its **Detail** says what came in, for example **3 groups and 1
user imported**.

Your components are now in **Catalog**.

✅ That's it!

To name a real GitLab group as the owner of each component, read
[Import your GitLab groups](import-groups.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/gitlab/troubleshooting.md -->

# Common problems with the GitLab catalog

| What you see | What to do |
| --- | --- |
| Under **Group**: `On gitlab.com, importing GitLab groups needs a Group: without one it would be every public group of gitlab.com. Enter your top-level group (for example acme); its subgroups come with it.` | On gitlab.com, enter your top-level group. |
| On a component: `This entity has relations to other entities, which can't be found in the catalog.` | The `owner` group is not in the catalog. Check the `group:gitlab/` prefix, then [copy the name from the catalog](give-an-owner.md#-find-the-exact-name). |
| A GitLab group is missing from **Catalog › Groups** | Give it a direct member in GitLab. Check it is under **Group**, its name is 63 characters at most and, with **Group** empty, its path holds no `.`. Then run the collection again. |
| The **GitLab** card says `Ran before Astrolabe restarted: its outcome is not known. Run it now to see it.` | Click the play button (**Run the GitLab collection now**) in the **Catalog collection** table. |
| A new project or a changed `owner` does not show up | The catalog reads GitLab every 30 minutes. Click the play button (**Run the GitLab collection now**). |
| The **GitLab** card says `Configure the GitLab integration first: without it, this provider cannot read anything.` | Add the GitLab integration first: [GitLab › Add the GitLab integration](../../Integration/gitlab/add-the-integration.md). |
| In the **Catalog collection** table, **Detail** says `The source does not know what the settings name (404): check the Group, the Organization or the Project in the provider's settings.` | The group does not exist, or is misspelled. In **Group**, write it as in `https://<host>/<group>`. |
| In **Administration › Problems**, a **Catalog** block: `2 components name an owner missing from the catalog: group:gitlab/does-not-exist.` | The `owner` group is not in the catalog. [Copy the name from the catalog](give-an-owner.md#-find-the-exact-name), then see [Fix a component whose owner is not found](../../../../administration/problems/fix-a-missing-owner.md). |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component or the group.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/microsoft-entra-id/faq.md -->

# Microsoft Entra ID FAQ

## Which permissions does the app registration need?

The application permissions **`User.Read.All`** and **`GroupMember.Read.All`**, with admin consent.
Astrolabe only reads.

## Is this the same app registration as the Microsoft sign-in?

The form of the sign-in asks for the same three values (tenant, client ID, client secret). See
[Microsoft sign-in](../../Authentication/microsoft/set-up-sign-in.md).

## How do I change the secret?

On **Administration › Catalog**, click **Configure** on the **Microsoft Graph** card. Next to **Client
Secret**, click **Replace**, paste the new Value, then click **Update Configuration**.

## Where do I see that a collection failed?

In **Administration › Problems**, under **Catalog collection**, and in the **Catalog collection** table
of **Administration › Catalog**.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/microsoft-entra-id/import-users-and-groups.md -->

# Import your Entra ID users and groups

Astrolabe reads the users and the groups of your Microsoft Entra ID with an app registration and adds
them to the catalog.

You set it up once, as an administrator.

*The collection itself was not checked with an app registration that is allowed to read the
directory. This step was not checked on a live instance.*

## Before you start

You need an app registration in Microsoft Entra ID, with:

- the **application permissions** `User.Read.All` and `GroupMember.Read.All`, with admin consent;
- a client secret.

Keep three values: its **Directory (tenant) ID** and its **Application (client) ID**, both on its
Overview page, and the **Value** of the client secret (*Certificates & secrets*).

## 🔧 Configure the Microsoft Graph provider

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Catalog**. The **Providers** tab opens.

3. On the **Microsoft Graph** card, click **Configure**.

4. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter |
   | --- | --- |
   | **Target URL** | Leave `https://graph.microsoft.com/v1.0`, unless you use a national cloud |
   | **Authority URL** | Leave `https://login.microsoftonline.com`, unless you use a national cloud |
   | **Tenant ID** | The Directory (tenant) ID |
   | **Client ID** | The Application (client) ID |
   | **Client Secret** | The Value of the client secret |

5. Click **Install**. A window says **Reloading configuration**, then the page comes back.

:::tip Fill the three values before you click Install
**Tenant ID**, **Client ID** and **Client Secret** are needed for the provider to start.
:::

## 🔍 Import only some users and groups

The same form has two optional sections. Leave them empty to import everything.

| Field | What it does | Example |
| --- | --- | --- |
| **UserGroupMember › User Group Member Filter** | Only the users who are members of the groups matching this OData filter | `displayName eq 'Engineering'` |
| **UserGroupMember › User Group Member Search** | The same, as a search expression | `"displayName:Engineering"` |
| **Group › Group Filter** | Only the groups matching this OData filter | `securityEnabled eq true` |
| **Group › Group Search** | Only the groups matching this search | `"displayName:team"` |
| **Group › Group Expand** | Extra group properties to fetch | `member` |
| **Group › Group Select Fields** | The group properties to read: click **Add Group Select Fields**, one per entry | `id`, `displayName`, `description` |

## ▶️ Run the collection now

You don't want to wait for the next run?

1. On **Administration › Catalog**, find the **Catalog collection** table.

2. On the **Microsoft Graph · default** row, click **Run the Microsoft Graph collection now** in the
   **Actions** column.

3. Reload the page. **State** says how it went and **Detail** says why when it failed.

Your users and groups are then in **Catalog**.

✅ That's it!

Next: [Common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Catalogue/microsoft-entra-id/troubleshooting.md -->

# Common problems with the Microsoft Entra ID catalog

| What you see | What to do |
| --- | --- |
| In the **Catalog collection** table, **State** `Failed` and **Detail** `The collection failed for a reason Astrolabe could not identify. Run it again; if it fails again, tell your company's Astrolabe administrator.` | Run it again with **Run the Microsoft Graph collection now**. If it fails again, check in Microsoft Entra ID that the app registration has the application permissions `User.Read.All` and `GroupMember.Read.All`, with admin consent, and that the client secret has not expired. |
| In **Problems**, under **Catalog collection**: `The last collection failed. Run it again from the Catalog screen.` | Same as above. |
| **State** `Unknown` and **Detail** `Ran before Astrolabe restarted: its outcome is not known. Run it now to see it.` | Click **Run the Microsoft Graph collection now**. |
| The **Microsoft Graph** card says `Did not start: Astrolabe refused its settings when it started. Check its host and its integration; if they look right, tell your company's Astrolabe administrator.` | Click **Configure** and check **Tenant ID**, **Client ID** and **Client Secret**: all three must be filled. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/add-the-dashboard-card.md -->

# Add the Applications card to your dashboard

The **Applications** card lists the Argo CD applications of the components of the catalog, on **My
Dashboard**.

## Before you start

The Argo CD integration is added ([Add the integration](add-the-integration.md)). Until then, `argocd`
is not in the **Source** list of **Add a card**.

## What it shows, and to whom

One line per application: **Key**, **Namespace**, **Resource**, **Target Revision**, **Revision**,
**Health Status**, **Sync Status**, **Last Sync Status**, **Date**.

**The applications named by a component of the catalog** with `argocd/app-name`, whoever owns the
component. The applications that no component names are not listed. Two more columns, **Owner** and
**Mine**, say who owns the component and whether it is yours (**Mine** or **Others**): to keep only your
applications, filter on **Mine** and save the filter with the card, see
[Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

*This card was not checked on a live instance: no Argo CD was connected.*

## ➕ Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick **Source** `argocd` and **Key** `Applications`.

4. Enter a **Card Name**, then click **Add**.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/add-the-integration.md -->

# Add the Argo CD integration

The integration gives Astrolabe your Argo CD host and token. Without it, the Argo CD plugin cannot
be turned on.

You do it once, as an administrator.

## Before you start

You need an Argo CD API token: see [Create a read-only Argo CD token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **ArgoCD** card, click **Configure**. The card says **Not configured**.

4. Top right, click **Add Token**.

5. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice, shown in the token list | `Argo CD` |
   | **ArgoCD instance host** | The domain name of Argo CD, with its port if it is not 443. A leading `https://` is removed on save. | `argocd.example.com` |
   | **API token** | The token | `eyJhbGciOi…` |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**

7. Click **Add**. A banner says **The configuration has changed; the server is restarting.** with a
   **Reload** button.

After a few seconds, your token is in the list, with the state **Connected**.

✅ That's it!

Next: [Show the Argo CD tab on a component](show-the-tab.md).

:::tip The test fails?
Each message is explained in [Common problems with Argo CD](troubleshooting.md).
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/create-a-token.md -->

# Create a read-only Argo CD token

Astrolabe reads Argo CD with **an API token**. The token belongs to an account that may **read
applications**, and nothing else.

:::warning The `admin` account cannot give you this token
By default, Argo CD's `admin` account only has the `login` capability. Asking for a token for it
fails with: `account 'admin' does not have apiKey capability`. Create a dedicated account instead.
:::

## 👤 Create a dedicated account

Ask your Argo CD administrator to add an account, here `astrolabe`, in the `argocd-cm` and
`argocd-rbac-cm` ConfigMaps of the `argocd` namespace:

```yaml
# argocd-cm
data:
  accounts.astrolabe: apiKey
---
# argocd-rbac-cm
data:
  policy.csv: |
    p, astrolabe, applications, get, */*, allow
```

## 🔑 Generate the token

Either in the Argo CD interface: **Settings › Accounts › astrolabe › Generate New**.

Or with the CLI:

```bash
argocd account generate-token --account astrolabe
```

Copy the token **as is**: a long string starting with `eyJ`, without `Bearer ` in front.

:::tip Why read-only?
Every Astrolabe user reads Argo CD through this token. Astrolabe never writes to Argo CD: don't give
it an administrator token.
:::

✅ That's it!

Next: [Add the Argo CD integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/faq.md -->

# Argo CD FAQ

## Can one component show several applications, one per environment?

`argocd/app-name` names **one** application. Give each environment its own component in the
catalog, each with its own `argocd/app-name`: the **Argo CD** tab of each component shows its
application.

## Why doesn't my dashboard card list every application of Argo CD?

On purpose. The card lists the applications named by a **component of the catalog**. An application
that no component names does not appear.

## Does the card list only the applications of my components?

No: it lists those of every component of the catalog. Filter the column **Mine** to keep yours: see
[Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

## Which token rights does Astrolabe need?

Read access to applications (`applications, get`). Astrolabe never writes to Argo CD. Don't give it
an administrator token: every Astrolabe user reads Argo CD through it.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/show-the-tab.md -->

# Show the Argo CD tab on a component

Each annotated component gets an **Argo CD** tab: the health of its application, its sync, its
resources and its deployments.

Two steps: turn on the plugin, annotate the component.

## What the tab shows, and to whom

**Health**, **Sync**, **Last sync** (status, date, message), **Revision**, **Source**, an **Open in
Argo CD** link, then the **Resources** and **Deployments** sub-tabs.

Anyone who can open the component sees the tab. Astrolabe reads Argo CD with **the token of the
integration**, the same for everyone.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **Argo CD** card, click the switch at the **top right of the card**. It turns on at once,
   without confirmation.

:::tip The switch is greyed out?
If the card says **Configure the Argo CD integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Argo CD integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.
:::

## 2. 🏷️ Annotate the component

In the component's `catalog-info.yaml`, name **one** Argo CD application:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    argocd/app-name: shop-api        # the application's name in Argo CD
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team  # owners see it in their dashboard card
```

:::warning One application per component
A list such as `shop-api-staging,shop-api-prod` is not a valid name: the **Argo CD** tab disappears,
with no message. See the [FAQ](faq.md).
:::

## ✅ Check

Wait a few minutes for the catalog to read the file. Then open the component from **Catalog**: the
**Argo CD** tab is after **Docs**.

✅ That's it!

Next: [Add the Applications card to your dashboard](add-the-dashboard-card.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/argocd/troubleshooting.md -->

# Common problems with Argo CD

## When you add the integration

| What you see | What to do |
| --- | --- |
| `<host> refused the credentials (401). Check the token, and that it has not expired.` | The token is wrong, revoked, expired (a token copied from a browser session lasts 24 h), truncated, or pasted with `Bearer ` in front. Generate a new API token for a dedicated account ([Create a token](create-a-token.md)) and paste it alone. |
| `Astrolabe does not trust the security certificate of <host> (often an internal certificate of your company).` | Argo CD uses a certificate signed by your company's own authority. Your Astrolabe administrator adds that authority to Astrolabe (see the Docker Hub installation guide). |
| `<host> refused the connection. Check the port, and that the service runs.` | Wrong port, or Argo CD is down. Check the host and its port (`argocd.example.com:8443`). |

## On the component page

| What you see | What to do |
| --- | --- |
| No **Argo CD** tab | Check the `argocd/app-name` annotation: one name only (lowercase letters, digits, `-` and `.`), no comma. Check that **Argo CD** is on in **Administration › Plugins**. |
| **Argo CD** switch greyed out, **Configure the Argo CD integration first** | No working Argo CD token. [Add the integration](add-the-integration.md). |
| In the tab: `The application <name> cannot be seen with your Argo CD token: check the argocd/app-name annotation, or what the token may read.` | No application has that name, **or** the token's account may not read it: Argo CD answers the same in both cases. Compare the annotation with the name in Argo CD, then the account's `policy.csv`. |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this Argo CD feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves Argo CD. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its Argo CD application.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/aws/add-the-integration.md -->

# Add the AWS integration

The integration gives Astrolabe an AWS access key. The card of **Administration › Company connections**
describes it as **AWS credentials for services such as Cost Explorer.**

You do it once, as an administrator.

## Before you start

You need the 12-digit number of your AWS account, and an access key of an IAM user with read-only access.
AWS shows the secret access key only once, when you create the key. This step was not checked on a live
instance.

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **AWS** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Account ID** | The 12-digit AWS account number | `123456789012` |
   | **Name** | A name for you, shown in the token list. Already filled with `AWS`. | `AWS` |
   | **AWS Region** | The AWS region to read from. Already filled with `eu-west-1`. | `eu-west-1` |
   | **Access Key ID** | The access key ID of an IAM user with read-only access | `AKIAIOSFODNN7EXAMPLE` |
   | **Secret Access Key** | The secret access key paired with the access key ID | |

6. Click **Test connection**.

7. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list. This step was not checked on a live instance with a working key.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/aws/troubleshooting.md -->

# Common problems with AWS

## When you add the integration

| What you see | What to do |
| --- | --- |
| `Account ID is required.` | Fill in **Account ID**. |
| `Account ID must be a 12-digit AWS account number` | Write the 12 digits of your account number, without dashes: `123456789012`. |
| `Region must be a valid AWS region (e.g., 'eu-west-1', 'us-east-1')` | Write a region name such as `eu-west-1`. |
| `Access Key ID must contain only uppercase letters and numbers` | Copy the access key ID again from AWS, without spaces. |
| `sts.eu-west-1.amazonaws.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The access key ID or the secret access key is wrong, or the key was deleted. Create a new key in AWS and enter both values again. |

The form also offers **Save anyway**, to keep the key when AWS is only unreachable for now.

## After you add it

| What you see | What to do |
| --- | --- |
| In the token list, in **State**, the message `sts.eu-west-1.amazonaws.com refused the credentials (401). Check the token, and that it has not expired.` | Edit the token and enter a valid key. |
| In **Administration › Problems**, a **Company connection** line **AWS**: `sts.eu-west-1.amazonaws.com refuses the credentials (403). The token may be wrong or expired.` | Click **Fix it**: it opens the integration. Enter a valid key. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/add-the-dashboard-card.md -->

# Add the Azure costs card to your dashboard

The **Azure costs this month** card shows the costs of the month so far, service by service, for the
whole subscription or for the resources that carry a tag.

## ➕ Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick **Source** `azureCloud`. The **Key** is **Azure costs this month**.

4. In **tag**, write a tag `key=value` such as `app=shop-api` to keep only the resources that carry
   it. Leave it empty for the whole subscription.

5. Enter a **Card Name**, then click **Add**.

:::tip The `azureCloud` source is missing?
It is only offered once the administrator has [added the Azure Cloud
integration](add-the-integration.md).
:::

## What the card shows

A table with one row per service and the columns **Service**, **Cost**, **Last Month** and **Share**.
The amounts are in the currency of the subscription, for example `24.00 EUR`.

With a tag that no resource carries, the card says **Nothing here yet** and **Azure reports no cost this month, for the subscription or for the resources carrying the tag this card names.**

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/add-the-integration.md -->

# Add the Azure Cloud integration

The integration gives Astrolabe the identifiers of your service principal and your subscription. The
**Azure** plugin and the **Azure costs this month** card need it.

You do it once, as an administrator.

## Before you start

You need the four values of [Prepare an Azure service principal](create-a-service-principal.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Azure Cloud** card, click **Configure**. The card says **Not configured**.

4. Top right, click **Add Token**.

5. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter |
   | --- | --- |
   | **Name** | A name of your choice. Prefilled with `Azure Cloud`. |
   | **Tenant ID** | The Directory (tenant) ID |
   | **Client ID** | The Application (client) ID |
   | **Client secret** | The Value of the client secret |
   | **Subscription ID** | The subscription ID |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**

7. Click **Add**. A banner says **The configuration has changed; the server is restarting.**

About a minute later, your entry is in the list, with the source **Administration** and the state
**Connected**.

✅ That's it!

Next: [Show Azure on a component](show-on-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/create-a-service-principal.md -->

# Prepare an Azure service principal

Astrolabe reads the resources and the costs of your Azure subscription with **an app registration**
of Microsoft Entra ID (a service principal). It only reads.

*This page was not checked on a live Azure portal: it lists what Astrolabe's form asks for, and where
the form says to find it.*

## What you need

| You need | Where the form says to find it |
| --- | --- |
| **Tenant ID** | The *Directory (tenant) ID*, a GUID shown on the Overview page of the app registration in Microsoft Entra ID |
| **Client ID** | The *Application (client) ID*, a GUID shown on the same Overview page |
| **Client secret** | The **Value** of a client secret, in the app registration's *Certificates & secrets*. Azure shows it once: copy the **Value**, not the *Secret ID*. |
| **Subscription ID** | The ID of the subscription to read, a GUID shown in *Subscriptions* |

## 🔑 Give it the right roles

The app registration needs two roles **on the subscription**:

- **Reader**
- **Cost Management Reader**

✅ That's it!

Next: [Add the Azure Cloud integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/faq.md -->

# Azure Cloud FAQ

## Which roles does the service principal need?

**Reader** and **Cost Management Reader**, on the subscription. Astrolabe only reads.

## Why is there no Azure tab on my component?

Because it has no `azure.com/tag-selector` annotation, or the **Azure** plugin is off in
**Administration › Plugins**. See [Show Azure on a component](show-on-a-component.md).

## Is this the same as the Azure DevOps integration?

**No.** Azure Cloud reads resources and costs of a subscription. Azure DevOps reads pipelines, pull
requests and work items: see [Azure DevOps](../azure-devops/add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/show-on-a-component.md -->

# Show Azure on a component

An annotated component gets an **Azure costs** card on its **Overview** and an **Azure** tab with its
resources and its costs.

Two steps: turn on the plugin, annotate the component.

## What it shows

| Where | What |
| --- | --- |
| **Azure costs** card of the **Overview** | **This month so far** and **Last month**, and a link **Open the cost analysis** to the Azure portal |
| **Azure** tab, sub-tab **Resources** | The resources that carry the tag, with the columns **Resource**, **Type**, **Resource group** and **Location** |
| **Azure** tab, sub-tab **Costs** | The same two amounts, and a table by **Service**: **Cost this month**, **Last month** |

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **Azure** card, click the switch at the top right of the card.

:::tip The switch is greyed out?
If the card says **Configure the Azure integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Azure integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.
:::

## 2. 🏷️ Annotate the component

In the `catalog-info.yaml` of the component, add the annotation `azure.com/tag-selector`, with **one
tag** written `key=value`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    azure.com/tag-selector: app=shop-api
spec:
  type: service
  lifecycle: production
  owner: team-a
```

The resources of your subscription must carry this tag in Azure.

## 3. 👀 See it

1. In the sidebar, click **Catalog**, then your component.

2. On the **Overview**, look for the **Azure costs** card. Click the **Azure** tab for the details.

When no resource carries the tag, the **Resources** sub-tab says **No resource carries the tag
app=shop-api.** and the **Costs** sub-tab says **No cost this month for the tag app=shop-api.**

*A component whose tag matches resources was not at hand: the filled table was not checked.*

✅ That's it!

Next: [Add the costs card to your dashboard](add-the-dashboard-card.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-cloud/troubleshooting.md -->

# Common problems with Azure Cloud

## When you add the integration

| What you see | What to do |
| --- | --- |
| Under a field: `Tenant ID is required.` | The field is empty. Fill all four values. |
| `login.microsoftonline.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The tenant, the client ID or the client secret is wrong, or the secret has expired. Copy the secret's **Value** again, or create a new secret. |
| `management.azure.com answered something unexpected (400). Check the host and the API URL. Fix the field above, or save anyway if the source is only unreachable for now.` | The **Subscription ID** is not one the service principal can read. Copy it from *Subscriptions*. |

## On a component

| What you see | What to do |
| --- | --- |
| No **Azure** tab | Add the `azure.com/tag-selector` annotation and turn on **Azure** in **Administration › Plugins**. See [Show Azure on a component](show-on-a-component.md). |
| The **Azure** card of **Plugins** says `Configure the Azure integration first` | [Add the Azure Cloud integration](add-the-integration.md). |
| `No resource carries the tag app=shop-api.` | No resource of the subscription carries this tag. Compare the annotation with the tags in the Azure portal. |

## On your dashboard

| What you see | What to do |
| --- | --- |
| The source **azureCloud** is missing from **Add a card** | The integration is not configured. [Add it](add-the-integration.md). |
| Under the field **tag** of the form, when you add the card: `The tag "foo" is not written key=value (for example app=shop-api), with letters, digits and _ . : / @ + - only.` | Write the tag as `key=value`, for example `app=shop-api`, or leave the field empty for the whole subscription. Astrolabe refuses the card until the tag is right. |
| **Nothing here yet** and `Azure reports no cost this month, for the subscription or for the resources carrying the tag this card names.` | No resource carries the tag you wrote in the card. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-devops/add-the-dashboard-cards.md -->

# Add the Azure DevOps cards to your dashboard

The Azure DevOps cards of **My Dashboards** show what **your own Azure DevOps account** sees. They
need your own token, connected once, from the card itself.

## The cards

| Key | What it says it shows |
| --- | --- |
| **Pipelines** | Azure Pipelines runs of every repository of the catalog your token reads, whoever requested them (filter on « requested by me » to keep yours) |
| **Detailed Pipelines** | Pipeline runs with timeline stages, status breakdown, and duration |
| **Pull Requests** | Pull requests of every Azure DevOps repository of the catalog your token reads, with reviewers, vote status and your role (filter on it to keep yours) |
| **To Review** | Azure DevOps work items assigned to you as reviewer |
| **My Open Work Items** | Open work items assigned to you with status |
| **WIQL Query** | Run a custom WIQL query and display matching work items |

*What the cards show once your account is connected was not checked on a live Azure DevOps
organization.*

### Which repositories, and how to keep only yours

**Pull Requests**, **Pipelines** and **Detailed Pipelines** read **every repository of the catalog**
that your token reads (the components that carry the `dev.azure.com/project-repo` annotation),
whoever owns the component and whoever started the run. Each row says what you are on it, in a column
you can filter, and the filter is saved with the card:

| Card | Column | Values | To keep yours |
| --- | --- | --- | --- |
| **Pull Requests** | **My role** | **Author**, **Reviewer**, **Other** | Remove **Other** in the **Filters** tab |
| **Pipelines** and **Detailed Pipelines** | **Requested by me** | **Yes**, **No** | Remove **No** in the **Filters** tab |

The steps are those of [Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

When Azure DevOps holds more than a card can read, the card says so above the table: `Partial list: the
read stopped at its limit for …. Azure DevOps holds more.` and names the lists concerned.

## ➕ Add a card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick **Source** `azure`, then a **Key**. The line under the key says what
   it shows.

4. For **WIQL Query** only, a field **wiql** appears: write the query to run against Azure DevOps.
   For example:

   ```
   SELECT [System.Id] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed'
   ```

5. Enter a **Card Name**, then click **Add**.

:::tip The `azure` source is missing?
It is only offered once the administrator has [added the Azure DevOps
integration](add-the-integration.md).
:::

## 🔗 Connect your Azure DevOps account

The first time, the card says **Your Azure DevOps account is not connected.** and explains that the
company token does not serve this card.

1. In the card, click **Connect my Azure DevOps account**. The window **Connect my Azure DevOps
   account** opens. It lists the rights the token needs and links to **Create my token on Azure
   DevOps**.

2. Fill in:
   - **Username**: the email address of your Azure DevOps account, for example
     `jdoe@example.com`. Astrolabe recognises you by it in Azure DevOps events.
   - **Token**: a token of your own account. See [Create an Azure DevOps token](create-a-token.md).

3. Click **Test Connection**.

4. Click **Save**. Every Azure DevOps card of your dashboard reads again.

*This step was not checked on a live instance.*

✅ That's it!

Next: [Common problems](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-devops/add-the-integration.md -->

# Add the Azure DevOps integration

The integration gives Astrolabe your Azure DevOps host, your organization and the company token. The
Azure DevOps source of the dashboard needs it.

You do it once, as an administrator.

## Before you start

You need a personal access token: see [Create an Azure DevOps token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Azure DevOps** card, click **Configure**. The card says **Not configured**.

4. Top right, click **Add Token**.

5. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice. Prefilled with `Azure Server`. | `Azure DevOps` |
   | **Azure Server host** | The domain name only, no path. A leading `https://` is removed on save. | `dev.azure.com` |
   | **Organization** | The organization, as in the address `https://dev.azure.com/<organization>`. | `acme` |
   | **Personal Access Token** | The company token | |

6. Click **Test connection**. Under a wrong host or organization, the form says why (see
   [Common problems](troubleshooting.md)). *The message for a token Azure DevOps accepts was not
   checked on a live instance.*

7. Click **Add**. If the test found a problem, the button **Save anyway** appears instead: click it
   only if the source is unreachable for now. A banner says **The configuration has changed; the
   server is restarting.**

About a minute later, click **Reload** if the banner offers it. Your token is in the list, with the
source **Administration** and its state.

:::tip Where to see what is wrong
**Administration › Problems** lists a connection that does not work, with a **Fix it** button.
:::

✅ That's it!

Next: [Add the Azure DevOps cards to your dashboard](add-the-dashboard-cards.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-devops/create-a-token.md -->

# Create an Azure DevOps token

Astrolabe reads Azure DevOps with **a personal access token**. The administrator enters one for the
company, and each user creates one for their own dashboard cards.

*This page was not checked on a live Azure DevOps organization: the rights below are the ones
Astrolabe's own screens ask for.*

## Two tokens, two uses

| Token | Entered in | Reads Azure DevOps for |
| --- | --- | --- |
| The **company's** | **Administration › Company connections › Azure DevOps** | The entity tabs, the catalog and Compass, the same for everyone |
| **Yours** | The Azure DevOps cards of **My Dashboards**, or **My Account › My accounts** | **Your** dashboard cards. The company token is never used for them. |

## 🔑 Create the token

1. In Azure DevOps, open **User settings › Personal access tokens**. From a dashboard card, the link
   **Create my token on Azure DevOps** takes you there.

2. Create a new token and give it these rights, all in read mode:

   | Token | Rights |
   | --- | --- |
   | The company's | **Code** (Read) |
   | Yours | **Code**, **Project and Team**, **Graph**, **Identity** and **Work Items** (Read) |

3. Copy the token **as is**. Azure DevOps shows it once.

✅ That's it!

Next: [Add the Azure DevOps integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-devops/faq.md -->

# Azure DevOps FAQ

## Is there an Azure DevOps tab on my components?

**No.** The integration feeds the Azure DevOps cards of **My Dashboards**. The **Azure** tab of a
component is a different integration, for Azure cloud resources and costs: see
[Azure Cloud](../azure-cloud/add-the-integration.md).

## Why does a card say "Your Azure DevOps account is not connected."?

Because the card shows what **your own** Azure DevOps account sees. The company token does not serve
it. Click **Connect my Azure DevOps account** in the card.

## Which token rights does Astrolabe need?

Read on **Code** for the company token. Read on **Code**, **Project and Team**, **Graph**,
**Identity** and **Work Items** for yours. See [Create an Azure DevOps
token](create-a-token.md).

## Where do I see my own token afterwards?

In **My Account › My accounts**, on the **Azure DevOps** card, with a **Connect** button.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/azure-devops/troubleshooting.md -->

# Common problems with Azure DevOps

## When you add the integration

| What you see | What to do |
| --- | --- |
| Under **Azure Server host**: `Azure Server host is required.` | The field is empty. Enter `dev.azure.com`. |
| `No server answers to the name <host>. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Copy the host from the address bar of your Azure DevOps, without `https://` or a path. |
| `dev.azure.com answered « not found » (404). Check the host and the API URL. Fix the field above, or save anyway if the source is only unreachable for now.` | The **Organization** does not exist. Copy it from `https://dev.azure.com/<organization>`. |
| `dev.azure.com answered something unexpected (302). Check the host and the API URL. Fix the field above, or save anyway if the source is only unreachable for now.` | Check the token: [create a new one](create-a-token.md) and replace it. |

## On your dashboard

| What you see | What to do |
| --- | --- |
| `Your Azure DevOps account is not connected. This card shows what your own Azure DevOps account sees. The token set in the administration only serves the entity tabs, the catalog and Compass: connect your own Azure DevOps account, here or in My account › My accounts.` | Click **Connect my Azure DevOps account** in the card. |
| `Azure DevOps refused the token. The token may have expired or been revoked: replace it in Administration › Company connections › Azure DevOps (or in My account › My accounts if it is your own).` | Create a new token ([how](create-a-token.md)) and replace it where the message says. |
| `Partial list: the read stopped at its limit for …. Azure DevOps holds more.` above the table of a card | Azure DevOps holds more than the card can read: the rows shown are those read before the limit. |
| The source **azure** is missing from **Add a card** | The integration is not configured. [Add it](add-the-integration.md). |

## In Administration

| What you see | What to do |
| --- | --- |
| In **Problems**, a **Company connection** line `dev.azure.com answers something unexpected (302). Check the host and the API URL.` | Click **Fix it**, check the token, then click **Check again**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/bitbucket-cloud/add-the-integration.md -->

# Add the Bitbucket Cloud integration

The integration gives Astrolabe the email and the token of a Bitbucket Cloud account. The card of
**Administration › Company connections** describes it as **Repositories and catalog entities from Bitbucket
Cloud.**

You do it once, as an administrator.

## Before you start

You need the email address of an Atlassian account, and a token of that account with read access to the
repositories. In Bitbucket, you create it under **Personal settings**. This step was not checked on a live
instance.

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Bitbucket Cloud** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Email** | The email address of the Atlassian account the token belongs to | `dev@example.com` |
   | **Token** | An API token (or app password) of that account, with read access to the repositories | |

6. Click **Test connection**.

7. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list. This step was not checked on a live instance with a working token.

## The optional setting

Under **Optional settings**, **Name** is the label shown in the token list. It is already filled with
`Bitbucket Cloud`.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/bitbucket-cloud/troubleshooting.md -->

# Common problems with Bitbucket Cloud

## When you add the integration

| What you see | What to do |
| --- | --- |
| `Email is required.` | Fill in **Email** with the address of the Atlassian account that owns the token. |
| `api.bitbucket.org refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The email or the token is wrong, or the token has expired. Check **Email**, then create a new token in Bitbucket and paste it in **Token**. |

The form also offers **Save anyway**, to keep the token when Bitbucket is only unreachable for now.

## After you add it

| What you see | What to do |
| --- | --- |
| In the token list, in **State**, the message `api.bitbucket.org refused the credentials (401). Check the token, and that it has not expired.` | Edit the token: new token, then **Test connection**. |
| On **Administration › Company connections**, **Not working** on the **Bitbucket Cloud** card | Open the card: **State** says why. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/bitbucket-server/add-the-integration.md -->

# Add the Bitbucket Server integration

The integration gives Astrolabe the address of your Bitbucket Server and a token to read it. The catalog
reads your repositories with it: see [Import your Bitbucket Server repositories](../../Catalogue/bitbucket-server/import-repositories.md).

You do it once, as an administrator.

## Before you start

You need an access token of your Bitbucket Server, with read access to the projects. In Bitbucket, you
create it under **Manage account › HTTP access tokens**. This step was not checked on a live instance.

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Bitbucket Server** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name for you, shown in the token list. Already filled with `Bitbucket Server`. | `Bitbucket Server` |
   | **Bitbucket Server host** | The address of your server, without `https://` and without a path. It must be the exact name the server answers to. | `bitbucket.example.com` |
   | **Token** | The access token | |

6. Click **Test connection**.

7. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list. This step was not checked on a live instance with a working token.

:::tip Every field has its ?
Hover the **?** next to a field to see what it expects, with an example.
:::

## The optional setting

Under **Optional settings**, **API Base URL** is the full address of the REST API, with `https://`. Leave it
empty: Astrolabe then uses `https://<host>/rest/api/1.0`.

✅ That's it!

Next: [Import your Bitbucket Server repositories](../../Catalogue/bitbucket-server/import-repositories.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/bitbucket-server/troubleshooting.md -->

# Common problems with Bitbucket Server

## When you add the integration

| What you see | What to do |
| --- | --- |
| `Bitbucket Server host is required.` | Fill in **Bitbucket Server host**, for example `bitbucket.example.com`. |
| `No server answers to the name bitbucket.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Copy the address you open in your browser into **Bitbucket Server host**, without `https://`. If it is right, your Bitbucket Server is not reachable from Astrolabe. |
| `example.com answered « not found » (404). Check the host and the API URL. Fix the field above, or save anyway if the source is only unreachable for now.` | The host answers, but it is not a Bitbucket Server. Check **Bitbucket Server host**, and **API Base URL** under **Optional settings**. |

The form also offers **Save anyway**, to keep the token when the server is only unreachable for now.

## After you add it

**Administration › Problems** lists what does not work, with a **Fix it** button.

| What you see | What to do |
| --- | --- |
| In the token list, in **State**, the message `No server answers to the name bitbucket.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator.` | Edit the token and fix the host. |
| In **Administration › Problems**, a **Company connection** line **Bitbucket Server** with the same message | Click **Fix it**: it opens the integration. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/codacy/add-the-integration.md -->

# Add the Codacy integration

The integration gives Astrolabe a Codacy account API token. It is what the **Codacy** plugin reads: the
grade of a component and its issues.

You do it once, as an administrator.

## Before you start

You need a Codacy **account API token**. In Codacy, you create it under **your account › Access management
› API tokens**. This step was not checked on a live instance.

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Codacy** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name for you, shown in the token list. Already filled with `Codacy`. | `Codacy` |
   | **Account API token** | The account API token | |

6. Click **Test connection**.

7. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list. This step was not checked on a live instance with a working token.

## The optional setting

Under **Optional settings**, **API address (self-hosted Codacy only)** is the full address of your own
Codacy, with `https://`. Leave it empty to use `app.codacy.com`.

✅ That's it!

Next: [Show Codacy on a component](show-on-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/codacy/show-on-a-component.md -->

# Show Codacy on a component

Each annotated component shows its Codacy grade on its overview, and its issues in a tab. The card of
**Administration › Plugins** says: **An entity's Codacy grade on its overview, its issues in a tab.**

Two steps: turn on the plugin, annotate the component.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **Codacy** card, click the switch **Enable Codacy**.

:::tip The switch is greyed out?
If the card says **Configure the Codacy integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Codacy integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.
:::

## 2. 🏷️ Annotate the component

In the component's `catalog-info.yaml`, name the repository as Codacy knows it: the Codacy provider
(`gh` for GitHub, `gl` for GitLab, `bb` for Bitbucket), the organization, then the repository.

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    codacy.com/project-slug: gh/acme/shop-api
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
```

## ✅ Check

Wait a few minutes for the catalog to read the file, then open the component from **Catalog**. Without the
annotation, the component has no Codacy card on its overview and no Codacy tab. With the annotation, the
card and the tab show the grade and the issues. This part was not checked on a live instance.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/codacy/troubleshooting.md -->

# Common problems with Codacy

## When you add the integration

| What you see | What to do |
| --- | --- |
| `Account API token is required.` | Paste the account API token in **Account API token**. |
| `app.codacy.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong or expired. Create a new account API token in Codacy and paste it in **Account API token**. |

## After you add it

| What you see | What to do |
| --- | --- |
| On the **Codacy** card of **Administration › Plugins**, a greyed switch and **Configure the Codacy integration first** | Add the integration: [Add the Codacy integration](add-the-integration.md). |
| In **Administration › Problems**, a **Company connection** line **Codacy**: `app.codacy.com refuses the credentials (401). The token may be wrong or expired.` | Click **Fix it**: it opens the integration. Paste a new token. |
| No Codacy card on the component overview, no Codacy tab | Add the `codacy.com/project-slug` annotation to the component, and turn on **Enable Codacy** in **Administration › Plugins**. |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this Codacy feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves Codacy. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/company-token-and-my-account.md -->

# The company's token and your own account

GitHub, GitLab, Jira and Azure DevOps each have **two** tokens in Astrolabe. They are not the same,
and one never replaces the other.

| | The company's token | Your own account |
| --- | --- | --- |
| **Who sets it** | An Astrolabe administrator, once | Each user, for themselves |
| **Where** | **Administration › Company connections**, on the tool's card | **In the dashboard card** that needs it (**Connect my &lt;tool&gt; account**), or **My Account › My accounts** |
| **What it reads** | The tabs of the components, the catalog and Compass — the same for everyone | **Your** dashboard cards: my issues, my pull requests, my merge requests — what **your** account sees |

:::tip Which one am I missing?
A dashboard card that says **Your &lt;tool&gt; account is not connected.** asks for **your own** account,
not the company's token. Click **Connect my &lt;tool&gt; account** in the card: the window opens there, says
where to create the token and with which rights.
:::

## 🔑 Connect your own account

1. On **My Dashboards**, in the card that says **Your &lt;tool&gt; account is not connected.**, click
   **Connect my &lt;tool&gt; account**.
2. The window says where to create the token, with which rights, and links to the token page of your
   tool. Create the token there.
3. Fill in **Username** and **Token**, then click **Test Connection**. It says **Connection works: the
   tool accepted your token.** If the tool refuses it, the window says why: a wrong token, a missing
   right or an expired token.
4. Click **Save**. The window closes and every card of the tool reads again.

✅ That's it!

Step by step, tool by tool: [Jira](jira/add-the-dashboard-cards.md),
[GitLab](gitlab/add-the-dashboard-cards.md), [GitHub](github/add-the-dashboard-cards.md).

## 🧰 See, change or remove your accounts

1. Top right, click your avatar, then **My Account**.
2. Open the **My accounts** tab.

Each tool has a card: **Connected**, **Not connected**, **Token refused** or **Not verified**.
**Configure** changes or deletes your token; **Connect** adds one.

## For the administrator

On the page of each of these tools, in **Administration › Company connections**, Astrolabe says it too:
"This company token only serves the entity tabs, the catalog and Compass. It does not serve the
personal dashboard cards (my issues, my pull requests): everyone connects their own account there,
from the card itself or in My account › My accounts."

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/confluence/add-the-integration.md -->

# Add the Confluence integration

Once Confluence is connected, the search of Astrolabe finds its pages: type a word of a page, and the
page is in the list. You do this once, as an Astrolabe administrator.

## 🔑 1. Create a token in Confluence

The token reads what its owner can see: the account must be able to open the pages you want to
find. No Confluence administrator right is needed.

1. Log in to Confluence with the account Astrolabe will read with.
2. Open your profile, then **Personal Access Tokens**, then click **Create token**.
3. Give it a name (`Astrolabe`), then create it.
4. Copy the token **as is**.

## 🔌 2. Add the integration

1. In the left sidebar, at the bottom, click **Administration**.
2. Under **PLATFORM**, click **Company connections**.
3. On the **Confluence** card, click **Configure**.
4. Top right, click **Add Token**.
5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice (the form proposes `Confluence`) | `Confluence` |
   | **Confluence host** | The domain name of your Confluence, with its port if it is not 443; no `https://` | `wiki.example.com` |
   | **API token** | The token of step 1, pasted as is | |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**
7. Click **Add**. Astrolabe restarts on its own, in a few seconds.

The token is in the list, with **State** set to **Connected**.

## 🗂️ 3. Choose the spaces to search (optional)

Without this step, Astrolabe searches every space the token's account can read. To keep only some,
do this in the form of step 2, before **Add**:

1. Click **Optional settings**.
2. In **Spaces to search**, type the keys of the spaces, separated by commas: `ENG, OPS`. The key of a
   space is in its address: `.../spaces/ENG/...`.
3. Click **Add**.

**Test connection** does not check the space keys. A key that matches no space is said later, in
**Administration › Problems**: see [Common problems with Confluence](troubleshooting.md).

Two other optional fields are in **Optional settings**: **E-mail** (Confluence Cloud only: the e-mail
of the Atlassian account that owns the API token) and **Context path** (a Confluence installed under
a path, such as `/confluence`). Leave both empty otherwise.

:::note Confluence Cloud
A Confluence Cloud (`.atlassian.net`) takes the **E-mail** of the Atlassian account together with an
API token of this account (`id.atlassian.com`, **Security**, **Create and manage API tokens**).
This path was not tried on a Confluence Cloud instance.
:::

✅ That's it!

Next: [Find a Confluence page in the search](search-confluence-pages.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/confluence/search-confluence-pages.md -->

# Find a Confluence page in the search

With the [Confluence integration](add-the-integration.md) in place, the pages of Confluence are in
the same search as your components.

1. In the left sidebar, click **Search**.
2. Click in the search field at the top of the page and type a word of the page, for example
   `runbook`.

The result shows the title of the page, the beginning of its text and, below, its space (for
example **Space ENG**).

3. Click the result. The page opens in a new window, on your Confluence.

The search looks in the title **and** in the text of the page.

:::tip A page you just wrote
The pages are read again on a regular schedule, and once when Astrolabe restarts. A page written a
minute ago can take up to half an hour to appear.
:::

## What the filters do with Confluence pages

1. At the top right, click **Filters**.
2. Under **Kind**, **All** keeps the Confluence pages in the list; **Component**, **Template**,
   **User** or **Group** takes them out.

✅ That's it!

Next: [Common problems with Confluence](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/confluence/troubleshooting.md -->

# Common problems with Confluence

## When you add the integration

| What you see | What to do |
| --- | --- |
| `wiki.example.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong or expired. Create a new one ([step 1](add-the-integration.md)) and paste it as is in **API token**. |
| `No server answers to the name wiki.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Copy the domain name from the address bar of your browser into **Confluence host**, without `https://`. |

## In Administration

| What you see | What to do |
| --- | --- |
| In **Administration › Problems**, a **Company connection** line `wiki.example.com refuses the credentials (401). The token may be wrong or expired.` (the **State** column of the Confluence card says `wiki.example.com refused the credentials (401). Check the token, and that it has not expired.`) | The token no longer works. Click **Fix it**, delete the token, and add a new one. |
| In **Administration › Problems**, a **Search** line `Confluence · <name>` saying `wiki.example.com answers, but no page was found to search. Check the space keys of the connection: a misspelled key finds nothing.` | The keys in **Spaces to search** match no space. Click **Fix it**, compare each key with the address of its space (`.../spaces/ENG/...`), and correct the field. |
| In **Administration › Problems**, a **Search** line `Documentation · <component>` saying `The documentation could not be built from its repository, so it is not searched. Open it to read the error, and fix its mkdocs.yml or its pages.` | The documentation of this component does not build, so the search cannot read it. Click **Fix it**: the documentation opens and shows the error. Correct the `mkdocs.yml` or the page it names. *(Message taken from the screen's texts; not provoked on an instance.)* |

## In the search

| What you see | What to do |
| --- | --- |
| **We couldn't find a match** for a word you know is on a Confluence page | Open **Filters** and pick **All** under **Kind**. Otherwise the page is in a space outside **Spaces to search**, or was written less than half an hour ago. |

:::tip Still stuck?
Write to **support@forgeit.fr** with what you see on the screen.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/add-the-dashboard-cards.md -->

# Add the GitHub cards to your dashboard

The GitHub cards of **My Dashboards** show what **your own GitHub account** sees. They need your own
token, connected once — from the card itself.

## The cards

| Key | What it shows |
| --- | --- |
| **Workflows** | GitHub Actions workflow runs with status and run number |
| **Detailed Workflows** | Workflow runs with individual job details, stages, and duration |
| **Pull Requests** | Pull requests of every GitHub repository of the catalog that your token can read, with author, reviewers, status and your role (filter on it for your own) |
| **Releases** | The last published release of each GitHub repository of the catalog your token can read |

A card with nothing to show says **Nothing here yet** and, under it, what would fill it:

| Card | What it says |
| --- | --- |
| **Pull Requests** | No open pull request in the GitHub repositories named by the components of the catalog (github.com/project-slug annotation) that your token can read. |
| **Workflows** and **Detailed Workflows** | No workflow run lately in the GitHub repositories of the components you own (github.com/project-slug annotation). |
| **Releases** | No release published in the GitHub repositories named by the components of the catalog (github.com/project-slug annotation) that your token can read. |

Click **Learn more** under the sentence to come back to this page.

## ➕ Add a card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick **Source** `github`, then a **Key**.

4. Leave **organizations** empty, or see [Which repositories](#which-repositories) below.

5. Enter a **Card Name**, then click **Add**.

:::tip The `github` source is missing?
It is only offered once the administrator has [added the GitHub integration](add-the-integration.md).
:::

## 🔗 Connect your GitHub account

The first time, the card says **Your GitHub account is not connected.** ("This card shows what your
own GitHub account sees. The token set in the administration only serves the entity tabs, the catalog
and Compass: connect your own GitHub account, here or in My account › My accounts.")

1. In the card, click **Connect my GitHub account**. The **Connect my GitHub account** window opens
   on the dashboard. It says where to create the token, with which rights (`repo` and `read:org`),
   and links to the token page of your GitHub.

2. Fill in:
   - **Username**: your GitHub login, for example `octocat`. Astrolabe recognises you by it in GitHub
     events.
   - **Token**: a token of your own GitHub account. See [Create a GitHub token](create-a-token.md).

3. Click **Test Connection**. It says **Connection works: the tool accepted your token.**

4. Click **Save**. The window closes and **every GitHub card** of your dashboard reads again: they
   show what your GitHub account sees.

Your token is also listed in **My Account › My accounts**, where you change or remove it.

✅ That's it!

## What each card shows

Each row has a coloured dot for its status; the card's top right names the statuses it contains. The
arrow at the end of a row opens the item on GitHub.

### Workflows

| Column | What it holds |
| --- | --- |
| **Resource** | The repository |
| **Title** | The workflow |
| **Author** | Who started the run |
| **Date** | When the run was last updated |

One row per workflow of each repository: its latest run, kept only if it ran in the last two hours or
if it failed in the last day. A card with no such run says **Nothing here yet** and the sentence above.

### Detailed Workflows

| Column | What it holds |
| --- | --- |
| **Resource** | The repository |
| **Title** | The job |
| **Key** | The run number, like `#1` |
| **Date** | When the run was last updated |
| **Duration** | How long the job took, `-` while it has not finished |
| **Status** | `queued`, `success`, and so on |
| **Stages** | The steps of the job |

Same runs as **Workflows**, one row per job.

### Pull Requests

| Column | What it holds |
| --- | --- |
| **Resource** | The repository |
| **Key** | The number of the pull request, like `#44` |
| **Title** | The pull request |
| **Author** | Who opened it |
| **Assignees** | Who it is assigned to, `-` when nobody |
| **Reviewers** | Who is asked to review it, `-` when nobody |
| **My role** | What you are on it: **Author**, **Review requested**, **Assignee** or **None** |
| **Date** | The pull request date |

The pull requests of **every repository of the catalog that your token can read**, whoever opened
them: the open ones, and those closed in the last 7 days. The top right of the card names the states
present, **open** and **closed**. The table shows 5 rows per page; **Show 10 results** lists 10, and
the count (for example **1-5 of 83**) moves with the filter.

If GitHub holds too many pull requests to read them all, the card says **List cut: too many items to
read, only the most recent are shown.** above the table.

#### Keep only your pull requests

The card lists everything your token reads. To keep yours, filter the column **My role** and save the
filter with the card:

1. On **My Dashboards**, open the tab of the dashboard.

2. On the card, click **more**, then **Edit**, then open the **Filters** tab.

3. Under **my role**, click the cross of **None** (**Remove filter None**). Only the pull requests
   where you are involved stay: here **Author**.

4. Click **Save** in the window.

The filter is saved with the card. To see everything again, open the **Filters** tab and click **Reset**
under **my role**. See also [Change or remove a card](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

### Releases

| Column | What it holds |
| --- | --- |
| **Resource** | The repository |
| **Key** | The tag of the release |
| **Date** | When it was published |

The last published release of each repository. A repository without any release has no row.

### Which repositories?

The cards only show repositories that **a component of the catalog names** with
`github.com/project-slug`. A repository the catalog does not know is never shown.

The **organizations** field ("GitHub organizations to show, comma-separated (e.g. acme). Empty: the
ones the catalog imports.") picks the organizations. Left empty, a card covers the organizations of the
GitHub catalog provider. To show a component registered by hand from another organization, write that
organization in the field, for example `acme`.

## The states in My Account › My accounts

| State | What it means |
| --- | --- |
| **Connected** | Your token works |
| **Not connected** | You have not saved a token |
| **Token refused** | GitHub refuses your saved token. Hover the words for the reason, or click **Configure**. |
| **Not verified** | GitHub could not be reached to check |

## 🔔 Notifications

You choose what you receive in **My Account › Notifications**. Under **GitHub**, the screen lists
**When a workflow fails** (marked as critical), **When a PR is opened**, **When a PR is closed**,
**When a PR is edited**, **When a PR review is requested**, **When a PR is approved**, **When changes
are requested on a PR**, **When a PR is reviewed with comments** and **When a workflow is cancelled**.

For GitHub to send them, the administrator sets a secret in **Administration › Company connections ›
Webhooks › GitHub › Configure** (**Webhook Secret**, then **Save Secret**). This step, and the
delivery of the notifications, were not checked on a live instance.

Next: [GitHub FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/add-the-integration.md -->

# Add the GitHub integration

The integration gives Astrolabe your GitHub host and the administrator's token. The **GitHub** tab,
the catalog and the dashboard cards need it.

You do it once, as an administrator.

## Before you start

You need a token with `repo`, `read:org` and `read:user`: see [Create a GitHub token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **GitHub** card, click **Configure**. The card says **Not configured**.

4. Top right, click **Add Token**.

5. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice, unique in the list. Prefilled with `GitHub`. | `GitHub` |
   | **Host** | The domain name only, no path. Prefilled with `github.com`. For GitHub Enterprise, its own domain name, exactly as the server answers to it. | `github.com` |
   | **Token** | The administrator's token | `ghp_…` |
   | **Optional settings › API Base URL** | Leave empty: github.com needs none, and for GitHub Enterprise `https://<host>/api/v3` is filled in on save. | |
   | **Optional settings › Raw Base URL** | Leave empty: for GitHub Enterprise `https://<host>/raw` is filled in on save. | |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**

7. Click **Add**. The instance restarts.

About 25 seconds later, your token is in the list, with the source **Administration** and the state
**Connected**.

:::warning Same host as the catalog
The **Host** of the GitHub catalog provider (**Administration › Catalog › GitHub**) must be the one
written here.
:::

✅ That's it!

Next: [Show the GitHub tab on a component](show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/create-a-token.md -->

# Create a GitHub token

Astrolabe reads GitHub with **a classic personal access token**. You need one for the administrator,
and each user creates one for their own dashboard cards.

## Two tokens, two uses

| Token | Entered in | Reads GitHub for |
| --- | --- | --- |
| The **administrator's** | **Administration › Company connections** | The **GitHub** tab, the **GitHub releases** card and the catalog, the same for everyone |
| **Yours** | **My Account › My accounts** | **Your** dashboard cards. The administrator's token is never used for them. |

## 🔑 Create the token

1. In GitHub, open **Settings › Developer settings › Personal access tokens**, then **Tokens
   (classic)**, and generate a new token.

2. Tick **`repo`**, **`read:org`** and, under **`user`**, **`read:user`**. Pick an expiration date and
   generate the token. Without `read:user`, the import of the organization's members and teams fails.

3. Copy the token **as is**: a string starting with `ghp_`, without `Bearer ` in front.

:::tip A dedicated account for the administrator's token
Every user reads the **GitHub** tab through it, and it only sees the repositories of its account. Use
an account dedicated to Astrolabe rather than a person's account.
:::

✅ That's it!

Next: [Add the GitHub integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/faq.md -->

# GitHub FAQ

## Why is there no GitHub tab on my component?

Because the GitHub plugin is off, or the component has no `github.com/project-slug` annotation. Turn
the plugin on in **Administration › Plugins**, and add the annotation. See
[Show the GitHub tab](show-the-tab.md).

## Do the dashboard cards show my own pull requests?

**Yes**, among others: the **Pull Requests** card shows every pull request of the repositories of the
catalog that your token reads, and its column **My role** tells which ones are yours. Filter on it to
keep them: see [Keep only your pull requests](add-the-dashboard-cards.md#keep-only-your-pull-requests).
Your own token must be saved in **My Account › My accounts**: each user sees what their own GitHub
account sees. Without it, the cards say **Your GitHub account is not connected.**

## Can a product owner see all the pull requests of the team?

**Yes.** Add the **Pull Requests** card: it lists every pull request of the repositories of the catalog
that the token of the product owner can read, whoever opened them. Nothing to filter, nothing to
configure. To follow one person or a state, filter the columns **Author** or **status** in the card:
see [Change or remove a card](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

## Which token rights does Astrolabe need?

A classic token. The administrator's token needs `repo`, `read:org` and `read:user` (`read:user` to
GitHub.

## Why is a repository missing from my cards?

Because no component of the catalog names it with `github.com/project-slug`, or it belongs to an
organization the card does not cover. Write that organization in the **organizations** field of the
card. See [Which repositories](add-the-dashboard-cards.md#which-repositories).

## Why does the Workflows card say "Nothing here yet" when my workflows ran?

Because it only keeps a workflow whose latest run happened in the last two hours, or failed in the
last day. A workflow that succeeded yesterday is not listed.

## Does the card show one line per run?

No. **Workflows** shows one line per workflow, its latest run. **Detailed Workflows** shows one line
per job of those runs.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/get-notifications.md -->

# Get GitHub notifications

Astrolabe tells you about GitHub in the bell at the top right: a workflow that fails, a pull request
that needs a review. You choose which events.

## Before you start

Your administrator has set up the GitHub webhook (see below).

## 🔔 Choose your GitHub events

1. At the top right, click your avatar, then **My Account**.

2. Open the **Notifications** tab.

3. In the **What do you want to receive?** card, find the **GitHub** section. Each event has two
   switches: **In Astrolabe** (the bell) and **On this browser**.

   | Event | |
   | --- | --- |
   | **When a workflow fails** | Marked **Critical** |
   | **When a PR is opened** | |
   | **When a PR is closed** | |
   | **When a PR is edited** | |
   | **When a PR review is requested** | |
   | **When a PR is approved** | |
   | **When changes are requested on a PR** | |
   | **When a PR is reviewed with comments** | |
   | **When a workflow is cancelled** | |

4. Switch an event off or on. It is saved right away.

For the browser column, see
[Choose your notifications](../../../../developer-dashboard/notifications/choose-your-notifications.md).

✅ That's it!

## 🔗 For the administrator: set up the webhook

GitHub sends its events to Astrolabe through a webhook.

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**, then open the **Webhooks** tab.

3. On the **GitHub** card, click **Configure**.

4. In the window, next to **Webhook URL**, click **Copy address**. The button says **Copied**.

5. In **Webhook Secret**, type a secret of your choice, then click **Save Secret**.

6. In your GitHub repository, add a webhook: paste the address as its URL, and use the same secret. *This step was not checked on a live instance, nor was the arrival of the notifications.*

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/show-the-tab.md -->

# Show the GitHub tab on a component

Each annotated component gets a **GitHub** tab and a **GitHub releases** card on its **Overview**.

Two steps: turn on the plugin, annotate the component.

## What it shows, and to whom

| Where | What |
| --- | --- |
| **GitHub** tab | Three sub-tabs with their count: **Pipelines** (Workflow, Branch, Result, Started by, Started), **Pull requests** (Pull request, Author, Branch, Updated), **Branches** (the default one marked `default`, protected ones `protected`) |
| **GitHub releases** card of the **Overview** | The latest releases of the repository, with their tag, title and date |

The **Pipelines** sub-tab lists the latest workflow runs, whoever started them. Anyone who can open the
component sees all of this. Astrolabe reads GitHub with **the administrator's token**, the same for
everyone.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **GitHub** card, click the switch at the **top right of the card**. It turns on at once,
   without confirmation.

## 2. 🏷️ Annotate the component

In the component's `catalog-info.yaml`, name its repository as `<owner>/<repository>`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    github.com/project-slug: acme/shop-api   # <owner>/<repository> on GitHub
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
```

## 3. 📥 Put the component in the catalog

- **One component**: in the sidebar, click **Catalog**, then **Register an existing component** at
  the top right. Paste the address of the `catalog-info.yaml` file on GitHub (for example
  `https://github.com/acme/shop-api/blob/main/catalog-info.yaml`), click **Analyze**, then
  **Import**, then **View Component**.
- **A whole organization**: use the GitHub catalog provider. See
  [Import your GitHub repositories](../../Catalogue/github/import-repositories.md).

## ✅ Check

Open the component. The **GitHub** tab is after **Docs**. The **Overview** shows a **GitHub releases**
card.

✅ That's it!

Next: [Add the GitHub cards to your dashboard](add-the-dashboard-cards.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/github/troubleshooting.md -->

# Common problems with GitHub

## When you add the integration

| What you see | What to do |
| --- | --- |
| Under the **Token** field: `Token is required.` | The field is empty; nothing was sent to GitHub. Paste the token. |
| `api.github.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong, revoked or expired. Paste the token alone (it starts with `ghp_`), or [create a new one](create-a-token.md). |
| `No server answers to the name <host>. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Copy the domain name from the address bar of your GitHub, without `https://` nor path. If it is right, the server is not reachable from Astrolabe. |
| The card says **Set by app-config.local.yaml** (or another file name), and the page says `This connection is set by the config file app-config.local.yaml: a token added here would be ignored. Change it in that file, or ask whoever manages the instance's files.` **Add Token** is greyed out. | A configuration file of the instance declares GitHub, and a file always wins over the administration. Change the token in that file, or ask whoever manages the instance's files to remove GitHub from it: the administration then takes over. |

## On the component page

| What you see | What to do |
| --- | --- |
| No **GitHub** tab | Add the `github.com/project-slug` annotation ([Show the GitHub tab](show-the-tab.md)), and check that **GitHub** is on in **Administration › Plugins**. |
| In the tab or the **GitHub releases** card: `The repository <owner>/<repository> cannot be reached with your GitHub token: check the github.com/project-slug annotation, or the token access.` | No repository has that name, **or** the token's account cannot see it. Compare the annotation with the repository's address on GitHub, then check that the token's account has access to it. |

## On your dashboard

| What you see | What to do |
| --- | --- |
| The **github** source is missing from **Add a card** | The GitHub integration is not configured. [Add it](add-the-integration.md). |
| `Your GitHub account is not connected.` | Click **Connect my GitHub account** in the card. See [Connect your GitHub account](add-the-dashboard-cards.md#-connect-your-github-account). |
| **Nothing here yet** and `No open pull request in the GitHub repositories named by the components of the catalog (github.com/project-slug annotation) that your token can read.` | Check that the repository is named by a component of the catalog (`github.com/project-slug`), that your token can read it, and the card's **organizations** field. |
| The **Pull Requests** card is empty after you removed values in **Filters** | The filter keeps no row. Open **Edit** on the card, then **Filters**, and click **Reset** under the column. |
| `List cut: too many items to read, only the most recent are shown.` above the table | GitHub holds more than the card can read: the rows shown are the most recent ones. |
| **Nothing here yet** and `No workflow run lately in the GitHub repositories of the components you own (github.com/project-slug annotation).` | Check that you own the component of the repository and that it carries the `github.com/project-slug` annotation. |
| **Nothing here yet** and `No release published in the GitHub repositories named by the components of the catalog (github.com/project-slug annotation) that your token can read.` | Check that the repository is named by a component (`github.com/project-slug`) and that your token can read it. |
| `GitHub refused the token. The token may have expired or been revoked: replace it in Administration › Company connections › GitHub (or in My account › My accounts if it is your own).` | Your token is revoked, expired or wrong. Click **Open the GitHub integration**, or go to **My Account › My accounts**, click **Configure**, then **Replace** next to **Token**, paste a new token, **Save**. |
| In **My Account › My accounts**, the **GitHub** card says **Token refused** | GitHub refuses your token: revoked, expired, or without the rights. Click **Configure**: the form says why. Click **Replace** next to **Token**, paste a new token, **Save**. |
| **Test Connection** in **Connect my GitHub account** says `api.github.com refused your token (401). Check it, and that it has not expired.` | Your token is wrong, revoked or expired. Paste a valid token of your own GitHub account. |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this GitHub feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves GitHub. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its GitHub repository.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/add-the-dashboard-cards.md -->

# Add the GitLab cards to your dashboard

The GitLab cards of **My Dashboards** show what **your own GitLab account** sees. You add a card, then
you connect your account from the card itself, once.

## Before you start

- Your administrator has [added the GitLab integration](add-the-integration.md). Without it, the
  `gitlab` source is not in the list.
- You have [a GitLab token of your own](create-a-token.md).

## ➕ 1. Add a card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick the **Source** `gitlab`, then a **Key**:

   | Key | What it shows |
   | --- | --- |
   | **Pipelines** | The last pipeline of each branch of your active projects, when it failed or ran lately |
   | **Detailed Pipelines** | The jobs of your latest pipelines, with status and duration |
   | **Merge Requests** | Merge requests of every GitLab project of the catalog that your token can read, with status and your role (filter on it for your own) |
   | **Releases** | The last published release of each GitLab project of the catalog your token can read |
   | **To-Do List** | Your pending GitLab to-dos: reviews requested, assignments, mentions, broken builds |

4. Enter a **Card Name**, then click **Add**.

## 🔑 2. Connect your GitLab account, in the card

The first time, the card says **Your GitLab account is not connected.**

1. In the card, click **Connect my GitLab account**. The **Connect my GitLab account** window opens.
   It says where to create the token and with which rights (`read_api` and `read_repository`), and
   links to the token page of your GitLab.

2. Fill in:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Username** | Your GitLab username, the one after the `@` on your GitLab profile. Astrolabe recognises you by it in GitLab events. | `jdoe` |
   | **Token** | The token of your own GitLab account, pasted as is | `glpat-…` |

3. Click **Test Connection**. The window says **Connection works: the tool accepted your token.**

4. Click **Save**. The window closes and **every GitLab card** of your dashboard reads again.

✅ That's it!

:::tip Change or remove your token
Your GitLab account is listed in **My Account › My accounts** (your avatar, top right, then **My
Account**, then the **My accounts** tab). Click **Configure** on the **GitLab** card to replace the
token, or **Delete** to remove it.
:::

## The states in My Account › My accounts

| State | What it means |
| --- | --- |
| **Connected** | You saved a token |
| **Not connected** | You have not saved a token |
| **Token refused** | GitLab refuses your saved token. Click **Configure**: the window says why. |

Next: [What each GitLab card shows](what-the-cards-show.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/add-the-integration.md -->

# Add the GitLab integration

The integration gives Astrolabe your GitLab host and the administrator's token. The **GitLab** tab,
the catalog and the dashboard cards need it.

You do it once, as an administrator.

## Before you start

You need a token with `read_api` and `read_repository`: see [Create a GitLab token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **GitLab** card, click **Configure**. The card says **Not configured**.

4. Top right, click **Add Token**.

5. Fill in the form. Each **?** next to a label explains the field.

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice. Prefilled with `GitLab`. | `GitLab` |
   | **GitLab instance host** | The domain name only, no path. Prefilled with `gitlab.com`. For a self-hosted GitLab, exactly the domain name the server answers to. | `gitlab.com` |
   | **GitLab token** | The administrator's token | `glpat-…` |
   | **Optional settings › API Base URL** | Leave empty: `https://<host>/api/v4` is filled in on save. | |
   | **Optional settings › Base URL** | Leave empty: it is `https://<host>`. | |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**

7. Click **Add**. A banner says **The configuration has changed; the server is restarting.**

About 25 seconds later, your token is in the list, with the source **Administration** and the state
**Connected**.

:::warning Same host as the catalog
The host of the GitLab catalog provider (**Administration › Catalog › GitLab**) must be exactly this
one.
:::

✅ That's it!

Next: [Show the GitLab tab on a component](show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/create-a-token.md -->

# Create a GitLab token

Astrolabe reads GitLab with **a personal access token**. You need one for the administrator, and
each user creates one for their own dashboard cards.

## Two tokens, two uses

| Token | Entered in | Reads GitLab for |
| --- | --- | --- |
| The **administrator's** | **Administration › Company connections** | The **GitLab** tab, the **GitLab releases** card and the catalog, the same for everyone |
| **Yours** | **My Account › My accounts** | **Your** dashboard cards. The administrator's token is never used for them. |

## 🔑 Create the token

1. In GitLab, open your user settings, then **Access tokens**, and add a new token.

2. Tick **`read_api`** and **`read_repository`**, pick an expiration date, and create the token.

3. Copy the token **as is**: a string starting with `glpat-`.

:::tip A dedicated account for the administrator's token
Every user reads the **GitLab** tab through it, and it only sees the projects of its account. Use an
account dedicated to Astrolabe rather than a person's account.
:::

✅ That's it!

Next: [Add the GitLab integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/faq.md -->

# GitLab FAQ

## Why is there no GitLab tab on my component?

Because it has no `gitlab.com/project-slug` annotation, or the GitLab plugin is off. Astrolabe does
not deduce the project from where the component was registered: add the annotation. See
[Show the GitLab tab](show-the-tab.md).

## Do the dashboard cards show my own merge requests?

**Yes**, among others: the **Merge Requests** card shows every merge request of the projects of the
catalog that your token reads, and its column **My role** tells which ones are yours. Filter on it to
keep them: see [What each GitLab card shows](what-the-cards-show.md#merge-requests). Your own token must
be saved in **My Account › My accounts**: each user sees what their own GitLab account sees. Without
it, the cards say **Your GitLab account is not connected.**

## Can a product owner see all the merge requests of the team?

**Yes.** Add the **Merge Requests** card: it lists every merge request of the projects of the catalog
that the token of the product owner can read, whoever opened them. *Not checked on a live instance (no
GitLab connected).*

## Which token rights does Astrolabe need?

`read_api` and `read_repository`, for the administrator's token as for yours. Astrolabe only reads
GitLab.

## Why is a card empty while I have projects on GitLab?

Because a card reads **the projects of the components of your catalog** that carry the
`gitlab.com/project-slug` annotation, and only what is recent: the last pipeline of each branch when it
failed or ran lately, the merge requests of the projects of the catalog, the last release. Add the annotation to the
component: see [Show the GitLab tab](show-the-tab.md). The empty card says which condition is missing,
in the sentence under **Nothing here yet**: see
[What each GitLab card shows](what-the-cards-show.md#when-there-is-nothing-to-show).

## Do the cards show every project of my GitLab?

**No**, only the projects of the components in your catalog that name their project with the
annotation, and that your token can read.

## What does the To-Do List card show?

The pending to-dos of your own GitLab account: reviews requested, assignments, mentions, broken
builds. With none pending, it says **No pending to-do on GitLab**. *A card with to-dos in it was not
checked on a live instance.*

## Who is told when a pipeline fails?

You choose in **My Account › Notifications**: see [Get GitLab notifications](get-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/get-notifications.md -->

# Get GitLab notifications

Astrolabe tells you about GitLab in the bell at the top right: a pipeline that fails, a merge request
that needs a review. You choose which events.

## Before you start

Your administrator has set up the GitLab webhook (see below).

## 🔔 Choose your GitLab events

1. At the top right, click your avatar, then **My Account**.

2. Open the **Notifications** tab.

3. In the **What do you want to receive?** card, find the **GitLab** section. Each event has two
   switches: **In Astrolabe** (the bell) and **On this browser**.

   | Event | |
   | --- | --- |
   | **When a pipeline fails** | Marked **Critical** |
   | **When a MR is opened** | |
   | **When a MR is closed** | |
   | **When a MR is edited** | |
   | **When a MR review is requested** | |
   | **When a MR is approved** | |
   | **When changes are requested on a MR** | |
   | **When a MR is reviewed with comments** | |
   | **When a pipeline is cancelled** | |
   | **When a to-do is added to your GitLab to-do list** | |

4. Switch an event off or on. It is saved right away.

Pipeline starts and successes are under **Starts and successes**, at the bottom of the
**GitLab** section: **When a pipeline starts** and **When a pipeline completes successfully**. They
are off.

A pipeline that fails reaches you as, for example, **Pipeline failed for shop-api (main)**, with
`acme/shop-api #9 - By jdoe` under it.

To be told about every pipeline of a component, see
[Watch a component](../../../../developer-dashboard/notifications/watch-a-component.md). For the
browser column, see
[Choose your notifications](../../../../developer-dashboard/notifications/choose-your-notifications.md).

✅ That's it!

## 🔕 Stop the successes of the components you watch

You watch a component? Everything that happens to it reaches you, successes included: the
**Watched components** section of the same card is on by default.

1. In the **Watched components** section, click **Starts and successes**.

2. On the line **GitLab — When a pipeline completes successfully**, switch **In Astrolabe** off.

The failures keep reaching you: **GitLab — When a pipeline fails** stays on.

✅ That's it!

## 🔗 For the administrator: set up the webhook

GitLab sends its events to Astrolabe through a webhook.

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**, then open the **Webhooks** tab.

3. On the **GitLab** card, click **Configure**.

4. In the window, next to **Webhook URL**, click **Copy address**. The button says **Copied**.

5. In **Webhook Secret**, type a secret of your choice, then click **Save Secret**.

6. In your GitLab project, add a webhook: paste the address as its URL, and the same secret as its token. *This step was not checked on a live instance.*

Each time GitLab calls Astrolabe with the right secret, the **GitLab** card of the **Webhooks** tab
says **Last call accepted** with the date, and its button reads **Manage**.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/show-the-tab.md -->

# Show the GitLab tab on a component

Each annotated component gets a **GitLab** tab and a **GitLab releases** card on its **Overview**.

Two steps: turn on the plugin, annotate the component.

## What it shows, and to whom

| Where | What |
| --- | --- |
| **GitLab** tab | Three sub-tabs with their count: **Pipelines** (Pipeline, Branch, Result, Trigger, Started), **Merge requests** (open ones: Merge request, Author, Branch, Updated), **Branches** (the default one marked `default`, protected ones `protected`) |
| **GitLab releases** card of the **Overview** | The project's releases, with their tag and date. **No release yet.** when there is none. |

Anyone who can open the component sees them. Astrolabe reads GitLab with **the administrator's
token**, the same for everyone.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **GitLab** card, click the switch at the **top right of the card**. It turns on at once,
   without confirmation.

If the card says **Configure the GitLab integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the GitLab integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.

## 2. 🏷️ Annotate the component

In the component's `catalog-info.yaml`, name its project as `<namespace>/<project>`, subgroups
included (for example `my-group/sub-group/shop-api`):

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    gitlab.com/project-slug: my-group/shop-api   # <namespace>/<project> on GitLab
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
```

:::warning The annotation is the only source
Astrolabe never guesses the project from the address the component was registered from. A component
without the annotation has no **GitLab** tab.
:::

## 3. 📥 Put the component in the catalog

- **One component**: in the sidebar, click **Catalog**, then **Register an existing component** at
  the top right. Paste the address of the `catalog-info.yaml` file on GitLab (for example
  `https://gitlab.com/my-group/shop-api/-/blob/main/catalog-info.yaml`), click **Analyze**, then
  **Import**, then **View Component**.
- **A whole group**: use the GitLab catalog provider. See
  [Import your GitLab projects](../../Catalogue/gitlab/import-projects.md).

## ✅ Check

Open the component. The **GitLab** tab is after **Docs**. The **Overview** shows a **GitLab
releases** card.

✅ That's it!

Next: [Add the GitLab cards to your dashboard](add-the-dashboard-cards.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/troubleshooting.md -->

# Common problems with GitLab

## When you add the integration

| What you see | What to do |
| --- | --- |
| Under the **GitLab token** field: `GitLab token is required.` | The field is empty; nothing was sent to GitLab. Paste the token. |
| `gitlab.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong, revoked or expired. Paste the token alone (it starts with `glpat-`), or [create a new one](create-a-token.md). |
| `No server answers to the name <host>. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Copy the domain name from the address bar of your GitLab, without `https://` nor path. If it is right, the server is not reachable from Astrolabe. |

## On the component page

| What you see | What to do |
| --- | --- |
| No **GitLab** tab | Add the `gitlab.com/project-slug` annotation ([Show the GitLab tab](show-the-tab.md)), and check that **GitLab** is on in **Administration › Plugins**. |
| In the tab or the **GitLab releases** card: `The project <namespace>/<project> cannot be reached with your GitLab token: check the gitlab.com/project-slug annotation, or the token access.` | No project has that path, **or** the token's account cannot see it. Compare the annotation with the project's address on GitLab, then check that the token's account is a member of the project. |

## On your dashboard

| What you see | What to do |
| --- | --- |
| The **gitlab** source is missing from **Add a card** | The GitLab integration is not configured. [Add it](add-the-integration.md). |
| `Your GitLab account is not connected.` | Click **Connect my GitLab account** in the card. See [Add the GitLab cards to your dashboard](add-the-dashboard-cards.md). |
| `GitLab refused the token. The token may have expired or been revoked: replace it in Administration › Company connections › GitLab (or in My account › My accounts if it is your own).` | The cards read with your own token, so it is yours that GitLab refuses: revoked, expired, or without the rights. In **My Account › My accounts**, click **Configure** on the **GitLab** card, click **Replace** next to **Token**, paste a new token, click **Save**. |
| **Nothing here yet** and `No open merge request in the GitLab projects named by the components of the catalog (gitlab.com/project-slug annotation) that your token can read.` | No merge request is open in a project of the catalog that your token reads. If you expected one, check that the component of the project has the `gitlab.com/project-slug` annotation ([Show the GitLab tab](show-the-tab.md)) and that your token's account can read the project. |
| `List cut: too many items to read, only the most recent are shown.` above the table of a GitLab card | GitLab holds more than the card can read: the rows shown are the most recent ones. |
| **Nothing here yet** and `No pipeline failed or ran lately in the GitLab projects that your token reads and that a component of the catalog names (gitlab.com/project-slug annotation).` | Add the `gitlab.com/project-slug` annotation to the component of the project ([Show the GitLab tab](show-the-tab.md)), and check that your token's account is a member of the project. |
| **Nothing here yet** and `No release published in the GitLab projects named by the components of the catalog (gitlab.com/project-slug annotation) that your token can read.` | Add the `gitlab.com/project-slug` annotation to the component of the project, and check that your token's account can read the project. |
| **No pending to-do on GitLab** and `GitLab lists no pending to-do for your account: no review requested, assignment, mention or broken build.` | Nothing to fix: the card fills as soon as GitLab has a to-do for you. |
| **Test Connection** in **Connect my GitLab account** says `gitlab.com refused your token (401). Check it, and that it has not expired.` | Your token is wrong, revoked or expired. Paste a valid token of your own GitLab account. |
| In **My Account › My accounts**, the **GitLab** card says **Token refused** | Same as above: click **Configure**, then **Replace**. |

## Notifications

| What you see | What to do |
| --- | --- |
| No **GitLab** section in **My Account › Notifications** | GitLab is not connected: ask your Astrolabe administrator to [add the GitLab integration](add-the-integration.md). |
| A failed pipeline does not ring the bell | Check that **When a pipeline fails** is on in **My Account › Notifications**, and ask your administrator whether the GitLab webhook is set up (see [Get GitLab notifications](get-notifications.md)). |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this GitLab feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves GitLab. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its GitLab project.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/gitlab/what-the-cards-show.md -->

# What each GitLab card shows

You have [added a GitLab card](add-the-dashboard-cards.md). Here is what it lists, and for which
projects.

## Which projects a card reads

A card reads the GitLab projects of the **components of your catalog** that name their project with
the `gitlab.com/project-slug` annotation, with **your own token**. A component without the annotation
is not read. See [Show the GitLab tab on a component](show-the-tab.md) for the annotation.

```yaml
metadata:
  annotations:
    gitlab.com/project-slug: acme/shop-api   # <namespace>/<project> on GitLab
```

Each row ends with an arrow: click it to open the pipeline, job, merge request or release in GitLab.

## Pipelines

The last pipeline of each branch, when it failed or ran lately.

| Column | What it shows |
| --- | --- |
| **Resource** | The project, with a coloured dot for the status of the pipeline |
| **Title** | The branch |
| **Author** | The GitLab username of the person who triggered it |
| **Date** | When it ran, most recent first |

The statuses present in the card are written at the top right of the card, with their colour: for
example **running**, **success**.

## Detailed Pipelines

The jobs of your latest pipelines. One row per job.

| Column | What it shows |
| --- | --- |
| **Resource** | The project |
| **Title** | The name of the job |
| **Date** | When it ran |
| **Duration** | How long it took, for example `27s` |
| **Status** | `running`, `success`, … |
| **Stages** | The status of the job's stage, as a coloured mark |

## Merge Requests

The merge requests of **every GitLab project of the catalog that your token can read**, whoever opened
them: the open ones, and those closed in the last 7 days.

| Column | What it shows |
| --- | --- |
| **Resource** | The project, with a coloured dot for the state of the merge request |
| **Title** | The title of the merge request |
| **Author** | The GitLab username of its author |
| **My role** | What you are on it: **Author**, **Review requested**, **Assignee** or **None** |
| **Date** | Its last update |

The states present are written at the top right of the card, for example **open**.

To keep only yours, filter the column **My role** and save the filter with the card: remove **None**
in the **Filters** tab of the card, as for the GitHub **Pull Requests** card, see
[Change or remove a card](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows). If GitLab holds too many merge
requests to read them all, the card says **List cut: too many items to read, only the most recent are
shown.** above the table.

*A card with merge requests in it was not checked on a live instance (no GitLab connected); it works like the GitHub **Pull Requests** card.*

## Releases

The last published release of each GitLab project of your catalog that your token can read.

| Column | What it shows |
| --- | --- |
| **Resource** | The project |
| **Key** | The tag of the release, for example `v1.2.0` |
| **Date** | The date of the release |

## To-Do List

Your pending GitLab to-dos: reviews requested, assignments, mentions, broken builds. When you have
none, the card says **No pending to-do on GitLab**. *A card with to-dos in it was not checked on a
live instance.*

## When there is nothing to show

A card with no row says **Nothing here yet** and, under it, what would fill it. Click **Learn more**
under the sentence to come back to this page.

| Card | What it says |
| --- | --- |
| **Merge Requests** | No open merge request in the GitLab projects named by the components of the catalog (gitlab.com/project-slug annotation) that your token can read. |
| **Pipelines** and **Detailed Pipelines** | No pipeline failed or ran lately in the GitLab projects that your token reads and that a component of the catalog names (gitlab.com/project-slug annotation). |
| **Releases** | No release published in the GitLab projects named by the components of the catalog (gitlab.com/project-slug annotation) that your token can read. |
| **To-Do List** | **No pending to-do on GitLab**, then: GitLab lists no pending to-do for your account: no review requested, assignment, mention or broken build. |

## Change what a card shows

1. On **My Dashboards**, open the tab of the dashboard.

2. At the top right of the card, click the **more** button, then **Edit**. The **Edit card** window has three tabs:

   | Tab | What you do |
   | --- | --- |
   | **General** | Rename the card or change its icon |
   | **Columns** | Switch a column off |
   | **Filters** | Remove a value from a column, so its rows disappear |

3. Click **Save**.

The same menu has **Refresh**, to read GitLab again now, and **Delete**.

✅ That's it!

Next: [Get GitLab notifications](get-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/add-the-alerts-card.md -->

# Add the Alerts in trouble card to your dashboard

The **Alerts in trouble** card lists the Grafana alert rules that **fire**, are **in error** or **get no
data**, the oldest first, on **My Dashboards**.

## Before you start

The [Grafana integration](add-the-integration.md) is added: the card reads Grafana with its token.
Your license covers Grafana (Premium): see
[What a license unlocks](../../../../administration/licensing/what-a-license-unlocks.md). Without it,
**Add a card** says **Grafana requires the Premium license**, with a link **Open the license**.

## ➕ Add the card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, choose **Source** `grafana`. **Key** shows **Alerts in trouble**, with the text
   **Grafana alert rules that fire, are in error or get no data, the oldest first**.

4. Enter a **Card Name**, for example `Alerts`, then click **Add**.

The card shows its name, then **No alert in trouble** when every rule is fine, with the sentence "No
alert rule is firing, in error or without data for the components of the catalog
(grafana/alert-label-selector annotation)."

## What it lists

The alert rules designated by the `grafana/alert-label-selector` annotation of **every component of the
catalog**, whoever owns the component, and only the rules that fire, are in error or get no data. A
component without the annotation adds nothing. Two columns, **Owner** and **Mine**, say who owns the
component and whether it is yours (**Mine** or **Others**): to keep only your alerts, filter on **Mine**
and save the filter with the card, see
[Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

*A card with alerts in it was not checked on a live instance: no alert was firing.*

## 🔔 Be told when an alert fires

**My account › Notifications** has a line **Grafana — When an alert is triggered**, marked
**CRITICAL**. See [Choose your notifications](../../../../developer-dashboard/notifications/choose-your-notifications.md).

✅ That's it!

Something is wrong? See [Common problems with Grafana](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/add-the-integration.md -->

# Add the Grafana integration

The integration gives Astrolabe the address of your Grafana and a token to read it. It feeds the
**Monitoring** tab of your components and the **Alerts in trouble** card of **My Dashboards**.

You do it once, as an administrator. The same token serves the tab and the card: there is nothing
else to enter.

## Before you start

You need the address of your Grafana and a service account token: see
[Create a Grafana service account token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Grafana** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name for you | `Grafana` |
   | **Grafana address** | The web address of Grafana, **with** `https://` | `https://grafana.example.com` |
   | **Service account token** | The token you created | |

6. Click **Test connection**. The form says **Connection works: the source accepted the credentials.**

7. Click **Add**. The form warns: **The instance will restart after confirmation.** The screen says
   **Please wait while the instance is reloading...** Wait a few seconds.

The token is in the list, with **State** set to **Connected**. On **Company connections**, the **Grafana**
card now says **Connected** and its button reads **Manage**.

✅ That's it!

Next: [Show the Monitoring tab on a component](show-the-monitoring-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/create-a-token.md -->

# Create a Grafana service account token

Astrolabe reads Grafana with **a service account token**. The **Viewer** role is enough: Astrolabe only
reads your alerts and dashboards, it never changes anything in Grafana.

You create the token once, in Grafana.

:::tip Use a dedicated service account
Create a service account for Astrolabe, for example `astrolabe`. A service account does not belong to a
person, so the token keeps working when someone leaves.
:::

## 🔑 Create the token

1. In Grafana, open the menu, then **Administration**, then **Users and access**, then **Service
   accounts**.

2. Click **Add service account**.

3. In **Display name**, enter `astrolabe`. In **Role**, choose `Viewer`.

4. Click **Create**.

5. Click **Add service account token**, then **Generate token**.

6. **Copy the token now.** Grafana never shows it again.

These steps happen in Grafana. They were not checked on a live instance.

✅ That's it!

Next: [Add the Grafana integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/faq.md -->

# Grafana FAQ

## Does Grafana need a license?

Yes, the Premium license. Without a license that covers it, the **Monitoring** tab is not on the
components and the **Alerts in trouble** card is closed: see
[Common problems with Grafana](troubleshooting.md).

## Which token?

A Grafana **service account token** with the **Viewer** role. See
[Create a Grafana service account token](create-a-token.md).

## Does Astrolabe change anything in Grafana?

No. Astrolabe only reads: alerts and dashboards.

## Do I enter Grafana twice?

No. The **Grafana** plugin card has no settings. The address and the token are entered once, in
**Administration › Company connections**, and serve both the tab and the card.

## Who sees the Monitoring tab?

Anyone who can open the component. Astrolabe reads Grafana with the token of the integration, the same for
every reader.

## The tab is missing on a component. Why?

The tab only exists on a component annotated `grafana/dashboard` or `grafana/alert-label-selector`, when the
**Grafana** plugin is turned on. See [Show the Monitoring tab](show-the-monitoring-tab.md).

## Do I need a dashboard to see alerts?

No. `grafana/alert-label-selector` alone shows the tab with its alerts.

## Does the card show only my components?

No: it lists the alerts of **every component of the catalog** that carries the
`grafana/alert-label-selector` annotation. Filter the column **Mine** to keep yours: see
[Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/show-the-monitoring-tab.md -->

# Show the Monitoring tab on a component

Each annotated component gets a **Monitoring** tab: the Grafana alerts that concern it and the panels of
its Grafana dashboard, drawn by Astrolabe.

Two steps: turn on the plugin, annotate the component.

## What the tab shows, and to whom

At the top, four period buttons: **1 h**, **6 h**, **24 h** and **7 d**. **24 h** is selected when you open
the tab.

Under **Alerts**, a table with one line per alert rule:

| Column | What |
| --- | --- |
| **State** | The state of the rule |
| **Rule** | The name of the rule |
| **Severity** | Its severity |
| **Summary** | Its summary |

Below, the panels of the dashboard named by the component.

Anyone who can open the component sees the tab. Astrolabe reads Grafana with **the token of the
integration**, the same for everyone.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **Grafana** card, turn on the switch at the top right.

If the card says **Requires the Premium license**, the switch is grey: Grafana is part of the Premium
license. Click the line, [add a license](../../../../administration/licensing/add-your-license.md) that
covers it, then come back to this step.

If the card says **Configure the Grafana integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Grafana integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.

The card has no settings: Grafana is entered once, in
[the integration](add-the-integration.md).

## 2. 🏷️ Annotate the component

In the `catalog-info.yaml` file of the component, add one or both of these annotations. **One is
enough** to show the tab.

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    grafana/dashboard: shop-api-overview
    grafana/alert-label-selector: service=shop-api
spec:
  type: service
  lifecycle: production
  owner: team-a
```

| Annotation | What to write | Example |
| --- | --- | --- |
| `grafana/dashboard` | The UID of the dashboard: in Grafana, the part after `/d/` in its address | `shop-api-overview` |
| `grafana/alert-label-selector` | A label of your alert rules, as `name=value` | `service=shop-api` |
| `grafana/panels` | Optional. The ids of the panels to draw, separated by commas. Leave it out to draw every panel | `2,4` |
| `grafana/variables` | Optional. Values for the variables of the dashboard, as `name=value`, separated by commas | `env=prod` |

The drawing of the panels was not checked on a live instance.

## ✅ Check

Open the component in **Catalog**. A **Monitoring** tab is in the tab bar, next to **Overview**. Click
it: the alerts table and the period buttons are there.

✅ That's it!

Something is wrong? See [Common problems with Grafana](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/grafana/troubleshooting.md -->

# Common problems with Grafana

## When you add the integration

| What you see | What to do |
| --- | --- |
| `grafana.example.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong, expired or deleted. Create a new one: see [Create a Grafana service account token](create-a-token.md). |
| `No server answers to the name grafana.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Check **Grafana address**: the address you open in your browser, with `https://`. If it is right, your Grafana is not reachable from Astrolabe. |

## In Administration

| What you see | What to do |
| --- | --- |
| In **Company connections › Grafana**, **State** says `grafana.example.com refused the credentials (401). Check the token, and that it has not expired.` | Click the **Edit Token** icon, click **Replace**, paste a new token, click **Test connection**, then **Save**. |
| In **Problems**: `grafana.example.com refuses the credentials (401). The token may be wrong or expired.` | Click **Fix it** to open the integration, replace the token, then click **Check again**. |

## When the license does not cover Grafana

| What you see | What to do |
| --- | --- |
| In **Administration › Plugins**, the **Grafana** card says **Requires the Premium license**, and the switch is grey | Your license does not cover Grafana. [Add a license](../../../../administration/licensing/add-your-license.md) that does, then switch the plugin on. |
| In **Administration › Plugins**, the **Grafana** card says **Not licensed**, and **Problems** shows **Switched on, but the license does not cover it.** | Click **Fix it**: the license screen opens. [Add a license](../../../../administration/licensing/add-your-license.md) that covers Grafana. |
| On the card, `Your license does not cover Grafana.` `Grafana is part of a higher license: its data stays closed until the license covers it. An administrator reads which one in Administration › Licensing.` and a link **Open the license** | Click **Open the license**: **Administration › Licensing** opens. [Add a license](../../../../administration/licensing/add-your-license.md) that covers Grafana. |
| On the card, the same text with `Only an Astrolabe administrator can fix this: tell them what this message says.` and no link | You are not an administrator. Send this message to yours. |
| In **Add a card**, the title `Grafana requires the Premium license`, then `Its cards stay closed until the license covers it. An administrator reads which license it needs in Administration › Licensing.` and a link **Open the license** | Same cause. Click **Open the license**, then [add a license](../../../../administration/licensing/add-your-license.md) that covers Grafana. |
| On the **Grafana** card of **Company connections › Webhooks**, `1 events reached nobody: the license does not cover this source, so its events are dropped. See Administration › Licensing.` | Grafana called Astrolabe, and Astrolabe dropped the alert. [Add a license](../../../../administration/licensing/add-your-license.md) that covers Grafana. |
| On the **Monitoring** tab, `Your license does not cover Grafana.` or `The license could not be checked.` | The tab says the same as the card: add a license that covers Grafana, or try again in a minute. *Not verified on an instance yet: the tab is not shown once the license no longer covers Grafana.* |

## On the Monitoring tab of a component

| What you see | What to do |
| --- | --- |
| No **Monitoring** tab | Add the `grafana/dashboard` or `grafana/alert-label-selector` annotation to the component, and turn on the **Grafana** plugin in **Administration › Plugins**. |
| `Grafana refused the token. The token may have expired or been revoked: replace it in Administration › Company connections › Grafana (or in My account › My accounts if it is your own).` and a link **Open the Grafana integration** | Click the link and replace the token. |
| `No alert rule carries the labels service=shop-api.` | No alert rule of Grafana has this label. Check `grafana/alert-label-selector` against the labels of your rules in Grafana. |
| `The dashboard shop-api-overview or one of its panels does not exist, or is out of the token reach: check the grafana/dashboard and grafana/panels annotations.` | Check the UID in `grafana/dashboard` and the ids in `grafana/panels`, and that the service account can see the dashboard. |

## On the card

| What you see | What to do |
| --- | --- |
| `Grafana refused the token. The token may have expired or been revoked: replace it in Administration › Company connections › Grafana (or in My account › My accounts if it is your own).` | Click **Open the Grafana integration** and replace the token. |
| **No alert in trouble** | Nothing to fix: no rule fires, fails or lacks data. |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this Grafana feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves Grafana. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its Grafana dashboard.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration.md -->

# Connect your tools

An integration gives Astrolabe the address and the token of one of your tools. The administrator adds
it once, in **Administration › Company connections**. Then the tool shows up where your teams look:
on the page of each component, on their dashboard, in the catalog.

## 🧰 The tools

| Tool | What it brings | Start here |
| --- | --- | --- |
| **GitHub** | Pipelines, pull requests, branches and releases of a component; dashboard cards | [Add the integration](github/add-the-integration.md) |
| **GitLab** | Pipelines, merge requests, branches and releases of a component; dashboard cards | [Add the integration](gitlab/add-the-integration.md) |
| **Jira** | The open issues of a component's project, in a tab; dashboard cards | [Connect Jira Cloud](jira/connect-jira-cloud.md) |
| **Argo CD** | A component's Argo CD application, its health and deployments | [Add the integration](argocd/add-the-integration.md) |
| **Jenkins** | The builds of a component; dashboard cards | [Add the integration](jenkins/add-the-integration.md) |
| **SonarQube** | The code quality of a component | [Add the integration](sonarqube/add-the-integration.md) |
| **Codacy** | A component's Codacy grade, and its issues in a tab | [Add the integration](codacy/add-the-integration.md) |
| **Grafana** | A component's Grafana alerts and dashboards, in its Monitoring tab | [Add the integration](grafana/add-the-integration.md) |
| **Terraform Cloud** | A component's workspaces and their last runs | [Add the integration](terraform/add-the-integration.md) |
| **LaunchDarkly** | The feature flags of a component | [Add the integration](launchdarkly/add-the-integration.md) |
| **Azure DevOps** | Pipelines, pull requests and work items on your dashboard | [Add the integration](azure-devops/add-the-integration.md) |
| **Azure Cloud** | A component's Azure resources and what they cost | [Add the integration](azure-cloud/add-the-integration.md) |
| **Bitbucket Server**, **Bitbucket Cloud** | Your repositories in the catalog | [Bitbucket Server](bitbucket-server/add-the-integration.md), [Bitbucket Cloud](bitbucket-cloud/add-the-integration.md) |
| **Confluence** | The pages of your Confluence, found by the search | [Add the integration](confluence/add-the-integration.md) |
| **AWS** | An AWS access key | [Add the integration](aws/add-the-integration.md) |

## 🔢 The steps, for every tool

1. **Create a token** in the tool. Each page says which rights it needs.

2. **Add the integration** in **Administration › Company connections**, and click **Test connection**.

3. **Turn on its plugin**, if it has one, in **Administration › Plugins**: see
   [Turn on a plugin](../../../administration/plugins/turn-on-a-plugin.md).

4. **Annotate your components** in their `catalog-info.yaml`, so that their tab shows up. Each tool's
   page gives its annotation.

## 🔑 Two tokens: the company's, and yours

GitHub, GitLab, Jira and Azure DevOps read with **the company's token** for the component tabs, the
catalog and Compass, and with **your own account** for your dashboard cards. See
[The company's token and your own account](company-token-and-my-account.md).

:::tip Something does not work?
Each tool has its **Common problems** page. For the whole instance, start with
[Find and fix a problem](../../../administration/problems/find-and-fix-a-problem.md).
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/add-the-dashboard-cards.md -->

# Add the Jenkins cards to your dashboard

The Jenkins cards of **My Dashboards** show the builds of **the components of the catalog**, so you see
at a glance what ran and what failed, without opening Jenkins.

## Before you start

- Your administrator has [added the Jenkins integration](add-the-integration.md). The cards need
  nothing from you: no token to enter, Astrolabe reads Jenkins with the integration.
- Your components are annotated `jenkins.io/job-full-name`. See
  [Show the Jenkins tab on a component](show-the-tab.md#2-annotate-the-component).

## The cards

| Key | What it shows |
| --- | --- |
| **Builds** | The builds of the Jenkins job of each component of the catalog, with their status and date |
| **Detailed Builds** | The same builds, with their duration and the stages of each build |

Both cards list **every component of the catalog** that carries the `jenkins.io/job-full-name`
annotation, whoever owns it. A component without the annotation does not appear. Both cards show five
rows at a time, with the most recent build of each job first.

To keep only your components, filter the column **Mine** (**Mine** or **Others**) and save the filter
with the card: see [Keep only your rows](../../../../developer-dashboard/my-dashboard/change-or-remove-a-card.md#-keep-only-your-rows).

*A card with builds in it was not checked on a live instance: no Jenkins was connected.*

### The columns

| Column | What it says | Cards |
| --- | --- | --- |
| **Resource** | The full name of the Jenkins job, for example `catalog-api` or `shop/shop-api` | Both |
| **Title** | The build, for example `catalog-api #3` on **Builds**, and the name of the job on **Detailed Builds** | Both |
| **Key** | The number of the build, for example `#3` | Both |
| **Owner** | The owner of the component | Both |
| **Mine** | **Mine** when the component is yours (you or one of your groups own it), **Others** otherwise | Both |
| **Status** | `success`, `failed` or another word of Jenkins in a coloured badge | Both |
| **Date** | The day of the build | Both |
| **Duration** | How long the build took | **Detailed Builds** |
| **Stages** | The stages of the build, each with its status | **Detailed Builds** |
| Last column | A link that opens the build in Jenkins | Both |

A job in a folder shows with its whole path in **Resource**, for example `shop/shop-api`. A job that is
not a pipeline has no stages: the build is on both cards, and **Stages** shows `-`.

## ➕ Add a card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick **Source** `jenkins`, then a **Key**: **Builds** or **Detailed Builds**.
   The description under the key tells what the card shows.

4. Enter a **Card Name**, then click **Add**.

The card fills in a few seconds.

✅ That's it!

## What the cards say when something is wrong

| What the card says | What it means |
| --- | --- |
| **Nothing here yet** and "No build to show: no component of the catalog has a jenkins.io/job-full-name annotation, or its job has no build yet." | No component of the catalog has a `jenkins.io/job-full-name` annotation, or its job has no build yet |
| **Jenkins refused the token.** and "The token may have expired or been revoked: replace it in Administration › Company connections › Jenkins (or in My account › My accounts if it is your own)." | Jenkins no longer accepts the token of the integration. The button **Open the Jenkins integration** takes you to the screen where it is replaced. See [Common problems with Jenkins](troubleshooting.md#on-my-dashboards). |
| **Jenkins refuses the connection.** and "Check the host and port in Administration › Company connections › Jenkins, and that the service runs." | Astrolabe cannot reach Jenkins. The button **Open the Jenkins integration** opens the integration. |
| **Jenkins does not know what is asked.** and "Check the name in the component's annotation, and that the token may see it." | Jenkins knows none of the jobs written in your components. Check the names. See [Common problems with Jenkins](troubleshooting.md#on-my-dashboards). |

A job Jenkins does not know is left out while the others still show.

## Notifications

This step was not checked on a live instance. You choose what you receive in **My Account ›
Notifications**.

Next: [Jenkins FAQ](faq.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/add-the-integration.md -->

# Add the Jenkins integration

The integration gives Astrolabe the address of your Jenkins, its user and its token. You do it once,
as an administrator. It is the only place where you enter Jenkins, and it also feeds the Jenkins cards
of **My Dashboards**.

**Before you start**: a Jenkins user name and its API token, see
[Create a Jenkins API token](create-a-token.md).

## How to

### 1. Open the Jenkins integration

1. In the left sidebar, at the bottom, click **Administration**.
2. Under **PLATFORM**, click **Company connections**.
3. On the **Jenkins** card, click **Configure**.
4. Top right, click **Add Token**.

### 2. Fill in the form

| Field | What to enter | Example |
| --- | --- | --- |
| **Name** | A name of your choice | `Jenkins` |
| **Jenkins instance URL** | The address of Jenkins, without `https://` | `jenkins.example.com` |
| **Jenkins user** | The user of the token | `astrolabe` |
| **Jenkins token** | The API token you created | |

### 3. Test and save

1. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**
2. Click **Add**. Astrolabe restarts on its own, in a few seconds.

The token is in the list, with **State** set to **Connected**.

✅ Done. Next: [Show the Jenkins tab on a component](show-the-tab.md).

## You have several Jenkins

Add one integration per Jenkins, and give each one an **instance key**.

1. On the **Jenkins** card, click **Manage**, then **Add Token** for each Jenkins.
2. In the form, open **Optional settings** and fill in **Jenkins instance key** with a short name:
   letters, digits, `.`, `_` and `-`.

| Jenkins | Name | Jenkins instance key |
| --- | --- | --- |
| Production | `Jenkins prod` | `prod` |
| Other environments | `Jenkins dev` | `dev` |

A component then picks its Jenkins in its annotation: see
[Show the Jenkins tab on a component](show-the-tab.md#you-have-several-jenkins).

:::tip The default Jenkins
A job name without an instance key is read from the integration whose instance key is `default`,
otherwise from the first one in the list.
:::

## Replace a token

When a token has expired or was revoked:

1. On the **Jenkins** card, click **Manage**.
2. On the line of the token, click **Edit Token**.
3. Next to **Jenkins token**, click **Replace**, then paste the new token.
4. Click **Test connection**, then **Save**. Astrolabe restarts on its own, in a few seconds.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/create-a-token.md -->

# Create a Jenkins API token

Astrolabe reads Jenkins with **a Jenkins user name and its API token**. You create the token once, in
Jenkins.

## Pick the Jenkins user

The token has **the rights of its user**. Astrolabe only sees the jobs this user can see.

:::tip Use a dedicated user
Create a Jenkins user for Astrolabe, for example `astrolabe`, that can read the jobs of your teams.
Your own account works too, but Astrolabe stops working the day you leave.
:::

## 🔑 Create the token

1. Log in to Jenkins with this user.

2. Top right, click the user name.

3. In the left menu, click **Security**.

4. Under **API Token**, click **Add new token**.

5. In **Name**, write `Astrolabe`, then click **Generate**.

6. **Copy the token now.** Jenkins says: **Copy this token now, because it cannot be recovered in the
   future.** Then click **Done**.

✅ That's it!

Next: [Add the Jenkins integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/faq.md -->

# Jenkins FAQ

## Where do I enter my Jenkins?

Only in the integration: **Administration › Company connections › Jenkins**. See
[Add the Jenkins integration](add-the-integration.md).

## Which token?

A Jenkins **API token** of a user who can read your jobs. See
[Create a Jenkins API token](create-a-token.md). Not the password of the user.

## Who sees the builds?

Anyone who can open the component. Astrolabe reads Jenkins with the user and the token of the
integration, the same for every reader.

## The tab is missing on a component. Why?

The tab only exists on a component annotated `jenkins.io/job-full-name`, when the **Jenkins** plugin
is turned on. See [Show the Jenkins tab](show-the-tab.md).

## I have several Jenkins. How does a component pick one?

By the start of its annotation: `jenkins.io/job-full-name: prod:shop-api` reads the job `shop-api`
from the integration whose **Jenkins instance key** is `prod`. See
[Show the Jenkins tab](show-the-tab.md#you-have-several-jenkins).

## Can a component show several jobs?

Yes: write their full names separated by a comma, on the same Jenkins. See
[Show the Jenkins tab](show-the-tab.md#several-jobs-on-one-component).

## Which components does a card show?

Every component of the catalog that carries the `jenkins.io/job-full-name` annotation, whoever owns it.
Filter the column **Mine** to keep yours. See
[Add the Jenkins cards to your dashboard](add-the-dashboard-cards.md).

## Do I need my own token for the cards?

No. The cards read Jenkins with the user and the token of the integration, like the tab.

## Can I show a job that is in a folder?

Yes: write the folders and the job separated by `/`, for example `shop/shop-api`.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/show-the-tab.md -->

# Show the Jenkins tab on a component

Each annotated component gets a **Jenkins** tab with its builds, and a **Latest master build** card
on its **Overview**.

## How to

### 1. Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.
2. On the **Jenkins** card, turn on the **Enable Jenkins** switch.

If the card says **Configure the Jenkins integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Jenkins integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.

### 2. Annotate the component

In the component's `catalog-info.yaml`, add the full name of its Jenkins job:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    jenkins.io/job-full-name: shop-api
spec:
  type: service
  lifecycle: production
  owner: team-a
```

:::tip Where is the full name?
It is the path of the job in the address bar of Jenkins, without `job/`. The job
`https://jenkins.example.com/job/shop/job/shop-api/` is written `shop/shop-api`.
:::

### 3. Check

Open the component in **Catalog**. A **Jenkins** tab is next to **Overview**. Click it: the job is
listed with its last build.

✅ Done.

## What it shows, and to whom

| Column | What |
| --- | --- |
| **Build** | The job name, with a link. A folder of branches gives one line per branch, for example `shop » master` |
| **Tests** | The test results, or `n/a` |
| **Status** | For example **Completed** |
| **Last Run Duration** | For example `0.1 s` |
| **Actions** | **View build** opens the build in Jenkins |

On **Overview**, the **Latest master build** card shows the **Status**, the **Build**, the **Latest
Run** and the **Duration** of the last build of the job `master`, with a link **See more on
Jenkins**. It reads the job named `master` inside your job: use a job that has a `master` branch.

Anyone who can open the component sees the tab and the card. Astrolabe reads Jenkins with the
user and the token of the integration, the same for every reader.

## Several jobs on one component

Write the full names separated by a comma. They must be on the same Jenkins.

```yaml
metadata:
  annotations:
    jenkins.io/job-full-name: shop-api,shop/shop-api-tests
```

The tab lists the builds of every job.

## You have several Jenkins

Start the annotation with the **instance key** of the integration, then `:`, then the job name:

```yaml
metadata:
  annotations:
    jenkins.io/job-full-name: prod:shop-api
```

Here, `prod` is the **Jenkins instance key** of the production Jenkins integration.

Next: [Add the Jenkins cards to your dashboard](add-the-dashboard-cards.md).

Something is wrong? See [Common problems with Jenkins](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jenkins/troubleshooting.md -->

# Common problems with Jenkins

## When you add the integration

| What you see | What to do |
| --- | --- |
| `jenkins.example.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The user or the token is wrong. Check **Jenkins user**, then create a new token: see [Create a Jenkins API token](create-a-token.md). |
| `No server answers to the name jenkins.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator. Fix the field above, or save anyway if the source is only unreachable for now.` | Check **Jenkins instance URL**: the address you open in your browser, without `https://`. If it is right, your Jenkins is not reachable from Astrolabe. |

## On the Plugins screen

| What you see | What to do |
| --- | --- |
| **Configure the Jenkins integration first** instead of a switch on the **Jenkins** card | [Add the Jenkins integration](add-the-integration.md). The switch appears once it is added. |

## On the component page

| What you see | What to do |
| --- | --- |
| No **Jenkins** tab | Add the `jenkins.io/job-full-name` annotation to the component, and turn on **Enable Jenkins** in **Administration › Plugins**. |
| **No records to display** in the **Jenkins** tab | Check the annotation: the full name of the job must be the path of the job in Jenkins, for example `shop/shop-api`. If it starts with a prefix, as in `prod:shop-api`, `prod` must be the **Jenkins instance key** of one of your integrations, or remove `prod:` to read from the default Jenkins. |
| **No records to display**, and the annotation is right | The token may have expired or been revoked. In **Administration › Company connections**, on the **Jenkins** card click **Manage**, then **Edit Token**, and click **Test connection**. If it says the credentials are refused, [replace the token](add-the-integration.md#replace-a-token). |
| The **Latest master build** card on **Overview** says `Jenkins has no build for the branch "master" of this component's job. The card looks for that branch: check the job name in the jenkins.io/job-full-name annotation, and that the job builds a "master" branch.` | The card reads the branch `master` of your job. Check the job name in the annotation, and use a job that builds a `master` branch. |
| The same card says `Jenkins did not answer for the branch "master" (HTTP 500).` | Same check, then the Jenkins connection in **Administration › Company connections › Jenkins**. The words in brackets say what Jenkins answered (`no answer` or `HTTP` and a number). |
| The same card says `Jenkins did not answer (no answer).` | Check the Jenkins connection in **Administration › Company connections › Jenkins**. |

## On My Dashboards

| What you see | What to do |
| --- | --- |
| **Nothing here yet** and `No build to show: no component of the catalog has a jenkins.io/job-full-name annotation, or its job has no build yet.` on a Jenkins card | The card lists the components **of the catalog**. Check that one of them has the `jenkins.io/job-full-name` annotation: see [Show the Jenkins tab on a component](show-the-tab.md#2-annotate-the-component). |
| **Jenkins refused the token.** | The token of the integration expired or was revoked. Click **Open the Jenkins integration**, then on the token click **Edit Token**, **Replace**, paste the new token and click **Test connection**, then **Save**. To create a token, see [Create a Jenkins API token](create-a-token.md). |
| **Jenkins refuses the connection.** | Astrolabe cannot reach Jenkins. Click **Open the Jenkins integration** and check **Jenkins instance URL**: the host and the port, without `https://`. Check that Jenkins is running. |
| **Jenkins does not know what is asked.** | Jenkins knows none of the jobs written in your components. Check each name against the path of the job in Jenkins, for example `shop/shop-api` for the job `shop-api` in the folder `shop`. |
| The builds of one component are missing, the others show | The annotation of that component names a job Jenkins does not know. Check the name, as above. |
| The **Stages** column shows `-` | The job is not a pipeline, so it has no stages. The build is shown with its status and its duration. |

*Not verified on an instance yet: the three messages of the **Latest master build** card, no Jenkins is connected to the test instance.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its Jenkins job.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/add-the-dashboard-cards.md -->

# Add your Jira issues to your dashboard

The Jira cards of **My Dashboards** show what **your own** Jira account sees. You add a card, then you
connect your account from the card itself, once.

## Before you start

Your administrator has connected Jira ([Data Center](connect-jira-data-center.md) or
[Cloud](connect-jira-cloud.md)). Without it, the `jira` source is not in the list.

## ➕ 1. Add a card

1. In the left sidebar, click **My Dashboards**, then the tab of the dashboard you want.

2. Click **Add a card**, at the top of the page.

3. In **Add a card**, pick the **Source** `jira`, then a **Key**:

   | Key | What it lists |
   | --- | --- |
   | **My Open Issues** | Open Jira issues assigned to you, most recently updated first |
   | **My Sprint** | Jira issues assigned to you in the sprint that is running, with the name of the sprint |
   | **To Review** | Jira issues where you are reviewer or mentioned |
   | **JQL Query** | The issues of a JQL query you write in the **jql** field |

4. For **JQL Query**, fill in **jql** with a Jira search, as you would type it in Jira's advanced
   search. For example:

   | You want | **jql** |
   | --- | --- |
   | All the issues of one project | `project = SHOP ORDER BY updated DESC` (replace `SHOP` with your project key) |
   | The open issues of one project | `project = SHOP AND statusCategory != Done ORDER BY updated DESC` |
   | The unresolved issues created this week | `resolution = Unresolved AND created >= startOfWeek() ORDER BY created DESC` |

5. Enter a **Card Name**, then click **Add**.

## 🔑 2. Connect your Jira account, in the card

The first time, the card says **Your Jira account is not connected.**

1. In the card, click **Connect my Jira account**. The **Connect my Jira account** window opens. It
   says where to create your token, and links to the page that creates it.

2. Create the token on that page:
   - Jira Cloud (`.atlassian.net`): an **API token** (`id.atlassian.com` › **Security** › **Create and
     manage API tokens**);
   - your company's Jira (Data Center): a **personal access token** (your avatar › **Profile** ›
     **Personal Access Tokens** › **Create token**).

   No Jira administrator right is needed.

3. Back in the window, fill in:

   | Field | Jira Cloud | Your company's Jira (Data Center) |
   | --- | --- | --- |
   | **Username** | The e-mail of your Atlassian account | Your Jira username |
   | **Token** | Your API token, pasted as is | Your personal access token, pasted as is |

4. Click **Test Connection**. The window says **Connection works: the tool accepted your token.**

5. Click **Save**. The window closes and every Jira card of your dashboard reads again.

✅ That's it!

:::tip Change or remove your token
Your Jira account is listed in **My Account › My accounts** (your avatar, top right, then **My
Account**, then the **My accounts** tab). Click **Configure** on the **Jira** card to change or delete
the token.
:::

Next: [What each Jira card shows](what-the-cards-show.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/connect-jira-cloud.md -->

# Connect Jira Cloud

Your Jira address ends in `.atlassian.net`. Astrolabe reads it with **the e-mail and an API token**
of an Atlassian account. You do this once, as an Astrolabe administrator.

Your address is something else, like `https://jira.example.com`? See
[Connect your company's Jira (Data Center)](connect-jira-data-center.md).

## 🔑 1. Create an API token in Atlassian

No Jira administrator right is needed: the token reads what its owner can see in Jira.

1. Log in to `id.atlassian.com` with the account Astrolabe will read with.
2. Open **Security**, then **Create and manage API tokens**.
3. Click **Create API token**, give it a name (`Astrolabe`), then **Create**.
4. Copy the token **as is**.

## 🔌 2. Add the Jira Cloud integration

1. In the left sidebar, at the bottom, click **Administration**.
2. Under **PLATFORM**, click **Company connections**.
3. On the **Jira Cloud** card, click **Configure**.
4. Top right, click **Add Token**.
5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice | `Jira Cloud` |
   | **Jira Cloud URL** | The address of your Jira site, with `https://` | `https://example.atlassian.net` |
   | **E-mail** | The e-mail of the Atlassian account that owns the token | `astrolabe@example.com` |
   | **API token** | The token of step 1, pasted as is | |

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**
7. Click **Add**. Astrolabe restarts on its own, in a few seconds.

The token is in the list, with **State** set to **Connected**.

✅ That's it!

Next: [Show the Jira tab on a component](show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/connect-jira-data-center.md -->

# Connect your company's Jira (Data Center)

Your company runs its own Jira, at an address like `https://jira.example.com`. Astrolabe reads it
with **a personal access token**. You do this once, as an Astrolabe administrator.

:::tip Is my Jira a Jira Data Center?
Look at the address you open in your browser. It ends in `.atlassian.net`? That's Jira Cloud: see
[Connect Jira Cloud](connect-jira-cloud.md). Any other address is your company's own Jira: you are on
the right page.
:::

## 🔑 1. Create a personal access token in Jira

No Jira administrator right is needed: the token reads what its owner can see in Jira.

1. Log in to Jira with the account Astrolabe will read with.
2. Top right, click your avatar, then **Profile**.
3. In the left menu, click **Personal Access Tokens**.
4. Click **Create token**, give it a name (`Astrolabe`), choose an expiry date, then click **Create**.
5. Copy the token **as is**: Jira shows it only once.

:::tip Use a dedicated account
Every Astrolabe user reads the **Jira** tab of a component through this token. Ask for a Jira
account named `astrolabe`, with access to your teams' projects: Astrolabe keeps working when people
leave.
:::

## 🔌 2. Add the Jira Data Center integration

1. In the left sidebar, at the bottom, click **Administration**.
2. Under **PLATFORM**, click **Company connections**.
3. On the **Jira Data Center** card, click **Configure**.
4. Top right, click **Add Token**.
5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name of your choice | `Jira Data Center` |
   | **Jira URL** | The address of your Jira, with `https://`, the one you open in your browser | `https://jira.example.com` |
   | **Personal access token** | The token of step 1, pasted as is | |

   You don't enter your username: the token is enough.

6. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.** *This step was not checked on a live instance.*
7. Click **Add**. Astrolabe restarts on its own, in a few seconds.

The token is in the list, with **State** set to **Connected**.

✅ That's it!

Next: [Show the Jira tab on a component](show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/faq.md -->

# Jira FAQ

## Jira Cloud or Jira Data Center: which one is mine?

Look at the address of your Jira. It ends in `.atlassian.net`: Jira Cloud. Anything else, like
`https://jira.example.com`: your company's own Jira, to connect as **Jira Data Center**.

## Do I need to be a Jira administrator?

No. A personal access token (Data Center) or an API token (Cloud) is enough: it reads what its owner
can see in Jira.

## Why two tokens, one in Administration and one in My Account?

The administration's token reads the **Jira** tab of every component, the same for everyone. Your own
token reads **your** dashboard cards: your issues, as your Jira account sees them. You connect it from
the card itself. See [The company's token and your own account](../company-token-and-my-account.md).

## Do I enter my username for Jira Data Center?

Not in the administration: the personal access token is enough. When you connect your own account
(from a card, or **My Account › My accounts**), enter your Jira username: the form asks for it.

## Can I connect two Jira?

Yes: one Jira Cloud and one Jira Data Center, each on its own card.

## What does the To Review card list?

The Jira issues where you are reviewer or mentioned, as its description says. With none, it says
**Nothing here yet** and **No Jira issue is waiting for your approval.** See [What each Jira card shows](what-the-cards-show.md).

## Can a product owner see all the tickets of a project?

**Yes.** Add the **JQL Query** card and write `project = SHOP ORDER BY updated DESC` in its **jql**
field (replace `SHOP` with the key of the project): the card lists every ticket of the project that the
Jira account of the product owner can see, whoever it is assigned to. Past 1000 tickets, the card says
so. *Not checked on a live instance: no Jira account was connected.*

## Can I write my own query?

**Yes**, with the **JQL Query** card: you write the query in its **jql** field when you add the card,
and change it later in the card's **⋮** menu › **Edit**. See [What each Jira card shows](what-the-cards-show.md).

## Which Jira events does Astrolabe tell me about?

The comments and status changes of your issues, and when you are assigned or unassigned: you choose in
**My Account › Notifications**. See [Get Jira notifications](get-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/get-notifications.md -->

# Get Jira notifications

Astrolabe tells you about your Jira issues in the bell at the top right: a comment, a new status, an
assignment. You choose which events.

## Before you start

Your administrator has set up the Jira webhook (see below).

## 🔔 Choose your Jira events

1. At the top right, click your avatar, then **My Account**.

2. Open the **Notifications** tab.

3. In the **What do you want to receive?** card, find the **Jira** section. Each event has two
   switches: **In Astrolabe** (the bell) and **On this browser**.

   | Event |
   | --- |
   | **Comments on your issues** |
   | **Status updates on your issues** |
   | **When you are (un)assigned to an issue** |
   | **When an issue assigned to you is created** |

4. Switch an event off or on. It is saved right away.

For the browser column, see
[Choose your notifications](../../../../developer-dashboard/notifications/choose-your-notifications.md).

✅ That's it!

## 🔗 For the administrator: set up the webhook

Jira sends its events to Astrolabe through a webhook.

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**, then open the **Webhooks** tab.

3. On the **Jira Cloud** card, click **Configure**.

4. In the window, next to **Webhook URL**, click **Copy address**. The button says **Copied**.

5. In **Webhook Secret**, type a secret of your choice, then click **Save Secret**.

6. In Jira, add a webhook: paste the address as its URL, and use the same secret. *This step was not checked on a live instance, nor was the arrival of the notifications.*

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/show-the-tab.md -->

# Show the Jira tab on a component

Each annotated component gets a **Jira** tab: the open issues of its Jira project, most recently
updated first.

**Before you start**: a Jira integration is added, [Data Center](connect-jira-data-center.md) or
[Cloud](connect-jira-cloud.md).

## 🔛 1. Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.
2. On the **Jira** card, turn on the **Enable Jira** switch.

## 🏷️ 2. Annotate the component

In the component's `catalog-info.yaml`, add the **key** of its Jira project: the prefix of its issue
numbers, `SHOP` for `SHOP-42`.

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    jira/project-key: SHOP
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
```

## 👀 3. Check

Open the component in **Catalog**: the **Jira** tab lists **Issue**, **Summary**, **Status** and
**Updated**.

✅ That's it!

## What it shows, and to whom

Anyone who can open the component sees its tab. Astrolabe reads Jira with the token of the
integration, the same for every reader.

Something is wrong? See [Common problems with Jira](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/troubleshooting.md -->

# Common problems with Jira

## When you add the integration

| What you see | What to do |
| --- | --- |
| `jira.example.com refused the credentials (401). Check the token, and that it has not expired.` | Create a new token ([Data Center](connect-jira-data-center.md), [Cloud](connect-jira-cloud.md)) and paste it as is. For Jira Cloud, check the **E-mail**: it must be the one of the account that owns the token. |
| `jira.example.com accepted the token but refuses access (403). Give the token the rights described in the « ? » of the field.` | The token's account cannot use Jira. Log in to Jira with this account: it must see your projects. |
| `This address is a Jira Cloud one (.atlassian.net). Use the Jira Cloud integration for it.` | Your Jira is a Jira Cloud: use the [Jira Cloud](connect-jira-cloud.md) card. |
| `This address is not a Jira Cloud one (they end in .atlassian.net). For your company's own Jira, use the Jira Data Center integration.` | Your Jira is your company's own: use the [Jira Data Center](connect-jira-data-center.md) card. |
| `No server answers to the name jira.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator.` | Copy the address from your browser into the URL field, without path. |

## In My Account, or when you connect your account in a card

| What you see | What to do |
| --- | --- |
| `example.atlassian.net refused your token (401). Check it, and that it has not expired.` | Create a new token of your own and paste it as is: see [Add your Jira issues to your dashboard](add-the-dashboard-cards.md). |

## On a component or your dashboard

| What you see | What to do |
| --- | --- |
| No **Jira** tab on a component | Add the `jira/project-key` annotation, and turn on **Enable Jira** in **Administration › Plugins**: see [Show the Jira tab](show-the-tab.md). |
| The tab says `The project SHOP does not exist, or the token account cannot see it. Check the jira/project-key annotation of the component.` | The key written in `jira/project-key` is not a Jira project, or the account of the token cannot open it. Compare the annotation with the key of the project in Jira, then check that the token's account can open the project. |
| The tab says `No open issue in SHOP.` while the project has open issues | Compare the annotation with the prefix of the project's issues, then check that the token's account can open the project in Jira. |
| A card says `Your Jira account is not connected.` | Click **Connect my Jira account** in the card: see [Connect your Jira account](add-the-dashboard-cards.md). |
| The **jira** source is missing from **Add a card** | Jira is not connected yet: ask your Astrolabe administrator. |
| **Nothing here yet** and `No open Jira issue is assigned to you.` on **My Open Issues** | Your Jira account has no open issue assigned to it. Nothing to fix: the card fills as soon as there is one. |
| **Nothing here yet** and `No Jira issue is waiting for your approval.` on **To Review** | Nothing to fix: the card fills as soon as an issue waits for your approval. |
| **Nothing here yet** and `Your JQL query returns no issue. Check the query.` on **JQL Query** | Open the card menu, click **Edit**, and correct the query in the **jql** field. |
| `Showing the first 1000 issues: Jira holds more. Narrow the query to see the rest.` above the table of a Jira card | The query matches more than 1000 issues. Narrow it in the **jql** field: add a condition, for example `AND statusCategory != Done`. |
| A **JQL Query** card says `Jira answered with an error it did not explain. Check the host and the API address in Administration › Company connections › Jira. If they are right, Jira itself is in trouble: try again later.` | Check the query first: on **My Dashboards**, open the **more** menu of the card, **Edit**, and read the **jql** field. Try the same query in Jira's own issue search: it must run there. |

*Not verified on an instance yet: the message about a project that does not exist, no Jira is connected to the test instance.*

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this Jira feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves Jira. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/jira/what-the-cards-show.md -->

# What each Jira card shows

You have [added a Jira card](add-the-dashboard-cards.md). Here is what it lists. The four cards read
Jira with **your own token**, so they show what your Jira account sees.

All four have the same table.

| Column | What it shows | Shown at first |
| --- | --- | --- |
| **Key** | The issue number, for example `SHOP-42` | Yes |
| **Type** | The type of the issue as your Jira names it, for example `Epic`, `Story`, `Bug` | Yes |
| **Resource** | The Jira project | Yes |
| **Title** | The summary of the issue | Yes |
| **Priority** | Its priority in Jira, for example `Highest`, `High`, `Medium`, `Low`, `Lowest` | Yes |
| **Status** | Its status in Jira, for example `to do`, `in progress`, `done` | No |
| **Estimate** | Its story points, or else its original time estimate. A dash (`-`) when the issue has none. | No |
| **Sprint** | The sprint the issue belongs to. A dash (`-`) when it belongs to none. | No |
| **Date** | Its last update | Yes |

- The statuses present are written at the top right of the card, for example **to do**, **in
  progress**.
- Each row ends with an arrow: click it to open the issue in Jira.
- Under the table, **Show 5 results** lets you pick 5, 10, 25 or 50 rows per page: see
  [Choose how many results a card shows](../../../../developer-dashboard/my-dashboard/choose-how-many-results.md).
  The count (for example **1-5 of 120**) and the arrows **Previous table page** and **Next table page**
  move through the pages.

The cards read **all the pages** of Jira's answer, up to 1000 issues. Past that, the card says
**Showing the first 1000 issues: Jira holds more. Narrow the query to see the rest.** above the table.

*The **Estimate** column was checked on an issue without estimate (a dash). The story points and the
time estimate were not checked on an instance.*

## 🧩 Show or hide a column

1. On **My Dashboards**, open the tab of the dashboard.

2. At the top right of the card, click the **More** button, then **Edit**. The window **Edit Card** opens.

3. Open the **Columns** tab. Under **Select columns to display**, you read the nine columns:
   `key`, `type`, `resource`, `title`, `priority`, `status`, `estimate`, `sprint`, `date`.

4. Tick **status**, **estimate** or **sprint** to show the column. Untick a column to hide it.

5. Click **Save**.

The table now has the columns you ticked, in the order above.

## ↕️ Sort by status

1. In the header of the table, click **Status**. The issues are sorted by status, those that are `done`
   first.

2. Click **Status** again. The order is reversed: the issues that are `to do` come first.

The sort applies to all the issues the card read, not only to the page you see. If **Status** is not in
the table, show it first: see [Show or hide a column](#-show-or-hide-a-column).

## ↕️ Sort by priority

1. In the header of the table, click **Priority**. The issues are sorted in Jira's order: `Highest`,
   `High`, `Medium`, `Low`, `Lowest`.

2. Click **Priority** again. The order is reversed: the `Lowest` issues come first.

A priority your Jira administrator created comes after `Lowest`. An issue without priority comes last.
The sort applies to all the issues the card read, not only to the page you see.

## My Open Issues

The open issues assigned to you, most recently updated first.

## My Sprint

The Jira issues assigned to you in the sprint that is running, with the name of the sprint in the
**Sprint** column.

When your Jira has no sprint running (a Kanban project has none), the card says:

`No sprint is running: your Jira has no active sprint (a Kanban project has none). Use « My Open Issues » to see your work.`

Add a **My Open Issues** card to see your work in that case.

*The list of a running sprint was not checked on an instance: the Jira used for this page had no sprint
running.*

## To Review

The issues where you are reviewer or mentioned. With none, the card says **Nothing here yet** and **No Jira issue is waiting for your approval.**

## JQL Query

The issues returned by the JQL query you wrote in the **jql** field when you added the card. Some
examples to copy:

| You want | jql |
| --- | --- |
| All the issues of a project, whoever they are assigned to | `project = SHOP ORDER BY updated DESC` |
| The open issues of a project | `project = SHOP AND statusCategory != Done ORDER BY updated DESC` |
| What is assigned to you | `assignee = currentUser() ORDER BY created DESC` |

To change the query later, see below.

## Change what a card shows

1. On **My Dashboards**, open the tab of the dashboard.

2. At the top right of the card, click the **More** button, then **Edit**. The **Edit Card** window has three tabs:

   | Tab | What you do |
   | --- | --- |
   | **General** | Rename the card, change its icon, and for **JQL Query** change the **jql** field |
   | **Columns** | Show or hide a column |
   | **Filters** | Remove a status or a project from the list, so its rows disappear |

3. Click **Save**.

The same menu has **Refresh**, to read Jira again now (see [Read a card's source again](../../../../developer-dashboard/my-dashboard/refresh-a-card.md)), and **Delete**.

✅ That's it!

Next: [Get Jira notifications](get-notifications.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/launchdarkly/add-the-integration.md -->

# Add the LaunchDarkly integration

The integration gives Astrolabe the address of the LaunchDarkly API and an access token. The card of **Administration › Company
connections** describes it as **The feature flags of an entity, from LaunchDarkly.**

You do it once, as an administrator.

## Before you start

You need a LaunchDarkly API access token with the **reader** role. In LaunchDarkly, you create it under
**Organization settings › Authorization**. This step was not checked on a live instance.

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **LaunchDarkly** card, click **Configure**.

4. Top right, click **Add Token**.

5. In **API URL**, keep `https://app.launchdarkly.com/api`. It is already filled in.

6. In **LaunchDarkly token**, paste the access token.

7. Click **Test connection**. The form says: **Connection works: the source accepted the
   credentials.**

8. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list, with **Administration** in the **Source** column.

✅ That's it!

Next: [Show the LaunchDarkly tab on a component](show-on-a-component.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/launchdarkly/show-on-a-component.md -->

# Show the LaunchDarkly tab on a component

Components get a **LaunchDarkly** tab: their feature flags. The card of **Administration › Plugins** says:
**Feature flags of an entity, read through the proxy.**

Three steps: turn on the plugin, give it the address and the key of LaunchDarkly, annotate the component.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **LaunchDarkly** card, click the switch **Enable LaunchDarkly**.

## 2. 🔧 Give the plugin the address and the key

1. On the **LaunchDarkly** card, click **Configure**. The **Settings** page of the plugin opens.

2. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **API URL** | The LaunchDarkly API root, with `https://` | `https://app.launchdarkly.com/api` |
   | **API key** | The API key LaunchDarkly expects. It stays in the backend: the browser never talks to LaunchDarkly. | |

3. Click **Save**. The message **Settings saved.** appears at the bottom left of the screen and goes away by itself. The page says **The configuration has changed.**

4. Click **Reload**. The instance restarts; wait a few seconds. The fields stay filled, and the API key shows as `XXXXXXXXXXXX`.

## 3. 🏷️ Annotate the component

In the component's `catalog-info.yaml`, name the LaunchDarkly project:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    launchdarkly.com/project-key: shop-api   # the project key in LaunchDarkly
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
```

## ✅ Check

Open the component from **Catalog**: the **LaunchDarkly** tab is after **Docs**. Once the settings are saved,
the tab no longer says **LaunchDarkly is not configured yet**; it asks LaunchDarkly for the flags. What the tab
shows when LaunchDarkly accepts the key was not checked on a live instance.

✅ That's it!

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/launchdarkly/troubleshooting.md -->

# Common problems with LaunchDarkly

## When you add the integration

| What you see | What to do |
| --- | --- |
| `The field "API URL" is required.` | Type `https://app.launchdarkly.com/api` in **API URL**. |
| `API URL must be a full address starting with https://, for example https://app.launchdarkly.com/api.` | The address lacks `https://`. Type `https://app.launchdarkly.com/api` in **API URL**. |
| `The field "LaunchDarkly token" is required.` | Paste the access token in **LaunchDarkly token**. |
| `app.launchdarkly.com refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong or expired. Create a new token with the **reader** role in LaunchDarkly and paste it. |

## When the license does not cover LaunchDarkly

| What you see | What to do |
| --- | --- |
| In **Administration › Plugins**, the **LaunchDarkly** card says **Requires the Premium license**, and **Configure** is grey | LaunchDarkly is part of the Premium license. Click the line, [add a license](../../../../administration/licensing/add-your-license.md) that covers it, then switch the plugin on. |
| On the **LaunchDarkly** tab of a component, `Your license does not cover LaunchDarkly.` or `The license could not be checked.` | Add a license that covers LaunchDarkly in **Administration › Licensing**, or try again in a minute. *Not verified on an instance yet: the tab is not shown once the license no longer covers LaunchDarkly.* |

## On the LaunchDarkly tab of a component

| What you see | What to do |
| --- | --- |
| `LaunchDarkly is not configured yet` `This plugin is running but has nothing to show until it is configured from the administration.` `Missing or invalid: API URL, API key` | Click **Open the LaunchDarkly settings**, fill in **API URL** and **API key**, click **Save**, then **Reload**. |
| `LaunchDarkly refused the API key.` `The key may have expired, been revoked or lack read access: enter a valid one in the LaunchDarkly settings.` | Click **Open the LaunchDarkly settings**, paste a valid **API key**, click **Save**, then **Reload**. Then check that the component has its `launchdarkly.com/project-key` annotation. |

## After you add the integration

| What you see | What to do |
| --- | --- |
| On the **LaunchDarkly** card of **Company connections**, **Not working** | Click **Manage**. The **State** column says why: for example `app.launchdarkly.com refused the credentials (401). Check the token, and that it has not expired.` Click **Edit Token** and paste a new token. |
| In **Administration › Problems**, a **Company connection** line **LaunchDarkly**: `app.launchdarkly.com refuses the credentials (401). The token may be wrong or expired.` | Click **Fix it**: it opens the integration. Paste a new token. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/sonarqube/add-the-integration.md -->

# Add the SonarQube integration

The integration gives Astrolabe the address of your SonarQube and its token. You do it once, as an
administrator.

**Before you start**: a SonarQube user token, see [Create a SonarQube token](create-a-token.md).

## How to

### 1. Open the SonarQube integration

1. In the left sidebar, at the bottom, click **Administration**.
2. Under **PLATFORM**, click **Company connections**.
3. On the **SonarQube** card, click **Configure**.
4. Top right, click **Add Token**.

### 2. Fill in the form

| Field | What to enter | Example |
| --- | --- | --- |
| **Name** | A name of your choice | `SonarQube` |
| **SonarQube base URL** | The address of SonarQube, with `https://` | `https://sonar.example.com` |
| **SonarQube API Key** | The token you created | |

### 3. Test and save

1. Click **Test connection**. The form says **Connection works: the source accepted the
   credentials.**
2. Click **Add**. Astrolabe restarts on its own, in a few seconds.

The token is in the list, with **State** set to **Connected**.

✅ Done. Next: [Show SonarQube on a component](show-on-a-component.md).

## You have several SonarQube

Add one integration per SonarQube, and give each one an **instance key**.

1. Repeat the steps above for each SonarQube.
2. In the form, open **Optional settings** and fill in **SonarQube instance key** with a short name:
   letters, digits, `.`, `_` and `-`.

| SonarQube | Name | SonarQube instance key |
| --- | --- | --- |
| Production | `SonarQube prod` | `prod` |
| Other environments | `SonarQube dev` | `dev` |

A component then picks its SonarQube in its annotation: see
[Show SonarQube on a component](show-on-a-component.md#you-have-several-sonarqube).

:::tip The default SonarQube
A project key without an instance key is read from the integration whose instance key is
`default`, otherwise from the first one in the list.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/sonarqube/create-a-token.md -->

# Create a SonarQube token in 2 minutes

Astrolabe reads SonarQube with a user token. You create it once, in SonarQube.

## How to

### 1. Log in with the right user

Log in to SonarQube with the user Astrolabe will read with. Astrolabe sees exactly the projects this
user can browse.

:::tip Use a dedicated user
Create a SonarQube user named `astrolabe`, with the **Browse** permission on your teams' projects.
Astrolabe keeps working when people leave.
:::

### 2. Generate the token

1. Top right, click your avatar, then **My Account**.
2. Open the **Security** tab.
3. Under **Generate Tokens**, fill in:
   - **Name**: `Astrolabe`
   - **Type**: **User Token**
   - **Expires in**: the date of your choice
4. Click **Generate**.

### 3. Copy the token

Copy the token right away: SonarQube shows it only once.

:::tip Write down the expiry date
Put it in your calendar. That day, generate a new token and paste it in the integration.
:::

✅ Done. Next: [Add the SonarQube integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/sonarqube/faq.md -->

# SonarQube FAQ

## Which token?

A SonarQube **User Token**, of a user with the **Browse** permission on your projects. See
[Create a SonarQube token](create-a-token.md).

## Who sees the code quality?

Anyone who can open the component. Astrolabe reads SonarQube with the token of the integration,
the same for every reader.

## I have several SonarQube. How does a component pick one?

By the start of its annotation: `sonarqube.org/project-key: prod/acme-shop-api` reads the project
`acme-shop-api` from the integration whose **SonarQube instance key** is `prod`. See
[Show SonarQube on a component](show-on-a-component.md#you-have-several-sonarqube).

## Does it work with SonarQube Cloud?

Yes: enter `https://sonarcloud.io` in **SonarQube base URL**.

## Does Compass use the same integration?

Yes. Compass reads the same integrations and the same annotation.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/sonarqube/show-on-a-component.md -->

# Show SonarQube on a component

Each annotated component shows its code quality: a **Code Quality** card on its **Overview**, and a
**SonarQube** tab.

## How to

### 1. Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.
2. On the **SonarQube** card, turn on the **Enable SonarQube** switch.

If the card says **Configure the SonarQube integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the SonarQube integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.

### 2. Annotate the component

In the component's `catalog-info.yaml`, add the key of its SonarQube project:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    sonarqube.org/project-key: acme-shop-api
spec:
  type: service
  lifecycle: production
  owner: team-a
```

:::tip Where is the project key?
In SonarQube, open the project, then **Project Information**: it is the **Project Key**.
:::

### 3. Check

Open the component in **Catalog**:

- on **Overview**, the **Code Quality** card shows the quality gate, **Bugs**, **Vulnerabilities**,
  **Code Smells**, **Hotspots Reviewed**, **Coverage** and **Duplications**;
- the **SonarQube** tab shows the same figures.

✅ Done.

## You have several SonarQube

Start the annotation with the **instance key** of the integration, then `/`, then the project key:

```yaml
metadata:
  annotations:
    sonarqube.org/project-key: prod/acme-shop-api
```

Here, `prod` is the **SonarQube instance key** of the production SonarQube integration.

## What it shows, and to whom

Anyone who can open the component sees its code quality. Astrolabe reads SonarQube with the token
of the integration, the same for every reader.

Something is wrong? See [Common problems with SonarQube](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/sonarqube/troubleshooting.md -->

# Common problems with SonarQube

## When you add the integration

| What you see | What to do |
| --- | --- |
| `sonar.example.com refused the credentials (401). Check the token, and that it has not expired.` | Create a new **User Token**: see [Create a SonarQube token](create-a-token.md). |
| `No server answers to the name sonar.example.com. Check its spelling against the address you open in your browser. If it is right, Astrolabe cannot see this server: tell your company's Astrolabe administrator.` | Copy the address from your browser into **SonarQube base URL**. |

## On the component page

| What you see | What to do |
| --- | --- |
| No **SonarQube** tab, no **Code Quality** card | Add the `sonarqube.org/project-key` annotation to the component, and turn on **Enable SonarQube** in **Administration › Plugins**. |
| `SonarQube is not set up yet. Add a SonarQube integration in Administration › Company connections › SonarQube, then switch the SonarQube plugin on in Administration › Plugins.` | Do what the message says: [add the integration](add-the-integration.md). |
| `The default SonarQube has no project with the key "acme-shop-api". Check the sonarqube.org/project-key annotation of this component.` | Copy the **Project Key** from SonarQube, **Project Information**, into the annotation. |
| `The default SonarQube refused the token of its integration. Replace the token in Administration › Company connections › SonarQube.` | The token has expired or was revoked: [create a new one](create-a-token.md) and paste it in the integration. |
| `The SonarQube "prod" refuses to show the project "acme-shop-api" to the token of its integration. In SonarQube, give the user of this token the Browse permission on the project.` | In SonarQube, give the **Browse** permission on the project to the token's user. |
| `No SonarQube integration has the instance key "prod" that this component's sonarqube.org/project-key annotation starts with. Use the instance key of one of your SonarQube integrations (Administration › Company connections › SonarQube), or remove "prod/" to read from the default SonarQube.` | Write in the annotation the **SonarQube instance key** of one of your integrations, or remove `prod/`. |
| `The default SonarQube has no analysis of the project "acme-shop-api" yet. Run an analysis, then reload this page.` | Run an analysis of the project in your CI, then reload the page. |
| `The default SonarQube could not be read (no answer). Check the SonarQube base URL in Administration › Company connections › SonarQube.` | Check **SonarQube base URL** in the integration, then **Test connection**. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and the message you see.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/terraform/add-the-integration.md -->

# Add the Terraform Cloud integration

The integration gives Astrolabe the address of Terraform Cloud (or of your Terraform Enterprise) and a
token to read it. It feeds the **Terraform** tab of your components.

You do it once, as an administrator.

## Before you start

You need an API token: see [Create a Terraform Cloud API token](create-a-token.md).

## 🔧 Add the integration

1. In the left sidebar, at the bottom, click **Administration**.

2. Under **PLATFORM**, click **Company connections**.

3. On the **Terraform Cloud** card, click **Configure**.

4. Top right, click **Add Token**.

5. Fill in the form:

   | Field | What to enter | Example |
   | --- | --- | --- |
   | **Name** | A name for you | `Terraform Cloud` |
   | **Terraform Cloud address** | The web address, **with** `https://`. It already reads `https://app.terraform.io`: change it only for your own Terraform Enterprise | `https://app.terraform.io` |
   | **API token (user or team token)** | The API token | |

6. Click **Test connection**. The form says **Connection works: the source accepted the credentials.**

7. Click **Add**. The form warns: **The instance will restart after confirmation.** Wait a few
   seconds.

The token is in the list, with **State** set to **Connected**. On **Company connections**, the **Terraform
Cloud** card says **Connected** and its button reads **Manage**.

✅ That's it!

Next: [Show the Terraform tab on a component](show-the-tab.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/terraform/create-a-token.md -->

# Create a Terraform Cloud API token

Astrolabe reads Terraform Cloud with **an API token**. The token has **the rights of its owner**:
Astrolabe only sees the workspaces this owner can see, and it only reads them.

You create the token once, in Terraform Cloud.

:::tip Use a dedicated user
Create a Terraform Cloud user for Astrolabe and give it read access to the workspaces your components
name. Your own token works too, but Astrolabe stops working the day your access ends.
:::

## 🔑 Create the token

1. In Terraform Cloud, log in with this user.

2. Open **User settings**, then **Tokens**.

3. Click **Create an API token**.

4. Give it a description, for example `Astrolabe`, then confirm.

5. **Copy the token now.** Terraform Cloud never shows it again.

These steps happen in Terraform Cloud. They were not checked on a live instance.

✅ That's it!

Next: [Add the Terraform Cloud integration](add-the-integration.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/terraform/faq.md -->

# Terraform Cloud FAQ

## Which token?

A Terraform Cloud **user or team API token**. See
[Create a Terraform Cloud API token](create-a-token.md).

## Does it work with Terraform Enterprise?

Yes, the address is a field of the form: enter the address of your Terraform Enterprise in **Terraform Cloud
address**. *Not verified on an instance yet.*

## Do I enter Terraform Cloud twice?

No. The **Terraform** plugin card has no settings. The address and the token are entered once, in
**Administration › Company connections**.

## Who sees the Terraform tab?

Anyone who can open the component. Astrolabe reads Terraform Cloud with the token of the integration, the
same for every reader.

## The tab is missing on a component. Why?

The tab only exists on a component with **both** `terraform/organization` and `terraform/workspaces`, when the
**Terraform** plugin is turned on. See [Show the Terraform tab](show-the-tab.md).

## Can a component show several workspaces?

Yes: separate their names with commas in `terraform/workspaces`.

## Is there a card for My Dashboards?

No. Terraform Cloud only feeds the tab.

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/terraform/show-the-tab.md -->

# Show the Terraform tab on a component

Each annotated component gets a **Terraform** tab: the Terraform Cloud workspaces it names, and their last
runs.

Two steps: turn on the plugin, annotate the component.

## What the tab shows, and to whom

The Terraform Cloud workspaces named by the component, each with its last runs. Anyone who can open the
component sees the tab. Astrolabe reads Terraform Cloud with **the token of the integration**, the same for
everyone.

## 1. 🔌 Turn on the plugin

1. In **Administration**, under **PLATFORM**, click **Plugins**.

2. On the **Terraform** card, turn on the switch at the top right.

If the card says **Configure the Terraform integration first**, click it: the integration opens in
**Company connections**. Add it ([Add the Terraform integration](add-the-integration.md)). The plugin turns on by itself when you
save the integration: go to step 2.

The card has no settings: Terraform Cloud is entered once, in
[the integration](add-the-integration.md).

## 2. 🏷️ Annotate the component

In the `catalog-info.yaml` file of the component, add **both** annotations:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
  annotations:
    terraform/organization: acme
    terraform/workspaces: shop-api,shop-api-staging
spec:
  type: service
  lifecycle: production
  owner: team-a
```

| Annotation | What to write | Example |
| --- | --- | --- |
| `terraform/organization` | The name of your Terraform Cloud organization | `acme` |
| `terraform/workspaces` | The names of the workspaces, separated by commas | `shop-api,shop-api-staging` |

## ✅ Check

Open the component in **Catalog**. A **Terraform** tab is in the tab bar, next to **Overview**. Click it: each
workspace is listed with its last runs.

The list of runs was not checked on a live instance.

✅ That's it!

Something is wrong? See [Common problems with Terraform Cloud](troubleshooting.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/Configuration/Integration/terraform/troubleshooting.md -->

# Common problems with Terraform Cloud

## When you add the integration

| What you see | What to do |
| --- | --- |
| `app.terraform.io refused the credentials (401). Check the token, and that it has not expired. Fix the field above, or save anyway if the source is only unreachable for now.` | The token is wrong, expired or deleted. Create a new one: see [Create a Terraform Cloud API token](create-a-token.md). |

## On the Terraform tab of a component

| What you see | What to do |
| --- | --- |
| No **Terraform** tab | Add **both** the `terraform/organization` and `terraform/workspaces` annotations to the component, and turn on the **Terraform** plugin in **Administration › Plugins**. |
| `The workspace acme/shop-api cannot be reached with the Terraform token: check the terraform/organization and terraform/workspaces annotations, or the token access.` | Check the organization and the workspace names in the annotations, and that the owner of the token can read this workspace in Terraform Cloud. |

## When the tab says a module is missing

| What you see | What to do |
| --- | --- |
| `Astrolabe does not offer this Terraform feature on this instance.` and `A module is missing from this Astrolabe installation. Tell your Astrolabe administrator.` | The integration may be connected and the plugin on, but this installation of Astrolabe lacks the module that serves Terraform. Tell your Astrolabe administrator. Nothing to change on the component. |

*Not verified on an instance yet: this message needs an installation that lacks the module.*

:::tip Still stuck?
Write to **support@forgeit.fr** with the name of the component and its Terraform Cloud workspace.
:::

---

<!-- https://doc.forgeit.fr/docs/getting-started/configure-astrolabe.md -->

# Configure Astrolabe

Your Astrolabe is installed and new. (Not installed yet? See [Install Astrolabe](install-astrolabe.md).) Follow these steps in order, as the administrator: at the end, your teams sign
in, find their components and see their tools.

## Before you start

You need the address of your Astrolabe, and the administrator username and password.

## 🚀 The steps

1. **Sign in as the administrator.** See
   [Sign in with your Astrolabe account](Configuration/Authentication/astrolabe-account/sign-in.md).

2. **Add your license**, in **Administration › Licensing**. See
   [Add your license](../administration/licensing/add-your-license.md).

3. **Choose how people sign in**, in **Administration › Authentication**. See
   [Choose how people sign in](Configuration/Authentication/authentification.md).

4. **Connect your tools** (GitHub, GitLab, Jira, Argo CD…), in **Administration › Company
   connections**. See [Integrations](Configuration/Integration/integration.md).

5. **Fill the catalog**, in **Administration › Catalog**. See
   [Choose what the catalog imports](../administration/catalog/choose-what-the-catalog-imports.md).

6. **Turn on the plugins** your teams use, in **Administration › Plugins**. See
   [Turn on a plugin](../administration/plugins/turn-on-a-plugin.md).

7. **Check that nothing is wrong**, in **Administration › Problems**. See
   [Find and fix a problem](../administration/problems/find-and-fix-a-problem.md).

✅ That's it! Your teams can sign in.

Next, for everyone: [Browse the catalog](../core-features/catalog/browse-the-catalog.md).

---

<!-- https://doc.forgeit.fr/docs/getting-started/install-astrolabe.md -->

# Install Astrolabe

There are two ways to have Astrolabe. Pick one, then [configure it](configure-astrolabe.md).

| | **SaaS** | **On-prem** |
| --- | --- | --- |
| Who runs it | ForgeIT hosts it for you | You run it in your infrastructure |
| What you receive | An address and an administrator account | The Astrolabe image and the files below |
| Your data | Hosted by ForgeIT | Stays in your PostgreSQL |

## ☁️ SaaS: we host it for you

1. Ask for your instance on the ForgeIT website: [www.forgeit.fr](https://www.forgeit.fr).

2. You receive the address of your Astrolabe and the administrator username and password.

✅ That's it! Go to [Configure Astrolabe](configure-astrolabe.md).

## 🏢 On-prem: in your infrastructure

You need Docker running on the machine, with 8 GB of memory given to Docker, and the name of the
Astrolabe image, which ForgeIT gives you with your license. See [Contact us](#-contact-us).

1. Create an empty folder and save this file in it as `docker-compose.hub.yml`.

   ```yaml
   name: astrolabe-hub

   services:
     postgres:
       image: postgres:14-alpine
       command: postgres -c max_connections=300
       environment:
         POSTGRES_USER: ${POSTGRES_USER:-backstage}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-backstage}
       volumes:
         - astrolabe-postgres:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-backstage}"]
         interval: 5s
         timeout: 5s
         retries: 10

     astrolabe:
       image: ${ASTROLABE_IMAGE:?set ASTROLABE_IMAGE}
       container_name: astrolabe-hub
       depends_on:
         postgres:
           condition: service_healthy
       ports:
         - "${ASTROLABE_PORT:-7007}:7007"
       environment:
         ENVIRONMENT: production
         FRONTEND_BASE_URL: http://127.0.0.1:${ASTROLABE_PORT:-7007}
         BACKEND_BASE_URL: http://127.0.0.1:${ASTROLABE_PORT:-7007}
         POSTGRES_HOST: postgres
         POSTGRES_PORT: 5432
         POSTGRES_USER: ${POSTGRES_USER:-backstage}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-backstage}
         ADMIN_USERNAME: ${ADMIN_USERNAME:-administrator}
         ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@astrolabe.local}
         ADMIN_PASSWORD: ${ADMIN_PASSWORD:-astrolabe}
         BACKEND_SECRET: ${BACKEND_SECRET:-local-only-change-me-before-sharing}
         ORGANIZATION_NAME: ${ORGANIZATION_NAME:-Astrolabe}

   volumes:
     astrolabe-postgres:
   ```

2. In a terminal opened in that folder, give the image name and start Astrolabe. Replace the value with the
   name you received.

   ```bash
   export ASTROLABE_IMAGE=<the image name you received>
   docker compose -f docker-compose.hub.yml up -d
   ```

   The first start downloads the image, then prepares the database: allow two to three minutes.

3. Open `http://127.0.0.1:7007`. Use this address, not `localhost`: the sign-in compares the address you
   open with the one in the file.

4. Sign in with the username `administrator` and the password `astrolabe`.

5. Before you share this Astrolabe, change the password and the secret. Put them in a `.env` file next to
   `docker-compose.hub.yml`, then start again with the same command as step 2.

   ```text
   ADMIN_PASSWORD=<a password only you know>
   BACKEND_SECRET=<a long random text>
   ```

   :::tip
   Choose `BACKEND_SECRET` before you configure anything. It encrypts the secrets you enter in
   Administration: changing it afterwards makes them unreadable.
   :::

✅ That's it! Go to [Configure Astrolabe](configure-astrolabe.md).

To stop Astrolabe, run `docker compose -f docker-compose.hub.yml down`. Your data stays. To start again,
run the command of step 2.

## 🧪 Try it in one command

To look around before you decide, start a demo on sample data, without PostgreSQL:

```bash
docker run --rm -p 7007:7007 --tmpfs /run/astrolabe-db -e DEMO_MODE=true -e ASTROLABE_DEMO_OPEN=true "$ASTROLABE_IMAGE"
```

Open `http://localhost:7007` and click **Start as a guest**. The demo is read-only and everything disappears
when you stop the container.

The public demo of ForgeIT works differently: you ask for access first. See
[Ask for access to the demo](request-demo-access.md).

## 📞 Contact us

- **Ask for a demo or an instance:** [www.forgeit.fr](https://www.forgeit.fr)
- **Talk to sales:** [www.forgeit.fr](https://www.forgeit.fr)
- **Already a customer, you need help:** write to **support@forgeit.fr**.

## ➡️ Next

[Configure Astrolabe](configure-astrolabe.md): sign in, add your license, connect your tools and fill the
catalog.

---

<!-- https://doc.forgeit.fr/docs/getting-started/request-demo-access.md -->

# Ask for access to the demo

The public Astrolabe demo is open by invitation. You give your address, ForgeIT approves it, and you
enter with a code or with the button of an e-mail. This page takes you from the sign-in page to the
demo.

## 🙋 Ask for access

1. Open the address of the demo.

2. On the sign-in page, click **Start as a guest**.

3. In **Email**, type your address, then click **Access the demo**.

   If your address is already approved, go to [Enter the demo](#-enter-the-demo).

4. The page says **This address is not allowed in the demo yet. Ask for access: we answer by email.**
   Fill in **First name** and **Last name**. **Company (optional)** can stay empty.

5. Tick the box **I agree that my visit is recorded and that you may contact me. Kept 12 months.**

6. Click **Get a code**.

7. Open the e-mail **Confirm your access request** that reaches your mailbox. Copy the 6-digit code.

8. Back on the page, type the code in **Code**, then click **Confirm my request**.

The page says **Your request is sent. You will receive an email as soon as it is approved.**

✅ That's it! When ForgeIT approves your request, you receive the e-mail **Your access to the Astrolabe demo is open**.

## 🚪 Enter the demo

From the approval e-mail:

1. In the e-mail **Your access to the Astrolabe demo is open**, click **Enter the demo**.

You land on **My dashboards**, signed in as a guest with your address. The button works once and for 7 days.

From the sign-in page, when the button is used or expired:

1. Open the address of the demo, then click **Start as a guest**.

2. In **Email**, type your approved address, then click **Access the demo**.

3. Open the e-mail **Your sign-in code for the Astrolabe demo**. Click **Enter the demo** in it, or copy the
   6-digit code.

4. If you copied the code, type it in **Code**, then click **Enter the demo**.

The code and the button of this e-mail are valid for 10 minutes.

## ❓ Frequently asked questions

### Who sees my address?

ForgeIT. Your visit to the demo is recorded and linked to your address, to tailor a demonstration and to
contact you. It is kept 12 months after your last visit and erased on request: write to
**support@forgeit.fr**.

### Can I change what I see in the demo?

No. The demo is a read-only guest session on sample data.

### How do I try Astrolabe on my own machine?

See [Try it in one command](install-astrolabe.md#-try-it-in-one-command).

## 🛠️ Troubleshooting

| What you see | What to do |
| --- | --- |
| **This address is not allowed in the demo yet. Ask for access: we answer by email.** | Your address is not approved. [Ask for access](#-ask-for-access), then wait for the approval e-mail. |
| **This code is not the right one. Check it and try again.** | Type the code of the most recent e-mail, six digits, without spaces. |
| **This code has expired. Go back and ask for a new one.** | Click **Back to sign-in**, then start again from **Start as a guest**. The code is valid for 10 minutes. |
| **A code was just sent. Wait a minute before asking for another.** | Wait one minute, then click again. Use the code of the first e-mail if it has arrived. |
| **The demo cannot check accesses right now. Try again in a few minutes.** | Nothing is wrong with your address. Try again in a few minutes. If it lasts, write to **support@forgeit.fr**. |
| **This link has already been used. Enter your address: we send you a code.** | The button of an e-mail works once. Type your address and use the code. |
| **This link has expired. Enter your address: we send you a new code.** | Type your address: a new code arrives. |
| **The anti-robot check failed. Reload the page and try again.** | Reload the page, then start again. |
| **The email could not be sent. Try again in a few minutes.** | Try again in a few minutes. |
| No e-mail arrives | Look in your spam folder for a message from **Astrolabe by Forge IT**. Check the spelling of the address you typed, then ask for a new code after one minute. |

:::tip Still stuck?
Write to **support@forgeit.fr** with the address you typed and what the screen says.
:::

## ➡️ Next

The people who approve requests follow [Manage access to the demo](../administration/demo-access/manage-demo-access.md).

---

<!-- https://doc.forgeit.fr/docs/intro.md -->

# Welcome to the Astrolabe help center

Astrolabe gathers your components, their tools and your team's work in one place. Here you find,
task by task, how to set it up and how to use it.

## Where to start?

**You set up Astrolabe for your company**

Sign in as the administrator, choose how people sign in, connect your tools and fill the catalog.

➡️ [Install Astrolabe](getting-started/install-astrolabe.md), then [Configure Astrolabe](getting-started/configure-astrolabe.md)

**You use Astrolabe every day**

Find a component, follow your work on your dashboard, and choose what Astrolabe tells you.

- [Browse the catalog](core-features/catalog/browse-the-catalog.md)
- [Add a card to your dashboard](developer-dashboard/my-dashboard/add-a-card.md)
- [Choose your notifications](developer-dashboard/notifications/choose-your-notifications.md)
- [Connect your own accounts](core-features/my-account/connect-my-accounts.md)
- [Switch Astrolabe to French or English](core-features/my-account/choose-language-and-theme.md)

**Something does not work**

Each topic has a **Common problems** page: find the message you see on the screen, and what to do.
For an administrator, start with [Find and fix a problem](administration/problems/find-and-fix-a-problem.md).

**You work with an AI assistant**

[Use this documentation with your AI assistant](use-with-an-ai-assistant.md).

:::tip From Astrolabe
The **?** next to the name of a plugin, an integration or a dashboard card opens its page here.
:::

:::tip Still stuck?
Write to **support@forgeit.fr**.
:::

---

<!-- https://doc.forgeit.fr/docs/use-with-an-ai-assistant.md -->

# Use this documentation with your AI assistant

Your assistant (Claude Code, Cursor, Codex…) can configure Astrolabe with you, write the
`catalog-info.yaml` of a component, and explain a message of the screen. It reads this
documentation, not what it believes it knows.

## 🤖 Install the Astrolabe skills

1. Open a terminal in the repository you work on.

2. Run the command of your assistant.

   With **Claude Code**:

   <SkillsCommand agent="claude-code" />

   With **Cursor**:

   <SkillsCommand agent="cursor" />

   The command ends with **Done!** and lists the three skills it installed:

| Skill | What your assistant does with it |
| --- | --- |
| **astrolabe-configure** | Connects a tool, a catalog source or a sign-in provider, step by step |
| **astrolabe-annotate** | Writes the annotations that show a tab on a component |
| **astrolabe-troubleshoot** | Finds the cause of a message you see on the screen, and the fix |

✅ That's it!

## 📄 Give a page to your assistant

Every page of this documentation also exists as plain Markdown: add `.md` at the end of its
address. The map of all pages is <SiteAddress path="/llms.txt" />, and every page in one file is
<SiteAddress path="/llms-full.txt" />.

:::tip
Ask your assistant to read the page first: « Read the Argo CD pages of the Astrolabe documentation,
then add the integration with me. »
:::